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:
-
Fold the answer into the PRD body. Find the relevant section in
project-prd.md(use the OQ row’sSectioncolumn 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. -
Move the OQ row from signals to history. Delete the row from
project-prd-signals.md## Open Questions. Append a row toproject-prd-history.md## Resolved Open Questionspreserving the original question and recording the resolution. TheResolved incolumn holds a pointer of the formRev N: see §XorRev N: see AD #Y(for a withdrawn question with no PRD change,Rev N: withdrawn). -
Append a revision entry. Add a
### Rev N — YYYY-MM-DDblock toproject-prd-history.md## Revisionsdescribing what changed and naming the OQ (Resolves: OQ-0). TakeNfrompython3 .claude/lib/next-id.py prd-rev(.claude/rules/id-numbering.md). -
Update every other statement of the old answer, in the same PR.
git grepthe wording the answer replaces (and the OQ id) across.forge/and.claude/, includingclient/anddesign/; 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 toproject-prd-signals.md. Never add an## Open Questionsor## Risks and Open Questionsheading toproject-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 Nblock toproject-prd-history.md## Revisions. Never add a## Revisionsheading or### Rev Nrow toproject-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 Engineeringitem 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 noowed.mdrow 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
Blockscolumn on signal rows is load-bearing —spec-reviewerfilters 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 toproject-prd-signals.md. - An
^## Open Questions$or^## Risks and Open Questions$heading → same pointer. - An
^## Revisions$heading or^### Rev \d+row → pointer toproject-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.)