Spec Prd

Phase 1: Current-State Analysis

Run PRD Sanitization before using raw PRD, notes, screenshots/OCR, transcripts, or source excerpts as requirements: separate product facts/goals/scope/acceptance, technical suggestions, temporary conclusions, unconfirmed facts, explicit non-goals, and embedded agent instructions/commands. Treat sanitization as authoring discipline, not a new schema or security parser.

When the inputs mix a ratified decision record (review conclusions, sign-off minutes) with raw discussion (verbatim transcript, chat log) or an older draft, sanitization must also separate ratified owner decisions from proposals, rejected ideas, thinking-aloud, and superseded draft claims. Only ratified decisions and confirmed source set scope, acceptance, and non-goals; the rest stay reference-claims even when they come from the same meeting. See evidence-and-topology.md Calibration Source Boundary for the authority rule.

Use evidence-and-topology.md before writing current-state, Change Delta, or source-backed claims. If the prompt already signals topology risk, run the internal Framing Gate before broad evidence gathering.

Gather scope-appropriate evidence:

• User-stated facts and decisions.
• Repo source, docs, tests, contracts, templates, and prior requirements/plans.
• Source candidates from bounded direct reads, rg, ast-grep, package/test facts, logs, knowledge-base/code-index pointers, and user-provided artifacts; confirm material claims before marking them confirmed-source.
• External research only when explicitly requested or required, with source/date.
• Assumptions only when labeled and safe to carry.

Write or update Current System Snapshot only for claims that affect the PRD. Unsupported current-state claims go to Evidence And Assumptions or Outstanding Questions.

For existing PRD or draft inputs under the default profile, extract a quality_diagnosis by applying the canonical Product Expert Lens in product-expert-lens.md. Under Contract Reset Lite, record the diagnosis in the Product Analysis Brief and load that lens only when the Brief cannot rank competing product risks. In refine the diagnosis precedes rewriting; in validate it feeds only the report. Treat external research and industry norms as advisory overlays unless confirmed by project source or owner decision.

For rough PRD / draft / reference-claims / resume-prd / pure-text inputs under analysis_profile=default, use source-first deep clarification through grill-with-docs-integration.md before final rewrite/readiness, not only after a high-severity gap label appears. Under analysis_profile=contract-reset-lite, load product-analysis-lite.md first and build its single Product Analysis Brief; load grill-with-docs-integration.md, domain, design, or large-input references only when the Brief exposes the corresponding unresolved trigger. Lite does not weaken closure: it removes parallel mandatory maps, not source reads, confirmation-basis/evidence assessment, one-question-at-a-time interaction with the sole current-user confirmer, Decision Card, checker, or finalize.

For the default profile, run the PRD-local Pre-PRD Clarification Loop after sanitization and current-state evidence, and keep its shared understanding map run-local: claim -> evidence/source -> gap -> question_or_assumption -> PRD write target. Resolve source/docs/tests/contracts/glossary/prior-PRD-answerable gaps before owner questions; source-resolved facts must not become owner questions and should carry a source ref or lookup marker in the trace. Ask owner questions one at a time with recommended answers and write targets, walking down each branch relentlessly by default: actor, flow, state, exception, acceptance, scope, permission, release-slice, terminology, decision intersections, and every triggered standard-template section. A branch stops only at a legal stop point defined in Canonical: Four Legal Stop Points. The run-local progress state must be one of closed, narrowed, accepted-assumption, owner-capped, outstanding-question, blocker, or route-out. Use compact output only when the PRD still needs a durable WHAT trace but source-first evidence already proves every relevant branch and no owner interview is needed; use bypass only when implementation-ready/direct route-out makes PRD authoring unnecessary with an explicit reason. Route missing product/system anchors to brainstorm, and never create standalone CONTEXT.md, CONTEXT-MAP.md, ADR, report, schema, or runtime artifacts in normal mode. Question order is set by downstream_confirmation_risk, but "the question would only expand scope" or "does not affect the current release slice" reorders rather than stops; only route-out (anchor missing / broad discovery / non-adjudicable) ends a branch without a Canonical stop point.

Before durable PRD write-in, run the Phase 1 Requirement Analysis Gate as a run-local map, not a persistent schema. Its required flow is: materials -> requirement understanding map -> uncertainty/contradiction identification -> decide which product/design/technical decisions must be asked through grill -> then write the PRD or analysis conclusion. Under Contract Reset Lite, the single Product Analysis Brief is the compatibility representation of this gate and Product Expert risk ranking; do not render separate parallel maps, and derive preflight_sweep_closure plus the Decision Card from the Brief. The minimum map is input_inventory, source_authority_order, target_surface_anchor, current_state_summary, change_delta, module_map, open_decisions, design_coverage, api_coverage, risk_to_prd_write_target, and either next_owner_question or a source-backed no-question reason. Compatibility labels from the former Phase 1 Preflight Sweep still apply: Input Inventory, Authority Classification, Target Surface Anchor, Current-State Evidence, Change Delta, and Risk -> PRD Write Target Map. This gate consumes the former Phase 1 Preflight Sweep; preflight_sweep_closure remains the lightweight compatibility declaration for Requirement Analysis Gate closure in Readiness Self-Check, checker findings, and closeout. Trigger Owner Question Gate, Domain/Glossary Gate, Topology/Producer-Consumer Gate, Design Coverage Gate, API/Contract Coverage Gate, and Large Input/Resume Gate when their signals appear. When design input is present, the Design Coverage Gate runs in Phase 1 before the first durable PRD write: build the existing design_source_inventory per source / node / state, including source_or_node, read_status, affected_prd_write_targets, extracted_design_what, unread_or_degraded_reason, readiness_consequence, and any conflict entry with owner_authority_needed. Only load-bearing unread/degraded items that can change page structure, state, interaction, acceptance, scope, source-of-truth, fallback display, or analytics block final-prd; non-load-bearing design residue or owner-accepted degraded design evidence may proceed only when the PRD keeps explicit coverage residue in Design Source Coverage / Planning Recheck / Outstanding Questions. Persist only the useful results into existing PRD sections such as Current System Snapshot, Change Delta, Evidence And Assumptions, Outstanding Questions, Planning Recheck, Decision Notes, Surface Map, Design Source Coverage, and Readiness Self-Check. Missing mandatory analysis items, triggered gate residue without a PRD write target, owner-owned open decisions, load-bearing unread/degraded design items without owner acceptance, or preflight_sweep_closure_absent / preflight_sweep_closure_blocked from the checker prevents final-prd and ready-for-planning; choose ask-owner-first, checkpoint-prd, or route-out instead.

Before asking owner questions, run Product Expert Lens over the Requirement Analysis Gate map: downstream_confirmation_risk -> claim -> evidence/source -> gap -> owner_question_or_assumption -> PRD_write_target -> closure_state. Requirements Grill consumes only the resulting gap, question/assumption, and write target; write-in and readiness consume closure state and remaining handoff residue. If the map shows an owner-owned product/design/technical decision that can change WHAT, acceptance, scope, data authority, interface availability, fallback display, analytics acceptance, or source-of-truth, start grill before PRD draft; do not bury it in a final PRD or non-blocking Planning Recheck.

Before the first durable PRD Write in an authoring/refinement run, emit a compact run-local Decision Card: write_mode (reused as the readiness declaration), highest_risk_gap, next_action (ask-owner-first / checkpoint-prd / final-prd / route-out), and why planning will not invent WHAT. This card exposes the path choice before side effects. Persist the three Decision-Card-only elements into the PRD Readiness Self-Check as verifiable body declarations — decision_card_highest_risk_gap:, decision_card_next_action:, decision_card_why_no_invention: — so Phase 1 entry is machine-verifiable in the artifact, not just asserted in conversation. write_mode itself doubles as the Decision Card's write_mode element (do not redeclare). decision_card_next_action 必须与该路径完全一致；两个字段都有效但互相冲突时，checker 报告 decision_card_path_mismatch。When the PRD claims ready-for-planning or write_mode=final-prd, the checker reports decision_card_undeclared if any of the three fields is missing or empty. checkpoint-prd 在仍处于 grill 时只豁免字段完整性，不豁免已声明字段之间的路径矛盾。If the card cannot justify final-prd, choose ask-owner-first, checkpoint-prd, or route-out instead of writing a final PRD and waiting for Phase 4 to catch it.

Run the Pre-Write Closure Gate before durable PRD write-in. Relentless grilling continues by default; write_mode=ask-owner-first means keep grilling the highest-risk branch, not "ask one question then stop drafting". Use write_mode=checkpoint-prd as the relentless fallback when the owner gives no cap/continue signal (absent/headless, or silent after a soft-cap offer), or for true large-input recovery that cannot wait, and mark it a recovery checkpoint (can_enter_spec-plan: no + next_owner_question) rather than a final PRD. Use write_mode=final-prd only when every load-bearing branch has reached a Canonical stop point (source evidence, owner answer, evidence-backed accepted-assumption, or owner cap); Outstanding Questions, Planning Recheck, blocker cluster, or route-out residue still in the PRD prevents final-prd. An owner who has not capped a branch that still has reachable sub-decisions prevents final-prd. Use write_mode=route-out when the input is wrong-stage or no PRD artifact would add durable WHAT value.

🔴 STOP — Pre-Write Closure Gate: Do not use write_mode=final-prd as a shortcut around semantic closure. The LLM may persist final intent only after this gate; it must keep status: draft and omit readiness_*. Claude hard-blocks direct machine-field mutation, Qoder projection is activation-unverified, and Codex/Cursor/Kiro use this as a loud convention. In every host, producer finalize remains mandatory before closeout can claim ready.

Degraded enforcement boundary: record the actual host posture in closeout when relevant. Claude is confirmed hard-enforced; Qoder is qoder_hook_activation_unverified; Codex, Cursor, and Kiro have no equivalent confirmed managed PreToolUse/Stop pair. Across all hosts, producer finalize remains mandatory before spec-prd claims a PRD is ready, but downstream entry into spec-plan is user-owned and legacy docs/brainstorms/*-requirements.md remains readable. --verify-receipt remains available as an optional read-only diagnostic, not a mandatory consumer gate. Never self-fill ready receipt fields or imply equal host protection.

Codex degraded enforcement boundary: record codex_prd_guard: not_available in closeout when relevant. Codex has no confirmed managed PreToolUse prewrite guard or Stop closeout guard for this PRD receipt path. Persist LLM-owned final intent only after semantic closure, then run the producer-local finalize command from the loaded spec-prd skill root before claiming ready. Do not imply equal protection with Claude, self-fill machine receipt fields, or convert the optional --verify-receipt diagnostic into a mandatory consumer gate.

Closure-disposition razor. Each Outstanding Question carries a closure_disposition column. An open question defaults to not-ready; it becomes non-blocking only by declaring one legal disposition plus its evidence — source-resolved / source-backed-non-WHAT-assumption (a checkable ref: repo path, URL, file:line, or anchor), owner-answered / owner-capped / owner-accepted-assumption (a matching Owner Decision Trace row), or implementation-only-how-pushdown (declares planning_would_invent_what=no and does not touch interface availability / permission / scope / source-of-truth / fallback display / analytics). "I judged it a parallel planning-time item" is NOT a disposition — that is exactly the observed failure where a load-bearing interface/permission question was self-downgraded to non-blocking and never asked. The model has no free "non-blocking" verdict; blocks_planning=no must be derived from a legal disposition, never asserted. The deterministic check-prd-artifact.js only reads the declared token and evidence-cell presence; it does not decide whether a question is load-bearing.

closure_state is not a second disposition vocabulary. Use only open, closed, deferred, or blocked there to describe the remaining handoff state. Put the reason in closure_disposition: owner-accepted-assumption, owner-capped, source-resolved, and implementation-only-how-pushdown are dispositions, not closure_state values. deferred without a legal disposition stays non-ready unless an owner cap/acceptance or source-backed non-WHAT assumption explains why planning will not invent WHAT.

For an owner-* disposition, "a matching Owner Decision Trace row" means a row that binds to this OQ specifically — either it repeats the OQ's question verbatim, or one of its cells names the OQ id (e.g. OQ-2). A single global trace row does not close every owner question at once; each owner-* OQ must point at its own bound row, or check-prd-artifact.js reports open_oq_without_owner_closure. This binding check is artifact-internal referential consistency — it verifies the OQ points at a real trace row, not that the owner genuinely decided it. Whether the owner was actually asked stays the deferred host-provenance ceiling; do not read this gate as proof of a real owner round-trip.

Push-Right owner checkpoint (Brief). Defer the irreducible owner decisions to the rightmost checkpoint as an ordering/preview Brief, not as permission to batch-close owner questions. The Brief is run-local, creates no new artifact, and lists candidate decision items with decision | recommended answer | affected PRD write target | what planning would invent if unanswered. Actual owner interaction still uses the Interaction Method: submit only the current highest-risk source-backed owner decision through the blocking question tool or question_delivery=chat-fallback, wait for the reply, bind that specific answer to its own Owner Decision Trace row, then continue with the next item if needed. A single global Brief or batch answer cannot close multiple owner-* OQs at once; each owner-* OQ must point at its own bound row. See prd-output-template.md Push-Right Owner Checkpoint (Brief) for the Brief item shape.

Owner-answer fidelity (no reversal). An Owner Decision Trace row must record the owner's actual answer verbatim in intent — you may not soften, widen, or reverse it. If the owner answered "must read Figma before planning", the trace and the bound OQ must carry that as an unmet blocking condition, not a relaxed owner-accepted-assumption that the description "is enough". Turning a real "must do X" reply into "owner accepted skipping X" is the worst observed failure: it launders the owner's blocking decision into a non-blocking disposition and reaches ready-for-planning against the owner's own instruction. When you cannot satisfy what the owner required (no Figma access, dependency unmet), the legal outcome is checkpoint-prd + can_enter_spec-plan: no + next_owner_question asking the owner to either supply the missing input or explicitly relax the decision — the relaxation must be a new owner reply, never your own rewrite of the old one. This is a producer-side fidelity obligation, not a checker-enforced gate: check-prd-artifact.js verifies that an owner-* OQ binds to a trace row (referential consistency), but it cannot verify that the row faithfully reflects what the owner actually said — that semantic fidelity stays the deferred host-provenance ceiling, guarded by this rule, fresh-source eval, and human review, not by a deterministic test.

When front-end/UI input includes a design link, screenshot, exported design context, or interaction-state material, load design-source-evidence.md, treat fetched design facts as source-candidate / provider_untrusted, and write unresolved design claims into Planning Recheck or Outstanding Questions rather than presenting them as confirmed scope. When a design source is detected, design_source_inventory is mandatory in Phase 1 even if every item is unread or degraded; tool-unavailable paths must loudly record design_sources_unread, unread reason, and readiness consequence rather than treating the design as background prose. If design evidence contradicts requirements, owner decisions, API/source contracts, source-of-truth, fallback display, analytics, or user-visible interaction in a way that changes WHAT, acceptance, or scope, it is not source-resolved; it must remain a checkpoint/OQ or become owner-answered only after the run shows a specific owner question and answer for that exact conflict.

Design degraded owner acceptance must be evidence-backed. A naked design_degraded_owner_acceptance: true line is not owner evidence and must not be used to clear unread/partial design risk; bind the acceptance to an Owner Decision Trace row or a checkable design_degraded_owner_acceptance_ref, otherwise keep readiness at ask-owner, revise-prd, or a non-ready checkpoint.

When input is oversized, multi-source, or long-chain, load large-input-checkpoint.md. Reduce output feeds Product Expert Lens risk ordering; checkpoint write-in uses normal PRD sections and source refs instead of a transcript or progress schema.

Use Preliminary Diagnosis only to choose how to run the full clarification path: source-resolved compact PRD, shared understanding map, large-input Map-Reduce, triggered P0/P1 packs, deep grill, blocker cluster, or route-out. For create/refine, only the post-rewrite Final Readiness Diagnosis can support a new ready-for-planning claim. Validate performs its final diagnosis after the read-only source/check-only pass and can only report the current claim; it cannot create one.

Phase 2: Change Delta And Domain Language

Confirm the increment as keep, extend, replace, remove, or unknown. Do not let current-state discovery expand the product scope silently.

When the delta affects capability identity, source-of-truth, public entrypoints, workflows, artifacts, contracts, setup/runtime generation, docs/tests/package, or active product surface, classify the topology before drafting and promote only planning-relevant boundaries into the PRD.

When domain terminology, source/user contradiction, ownership, permission/state/exception scenario, or hard product boundary affects WHAT or acceptance, use the domain-language reference. Prefer source-first questioning, read docs/contracts/domain-glossary.md when it exists, and surface contradictions instead of normalizing them silently. When that glossary exists, scripts/check-glossary-drift.js <prd-path> reports deterministic avoid_term_used facts you can use while drafting; it is advisory, and readiness reuses it (see prd-readiness-lens.md).

The Requirements Grill / Domain Grill Gate is always PRD-local: ask one owner question at a time, require a named gap and PRD write target, and persist results into existing PRD sections. Even when grill-with-docs-integration.md is triggered, this workflow never creates or modifies CONTEXT.md, CONTEXT-MAP.md, project glossary, or ADR files; cross-release knowledge is candidate-only after PRD-local closure. For rough, draft, reference-claim, resume, or pure-text inputs, deep clarification remains the default path. A branch stops only at a legal stop point in Canonical: Four Legal Stop Points. Domain Grill handles terminology, contradictions, ownership, permissions, state/exception edges, and hard product boundaries; Pre-PRD Clarification handles behavioral completeness, scenario coverage, acceptance, scope, and write-target closure.

Phase 3: Draft, Refine, Validate Report, Or Split

Choose output_shape before drafting, apply the machine-safe contract from prd-output-template.md, then compose assets/templates/00-generic.md, one primary surface template, and only the triggered built-in/project-local overlays. Include conditional sections only when they reduce planning invention; do not copy run-local scratch into the PRD by default.

When refining an existing PRD, produce optimization suggestions in the compact form original -> recommendation -> reason -> write target before the final rewrite or blocking question. The final durable artifact is the rewritten PRD-grade document under docs/brainstorms/, not a standalone critique report.

When validating, return the same source-grounded diagnosis and optimization suggestions as a report-only result. Include checker/check-only facts, semantic gaps, readiness consequence, and the exact sections a later refine would change. Do not write the artifact, create a critique file, call the write-mode finalizer, materialize design exports, or change runtime. A repair request is a separate preview-first refine run after confirmation.

For rough PRDs that ran Pre-PRD Clarification, fold source-resolved gaps, owner answers, accepted assumptions, blocker clusters, and write targets into existing PRD-local sections from prd-output-template.md. Do not copy Map rows, Reduce outputs, question cards, or topology-promotion notes into the PRD unless the content itself reduces planning invention.

For oversized initial PRDs, produce a split-decision recommendation first. Write split summary and child PRDs only when the owner confirms module boundaries, priorities, and release sequencing. Keep the original PRD or source input by reference; do not introduce packet manifests or trace-ledgers in v1.

Phase 4: Readiness And Handoff

🔴 STOP — Phase 4 Mandatory Gate: Phase 4 is mandatory but mutation posture depends on intent. Create/refine must not declare the PRD done, call it a "standard PRD", write confirmed ready fields, or offer a planning handoff before running the readiness lens and producer-local finalize. Validate must run the readiness lens plus checker/finalizer --check-only (and receipt verification when relevant), then report the current state without writing a receipt or changing the artifact. Self-declaring readiness or recommending planning without observed checker/receipt facts and a stated readiness outcome is a Phase 4 violation.

Run the readiness lens before recommending planning:

• If ready, hand off to the current host's plan workflow.
• If gaps remain, keep grilling one source-backed owner question at a time while the next question can close or narrow a named PRD write target; otherwise revise with labeled assumptions, Outstanding Questions, blockers, or route-out.
• If the document needs independent critique, hand off to the current host's document-review workflow. Trigger doc-review when: (a) the grill trace shows fewer owner interactions than load-bearing OQs identified in the Requirement Analysis Gate — a signal that some OQs were parked rather than grilled; (b) design_sources_unread is non-empty and there is no explicit owner acceptance of the degraded risk; or (c) Owner Decision Trace rows do not individually bind to each owner-* OQ (meaning some owner closures were asserted without per-OQ evidence). Doc-review does not replace grill — it is a human-readable audit that can catch the patterns that deterministic checks cannot: shallow owner interactions, acceptance reversals, and load-bearing OQs quietly treated as planning-time items.
• If the input is better served by brainstorm, app consistency audit, debug, plan, or work, route out with a short reason.

For create/refine when a PRD artifact path exists, resolve SKILL_DIR to the directory containing the currently loaded spec-prd/SKILL.md. Run both lines below in the same shell invocation, replacing the placeholder with that loaded skill directory:

SKILL_DIR="<absolute path of the directory containing the loaded spec-prd/SKILL.md>"
node "$SKILL_DIR/scripts/finalize-prd-artifact.js" <prd-path> --inputs <input-path>

Use this as the producer-local ready exit; add --check-only when you need to preview the receipt without writing. If the PRD frontmatter already lists every locatable input in source_inputs: / legacy prd_input:, --inputs-from-frontmatter may be used instead of manually copying the same paths. The finalize script calls check-prd-artifact.js to seed deterministic closeout counts and trace facts; omit both --inputs and --inputs-from-frontmatter only when no original input/source file is locatable, and then record that input-side design-source detection was not covered. Persist every locatable original input/source/design file in the PRD artifact frontmatter source_inputs: list before closeout; the Claude Stop hook reads that field (and the legacy alias prd_input:) to pass --inputs into finalize/checker, so input-side Figma/design-source accounting cannot depend on model memory. If prd_input, source docs, or source refs identify original input files but you cannot pass them to --inputs or use --inputs-from-frontmatter, record input_refs_unavailable in the readiness bridge and degrade rather than pretending a product-only scan covered input-side design sources. Readiness remains LLM-owned：语义关闭后，LLM 可以先在 status: draft 下持久化 write_mode=final-prd 与 can_enter_spec_plan: yes；只有 status: ready-for-planning 以及 handoff/closeout 的 ready claim 才要求 current machine-owned finalize receipt。Report the finalize/checker outcome in the handoff and closeout — at minimum the finding count, blocking reason_codes, receipt status, and readiness outcome — so the gate is verifiable in the artifact instead of asserted. A handoff that names no finalize/checker receipt has not passed Phase 4. The deterministic checker anchors PRD sections by canonical heading or <!-- prd:section=... --> section id; pure localized headings are valid when they carry the matching section id, while machine-owned safety sections must remain locatable before final ready.

For validate, invoke the same script only with --check-only or --verify-receipt; never invoke its write mode. Missing/stale receipt or other blockers remain report findings and do not authorize validate to repair or finalize the artifact. If the checker/finalize path returns any blocking reason_codes from scripts/lib/reason-codes.js, Phase 4 must not return ready-for-planning. Consume the full list through prd-readiness-lens.md The readiness orchestrator must consume declaration findings instead of duplicating it here. For create/refine, either fill a valid declaration from current evidence and rerun finalize, or set write_mode=checkpoint-prd when preserving recoverable PRD context is necessary while keeping readiness_outcome=revise-prd or readiness_outcome=ask-owner; otherwise degrade readiness to revise-prd, ask-owner, or route-out. For validate, report the blocker and proposed write target only; any repair waits for confirmed reclassification to refine. For final UI/design-surface PRDs, advisory fact input_scan_attempted=false is must-not-ready-until-confirmed. A degraded design-source path may become ready only when the PRD explicitly records design_sources_unread, the degraded reason, owner acceptance of that risk, and the remaining Planning Recheck / Outstanding Questions residue, then passes finalize. Repeat the finding in closeout instead of silently swallowing it. Close with a PRD summary: included sections, requirement count, acceptance example count, priority distribution, NFR/assumption/outstanding count, optimization suggestion count, trace gaps, and whether planning would still have to invent WHAT.

For medium/high/regulated, UI-heavy, tool/export-heavy, workflow/contract, or mixed-surface outputs, include the triggered P1 readiness residue in the closeout when it affects planning: Requirements Quality Rubric concerns, full Coverage Pack weak rows, Interaction Analysis findings, Regression Guard, Supporting Evidence Refs, Handoff Context Slice, Living Lifecycle, rollout/backout, and downstream_sync_impact or downstream_sync_unknown. 对于 long、mixed 或 high-risk PRD，按 prd-output-template.md 的 canonical Handoff Context Slice 组合下游阅读字段；本文件只保留触发与 ownership 边界，不复制字段表。These are LLM-owned readiness/doc-review facts; they must not be represented as checker-passed semantic proof.