ValidationKiểm tra Spec
Validation runs in two layers. Scripts catch anything answerable by parsing YAML, walking the graph, or counting fields — deterministically, with no LLM involved. The LLM layer runs second and judges only what requires reading prose and weighing meaning. Neither layer can substitute for the other.Validation chạy theo hai lớp. Script bắt mọi thứ có thể trả lời bằng cách phân tích YAML, duyệt đồ thị, hoặc đếm trường — tất định, không có LLM tham gia. Lớp LLM chạy sau và chỉ nhận định những gì đòi hỏi đọc văn xuôi và cân nhắc ý nghĩa. Không lớp nào có thể thay thế lớp kia.
Operating Principle 3 — the split is non-negotiableNguyên lý Vận hành 3 — sự phân tách này không thương lượng được
If a check can be answered by walking graph edges or counting items, it belongs in a script. If it needs to understand the words, it belongs in the LLM layer. This rule is enforced — any heuristic in a script that judges prose quality must be removed.Nếu một kiểm tra có thể trả lời bằng cách duyệt cạnh đồ thị hoặc đếm item, nó thuộc về script. Nếu cần hiểu ngôn ngữ, nó thuộc về lớp LLM. Quy tắc này được cưỡng chế — bất kỳ heuristic nào trong script mà nhận định chất lượng văn xuôi đều phải bị xóa.
Script layer — structuralLớp script — cấu trúc
Runs check_traceability.py, check_consistency.py, build_traceability_matrix.py, spec_graph.py. Each emits a findings JSON and exits 0 — the orchestration layer reads severities.Chạy check_traceability.py, check_consistency.py, build_traceability_matrix.py, spec_graph.py. Mỗi cái phát ra findings JSON và exit 0 — lớp điều phối đọc severity.
LLM layer — judgmentLớp LLM — nhận định
Runs after scripts. Reads prose, weighs meaning, and checks alignment. Two anchored checks (time_realism, competitive_drift) are pinned to script-precomputed numbers so the LLM cannot hallucinate.Chạy sau script. Đọc văn xuôi, cân nhắc ý nghĩa và kiểm tra tương thích. Hai kiểm tra có neo (time_realism, competitive_drift) được ghim vào số script đã tính trước để LLM không ảo giác.
Errors block with --strict; warns are always advisoryError chặn khi dùng --strict; warn luôn là tư vấn
The check catalog has two severity levels in the validate gate. advisory exists only for the out-of-gate time_advisory.py (overdue) which consumes the wall clock and is never part of the reproducible gate.Danh mục kiểm tra có hai mức severity trong gate validate. advisory chỉ tồn tại cho time_advisory.py ngoài gate (quá hạn) — nó đọc đồng hồ thực và không bao giờ là phần của gate tái tạo được.
| Check IDCheck ID | OwnerChủ | SevMức | What triggers itĐiều kích hoạt |
|---|---|---|---|
orphan_story | scriptscript | errorerror | Story with no epic fieldStory không có trường epic |
orphan_epic | scriptscript | errorerror | Epic with no prd fieldEpic không có trường prd |
dangling_link | scriptscript | errorerror | Any frontmatter ID reference that doesn't resolveBất kỳ tham chiếu ID trong frontmatter không giải được |
missing_ac | scriptscript | errorerror | Story with empty or missing acceptance_criteriaStory không có acceptance_criteria |
goal_without_metric | scriptscript | errorerror | BRD goal with no metrics slugMục tiêu BRD không có metric slug |
dep_cycle | scriptscript | errorerror | Circular depends_on chainChuỗi depends_on vòng tròn |
contradiction | LLMLLM | errorerror | New claim contradicts an approved artifactKhẳng định mới mâu thuẫn với tài liệu approved |
low_ac_count | scriptscript | warnwarn | Story with fewer than 2 acceptance criteriaStory có ít hơn 2 tiêu chí chấp nhận |
invest_quality | LLMLLM | warnwarn | Story failing an INVEST dimensionStory vi phạm một chiều INVEST |
vagueness | LLMLLM | warnwarn | Unquantified vague language ("fast", "easy")Ngôn ngữ mơ hồ chưa định lượng ("nhanh", "dễ") |
core_value_drift | LLMLLM | warnwarn | Narrative drifts from PRODUCT.md core-value sentenceVăn xuôi lệch khỏi câu core-value trong PRODUCT.md |
unaddressed_parent | scriptscript | warnwarn | Epic or PRD with zero inbound child edgesEpic hoặc PRD không có node con nào |
Example run (illustrative — not captured output):Ví dụ chạy (minh họa — không phải đầu ra thật):
# Validation Report — 2026-06-17 ## Summary - 18 artifacts checked - 0 errors · 2 warnings - Strict gate: ON (errors would block) ## Errors (0) (none) ## Warnings (2) ### PRD-AUTH-E1-S2 — low_ac_count (warn) Story has 1 acceptance criterion. Suggest ≥2. ### PRD-BILLING — core_value_drift (warn — LLM) Alignment: weak — billing flow is tangential to core value. Consider whether this PRD belongs in the next horizon. ## Suggested Next Steps 1. Add ≥1 AC to PRD-AUTH-E1-S2. 2. PRD-BILLING: discuss core-value alignment with stakeholders.
status: approved requires explicit PO sign-off — never automaticstatus: approved cần PO ký duyệt rõ ràng — không bao giờ tự động
--approve runs a full validation first (warns do not block), then checks for unresolved open markers (TBD, cần PO xác định), then records owner + date and flips status: approved. It never sets approved status on the PO's behalf without that explicit confirmation.--approve chạy toàn bộ validation trước (warn không chặn), sau đó kiểm tra các marker còn mở chưa giải quyết (TBD, cần PO xác định), rồi ghi owner + ngày và chuyển status: approved. Không bao giờ đặt trạng thái approved thay cho PO mà không có xác nhận rõ ràng đó.
status: approved without explicit PO approval, an owner name, and a date. Not even for boilerplate. Not even when the PO says "skip asking". The GATE is never waived — the skill proceeds but names the residual risk.
Skill không bao giờ đặt status: approved mà không có xác nhận rõ ràng của PO, tên owner và ngày. Kể cả với boilerplate. Kể cả khi PO nói "bỏ qua hỏi". GATE không bao giờ được miễn — skill tiếp tục nhưng nêu tên rủi ro còn lại.
approval: approved_by: "Jane Doe" approved_at: "2026-06-17" approved_version: "1.0.0"
After a successful sign-off, the skill nudges the PO that --export can produce one shareable copy and --viz can re-render visuals for the approved state. Both are suggestions, never automatic.Sau khi ký duyệt thành công, skill gợi ý PO rằng --export có thể tạo một bản chia sẻ và --viz có thể render lại biểu đồ cho trạng thái approved. Cả hai chỉ là gợi ý, không bao giờ tự động.
Operating Principle 4 — flag, then askNguyên lý Vận hành 4 — gắn cờ, rồi hỏi
When --update computes the downstream change set, it flags affected nodes for the PO's review — it never auto-rewrites them. Regeneration of any prose node is opt-in, per node, after the PO confirms. This applies to validation findings too: a vagueness warn surfaces a suggested rewrite but never applies it.Khi --update tính tập thay đổi downstream, nó gắn cờ các node bị ảnh hưởng để PO xem xét — không bao giờ tự viết lại. Việc tạo lại bất kỳ node văn xuôi nào là opt-in, từng node, sau khi PO xác nhận. Điều này cũng áp dụng cho kết quả validation: warn vagueness gợi ý cách viết lại nhưng không bao giờ tự áp dụng.
What the skill does on a findingSkill làm gì khi có finding
Surface verbatimNêu nguyên văn
Show the existing prose and the finding detail — never paraphrase the PO's words.Hiển thị văn xuôi hiện có và chi tiết finding — không bao giờ diễn giải lại lời PO.
Suggest, don't applyGợi ý, không áp dụng
Offer a concrete improvement if the finding allows it. Mark it clearly as a suggestion.Đề xuất cải thiện cụ thể nếu finding cho phép. Đánh dấu rõ ràng là gợi ý.
Wait for POChờ PO
Only proceed with a change after explicit PO confirmation. No silent edits.Chỉ tiến hành thay đổi sau khi PO xác nhận rõ ràng. Không sửa âm thầm.
Anti-rationalization trapsBẫy tự hợp lý hóa
- "I'll tidy their wording" → Flag, then ask."Tôi sửa lại câu chữ cho gọn" → Gắn cờ, rồi hỏi.
- "The scope is obvious, I'll set it" → Scope is PO's call."Phạm vi rõ ràng rồi, tôi đặt luôn" → Phạm vi là quyết định của PO.
- "It contradicts approved, I'll fix it" → Surface Keep / Change / Hybrid."Nó mâu thuẫn với approved, tôi sửa luôn" → Nêu Keep / Change / Hybrid.