source: .claude/rules/prd.md · generated — edit the markdown, not this file

PRD Trichotomy & Open-Question Lifecycle

The project PRD is split across three files with distinct content classes. This split exists because mixing live contract, live signals, and audit trail into one document bloated every read of the PRD and made selective context-loading impossible on the consumer side (spec-reviewer, etc.). The trichotomy mirrors the harness’s existing live-vs-frozen separation pattern (features.md live vs PRD §Feature Decomposition frozen).

The Trichotomy

File Class Contents When read
project-prd.md Live contract Problem, domain, scope, in-scope features, NFRs, constraints, §Risks, success criteria. The frozen-at-Gate-1 statement of what we are building. Always — full body — by anyone reading the PRD.
project-prd-signals.md Live signals Open and partial open questions only (⏳ open, ◐ partial). Each row anchored to a PRD section and (optionally) to feature IDs it blocks. Selectively — spec-reviewer loads only rows whose Blocks column contains the feature ID under review. Humans browse this file when answering or grooming OQs.
project-prd-history.md Audit trail Resolved open questions (## Resolved Open Questions) and PRD revisions (## Revisions). Rarely — humans tracing a past decision. Not auto-loaded by any skill or sub-agent.

Risks stay in project-prd.md (not in signals). Risks are part of the engagement contract, the section is small, and per-spec risk injection is already handled by tracker.yaml setup.* + the inject-relevant-risks-spikes.sh hook. Only OQs and Revisions move.

The OQ Resolution Procedure

When an open question in project-prd-signals.md is answered, four writes happen together:

  1. Fold the answer into the PRD body. Find the relevant section in project-prd.md (use the OQ row’s Section column as the anchor) and update the body so the decision is part of the live contract. If the resolution is an architectural decision, add it as a new row to .claude/CLAUDE.md § Architecture Decisions (DO NOT REVERSE) instead, with its reason and sign-off in .forge/design/architecture-decisions-why.md.

  2. Move the OQ row from signals to history. Delete the row from project-prd-signals.md ## Open Questions. Append a row to project-prd-history.md ## Resolved Open Questions preserving the original question and recording the resolution. The Resolved in column holds a pointer of the form Rev N: see §X or Rev N: see AD #Y (for a withdrawn question with no PRD change, Rev N: withdrawn).

  3. Append a revision entry. Add a ### Rev N — YYYY-MM-DD block to project-prd-history.md ## Revisions describing what changed and naming the OQ (Resolves: OQ-0). Take N from python3 .claude/lib/next-id.py prd-rev (.claude/rules/id-numbering.md).

  4. Update every other statement of the old answer, in the same PR. git grep the wording the answer replaces (and the OQ id) across .forge/ and .claude/, including client/ and design/; update each hit, add a post-issue note where the hit is in the proposal, and leave only dated records (revision logs, gate runs, the engagement log) as they are. The same applies when an OQ is reopened. Why: the second project audit (.forge/audits/2026-10-05-project-audit-2.md) found that OQ-15’s reopening, the AWS ownership change, the region choice and AD #38 had each been recorded where they were decided and nowhere else.

Do not skip step 3 — the Resolved in: Rev N pointer in step 2 must point at a real revision entry. The first three writes together preserve the audit trail and let a future reader trace any current PRD statement back to the question it answered.

Conventions

  • New open questions (from forge-prd-author, /forge-prd-check, /forge-arch-probe, /forge-decompose, or mid-engagement) → write to project-prd-signals.md. Never add an ## Open Questions or ## Risks and Open Questions heading to project-prd.md. The shape-guard hook will block it.
  • An OQ dropped without an answer (no longer needed, or replaced by a better question) moves to history like a resolved one: its row keeps the original question, the Resolution starts with Withdrawn, says why, and names the question that replaces it if there is one, and a revision entry records it (OQ-69 and Rev 68 are the model). A row is never deleted without its history row, and its number is never given to another question (.claude/rules/id-numbering.md).
  • New PRD revisions (any meaningful change to the PRD body after first sign-off, per the standard revisions convention) → append a ### Rev N block to project-prd-history.md ## Revisions. Never add a ## Revisions heading or ### Rev N row to project-prd.md. The shape-guard hook will block it.
  • Risks → project-prd.md § Risks (per the trichotomy table above). The per-spec risk-context injection mechanism (tracker.yaml setup.* + inject-relevant-risks-spikes.sh) is unchanged.
  • A change that rewords the PRD body gets the fresh-context comparison of .claude/CLAUDE.md § Compounding Engineering item 6 before merge.
  • A dropped or descoped item, or a missed milestone, is not raised with Empire Teas separately. Record a drop as usual — a post-issue note on the proposal’s header where it changes something the proposal promised, and the change to client/client-facing-prd.md — and write “not raised with Empire Teas separately”; add no owed.md row about telling Empire. Why: the lead decided the post-issue notes and the client-facing PRD are the record (2026-10-11; the same for the Foundation milestone, 2026-10-15), and a “decide whether to tell Empire” row was never acted on.
  • The Blocks column on signal rows is load-bearing — spec-reviewer filters signals by feature ID using it. When recording an OQ that blocks one or more features, list the feature IDs comma-separated. If the OQ is engagement-level and doesn’t block any specific feature, use —.

Hook Contract

The guard-prd-shape.sh PreToolUse hook (Edit | Write) inspects writes targeting project-prd.md. A Bash write to the same file (sed -i, a redirect) is refused by block-dangerous-bash.sh so it cannot slip past this guard. It exits non-zero with a stderr pointer message when the proposed new content tries to insert:

  • An ^| OQ-\d+ | row → pointer to project-prd-signals.md.
  • An ^## Open Questions$ or ^## Risks and Open Questions$ heading → same pointer.
  • An ^## Revisions$ heading or ^### Rev \d+ row → pointer to project-prd-history.md.

The hook is path-scoped — it only fires on project-prd.md (the contract file). Edits to project-prd-signals.md and project-prd-history.md are not inspected; those files are where this content belongs.

If blocked, follow the resolution procedure above — do not try to work around the hook. The error message points at the correct destination file and at this rule.

The hook fails open on missing jq, paths that don’t match, and malformed stdin — same posture as every other harness hook (guard-spec-approval.sh, guard-plan-approval.sh). It will not block a session because of its own malfunction.

Why this rule exists

Without enforcement, projects rot back into the inline pattern under deadline pressure — a single engagement can accumulate dozens of inline open questions over a few weeks, and once the majority are answered (✅) they become pure bookkeeping bloating every PRD read. The shape-guard hook + this rule are the same enforcement triangle already used for spec/plan approvals (skill writes the right shape, hook enforces it, annotation/structure is the evidence). Without both halves, the discipline doesn’t survive contact with a busy engagement.

See .forge/forge-harness-framework.md § 4. Required Artifacts for the doctrine-level statement. (The pre-trichotomy migration procedure lives in the upstream forge-harness repo; this project’s PRD was born trichotomous.)

Generated from .claude/rules/prd.md by .claude/lib/render-docs-html.js. Markdown is canonical.