Product Spec Harness
GuidesHướng dẫn
HomeTrang chủ › GuidesHướng dẫn › Decision registerSổ quyết định
Every PO ruling — recorded, never re-litigatedMọi phán quyết của PO — được ghi lại, không tranh luận lại

Decision RegisterSổ Quyết định

DEC-<n> · --decision

When a contradiction with an approved artifact surfaces — or when the PO makes a call that settles a debate — the ruling is recorded as a DEC-<n> entry in docs/product/decisions.md. This is the authoritative home for ruled drift. Downstream artifacts that changed as a result point back with po_ruling_ref: DEC-<n> so the same ground is never covered twice.Khi một mâu thuẫn với tài liệu đã duyệt xuất hiện — hoặc khi PO đưa ra phán quyết chấm dứt tranh luận — phán quyết đó được ghi vào mục DEC-<n> trong docs/product/decisions.md. Đây là nơi lưu trữ có thẩm quyền cho các lệch hướng đã được phán xử. Các tài liệu downstream thay đổi vì phán quyết này trỏ về bằng po_ruling_ref: DEC-<n> để không bao giờ phải đào lại vấn đề cũ.

WHEN A CLAIM CONTRADICTS APPROVEDKHI MỘT KHẲNG ĐỊNH MÂU THUẪN VỚI APPROVED

GATE-NO-SILENT-REVERSAL — surface verbatim, never flipGATE-NO-SILENT-REVERSAL — nêu nguyên văn, không bao giờ tự đảo

A new claim that contradicts an approved artifact is a stop point. The skill does NOT edit the artifact, pick a side, or tidy up the inconsistency. It surfaces the contradiction verbatim and presents exactly three choices to the PO. This gate is always on — it is never waived, even when the PO says "just proceed".Một khẳng định mới mâu thuẫn với tài liệu approved là điểm dừng. Skill KHÔNG sửa tài liệu, không chọn phe, không dọn dẹp mâu thuẫn. Nó nêu mâu thuẫn nguyên văn và đưa ra đúng ba lựa chọn cho PO. Gate này luôn bật — không bao giờ được miễn, kể cả khi PO nói "cứ tiếp tục".

Two ways a decision gets openedHai cách mở một quyết định

Auto-opened by contradictionTự mở khi có mâu thuẫn

--validate or --update detects a contradiction with an approved artifact → GATE fires → PO chooses Keep / Change / Hybrid → ruling recorded as DEC-<n>.--validate hoặc --update phát hiện mâu thuẫn với tài liệu approved → GATE kích hoạt → PO chọn Keep / Change / Hybrid → phán quyết ghi vào DEC-<n>.

PO-direct via --decisionPO ghi thẳng bằng --decision

The PO records a ruling they've already made, without a triggering contradiction — e.g. "we settled the guest-checkout debate, log it." Distinct from --reflect, which recovers decisions that were never logged.PO ghi một phán quyết đã thực hiện, không cần có mâu thuẫn kích hoạt — ví dụ "chúng tôi đã chốt vụ guest-checkout, ghi lại đi." Khác với --reflect, cái đó khôi phục quyết định chưa bao giờ được ghi.

What the skill never doesSkill không bao giờ làm gì

  • Auto-flip an approved artifact based on a contradictionTự đảo tài liệu approved vì mâu thuẫn
  • Invent a DEC-<n> without explicit PO confirmation of the ruling text + rationaleTự bịa một DEC-<n> mà không có xác nhận rõ ràng của PO về nội dung + lý do
  • Re-litigate a decided DEC-<n> on its own initiativeTự mình mở lại tranh luận về DEC-<n> đã phán xử
  • Skip the gate when the PO says "skip asking"Bỏ qua gate khi PO nói "đừng hỏi nữa"
KEEP · CHANGE · HYBRIDGIỮ NGUYÊN · THAY ĐỔI · KẾT HỢP

Three choices — only the PO decidesBa lựa chọn — chỉ PO mới quyết định

When GATE-NO-SILENT-REVERSAL fires, the skill presents the contradiction verbatim and waits. Exactly three choices are offered — no defaults, no hints about which one to pick.Khi GATE-NO-SILENT-REVERSAL kích hoạt, skill trình bày mâu thuẫn nguyên văn và chờ. Đúng ba lựa chọn được đưa ra — không có mặc định, không gợi ý nên chọn cái nào.

KeepGiữ nguyên Change + re-approveThay đổi + duyệt lại HybridKết hợp
What each choice meansÝ nghĩa từng lựa chọn
  • Keep — reject the new claim. The approved artifact is unchanged. The new claim is recorded in DEC-<n> as rejected, with rationale. Giữ nguyên — bác bỏ khẳng định mới. Tài liệu approved không đổi. Khẳng định mới được ghi vào DEC-<n> là bị bác, kèm lý do.
  • Change — accept the new claim. The PO must supply an owner name and date for re-approval. Only then does the skill update the approved artifact and bump approved_version. This is the only path that touches approved content. Thay đổi — chấp nhận khẳng định mới. PO phải cung cấp tên owner và ngày để duyệt lại. Chỉ sau đó skill mới cập nhật tài liệu approved và tăng approved_version. Đây là con đường duy nhất chạm đến nội dung approved.
  • Hybrid — record both the existing and new claim; define a follow-up to reconcile. Neither version is auto-discarded. The tension is preserved and documented until the PO resolves it explicitly. Kết hợp — ghi cả khẳng định hiện tại và mới; xác định một việc theo dõi để hòa giải. Không phiên bản nào bị bỏ tự động. Mâu thuẫn được bảo toàn và ghi lại cho đến khi PO giải quyết rõ ràng.
⚠️
If unsure whether it truly contradicts — ask. Surfacing a contradiction that turns out to be a misread is far safer than silently reversing approved content that was intentional. When in doubt, treat it as a contradiction and surface it. Nếu không chắc có thực sự mâu thuẫn không — hỏi. Nêu ra một mâu thuẫn hóa ra là hiểu nhầm thì an toàn hơn nhiều so với việc âm thầm đảo ngược nội dung approved mang tính chủ ý. Khi nghi ngờ, coi đó là mâu thuẫn và nêu ra.
RECORDED SO IT'S NOT RE-LITIGATEDGHI LẠI ĐỂ KHÔNG TRANH LUẬN LẠI

The register is append-only — one writer, no overwritesSổ chỉ ghi thêm — một người ghi, không ghi đè

All writes go through decision_register.py --append. The file is append-only: prior records are byte-unchanged. Each entry is a ----fenced YAML block plus a ## DEC-<n> heading and a free-text rationale note — the same storage model as the Outcome Register.Tất cả ghi chép đều đi qua decision_register.py --append. File chỉ ghi thêm: các record trước đó không thay đổi byte. Mỗi mục là một khối YAML được đánh dấu --- cộng với tiêu đề ## DEC-<n> và ghi chú lý do tự do — cùng mô hình lưu trữ như Outcome Register.

Decision Register — decisions.mdSổ Quyết định — decisions.md

Authoritative home for ruled drift. Monotonic DEC-<n> IDs; never reused. Downstream artifacts that changed point back via po_ruling_ref: DEC-<n>. View with --decision list; record with --decision.Nơi lưu có thẩm quyền cho các lệch hướng đã phán xử. ID DEC-<n> đơn điệu tăng; không bao giờ tái sử dụng. Các tài liệu downstream thay đổi trỏ về bằng po_ruling_ref: DEC-<n>. Xem bằng --decision list; ghi bằng --decision.

Outcome Register — outcomes.mdSổ Kết quả — outcomes.md

Sister register written by --learn. Records measured outcomes vs BRD goals as OUT-<n> entries. A miss on an approved goal is surfaced to the PO, never auto-edited — same no-silent-reversal guarantee.Sổ chị em được ghi bởi --learn. Ghi kết quả đo lường thực tế so với mục tiêu BRD dưới dạng mục OUT-<n>. miss trên mục tiêu approved được nêu cho PO, không bao giờ tự sửa — cùng đảm bảo không-đảo-ngầm.

Example DEC-1 entry (illustrative — not captured output):Ví dụ mục DEC-1 (minh họa — không phải đầu ra thật):

product-spec --decision list
## DEC-1

---
id: DEC-1
ruling: change
artifact: PRD-CHECKOUT
contradiction: "New claim sets scope: out; existing approved says scope: core-value."
choice: Change
re_approved_by: "Jane Doe"
re_approved_at: "2026-06-17"
re_approved_version: "1.1.0"
rationale: >
  Guest checkout removed from core-value after competitive analysis showed
  no differentiation vs Shopify. Moved to 'next' horizon as scope: in.
---
⚖️ What the register cannot doSổ không thể làm gì
  • Prove a ruling was well-reasoned — it records that the PO made it, not that it was correct.Chứng minh một phán quyết được lý luận tốt — nó ghi PO đã ra phán quyết, không chứng minh phán quyết đúng.
  • Auto-propagate a ruling downstream — the impact-pass flags affected nodes for PO review; regeneration is opt-in.Tự lan truyền phán quyết xuống downstream — impact-pass gắn cờ các node bị ảnh hưởng để PO xem xét; tạo lại là opt-in.
  • Replace --reflect — if decisions were made but never logged, --reflect recovers them retroactively from git history and .memory/.Thay thế --reflect — nếu quyết định đã được đưa ra nhưng chưa ghi, --reflect khôi phục chúng từ lịch sử git và .memory/.
Validation & approval gate →Validation & cổng phê duyệt → Critique skillSkill critique
← PrevTrướcValidationKiểm traNextSau →Voice levelsMức giọng