sunrain520/spec-first/spec-prd

Brownfield PRD Requirements

Purpose

Turn an existing-system increment, rough product note, or low-quality PRD into a standard durable PRD artifact by first thoroughly clarifying requirements with source-first grill-with-docs discipline, then writing WHAT/WHY, current-state evidence, acceptance, scope boundaries, assumptions, and unresolved blockers into the PRD template so spec-plan can plan without inventing product behavior. For existing PRDs, refine diagnoses and rewrites after closure; validate produces a read-only planning-readiness report and never mutates the artifact.

Default-profile mental map: spec-prd is analysis-first: materials become a run-local Requirement Analysis Gate map, the map identifies uncertainty and contradiction points, Product Expert Lens ranks which product/design/technical decisions must be grilled, Requirements Grill closes or carries the load-bearing WHAT gaps, Standard PRD write-in records the decisions, and Readiness Lens asks whether planning or work would still have to invent product behavior. Contract Reset Lite compresses the first three analysis views into one Brief without changing the durable write/readiness spine. Treat either form as a workflow spine, not a direct external skill chain or persistent artifact topology.

Main workflow spine: Input -> Classify / Route Decision -> Input Inventory & Sanitization -> Current-State Evidence -> Requirement Analysis Gate -> Product Expert Lens -> Requirements Grill -> Pre-Write Closure Decision -> PRD Write / Refine -> Readiness Lens + Finalize -> Handoff; validate branches after evidence into Readiness Lens + check-only -> Report, never the write/finalize spine. Treat ready-for-planning, ask-owner, revise-prd, doc-review, and route-out as readiness/handoff outcomes, not the main workflow chain. Treat checkpoint-prd as a write_mode recovery shape under Pre-Write Closure Decision, never as a readiness outcome or planning handoff.

Use the current host/session date when dating PRD requirements documents. If the date is unavailable, read it with a deterministic command; do not hard-code calendar years in this source file. All file references in generated documents must use repo-relative paths.

Default artifact invariant: write Markdown requirements under docs/brainstorms/*-requirements.md with artifact_kind: prd-requirements. Do not create docs/prds/, implement code, write implementation plans, or edit generated runtime mirrors.

Experimental analysis profile: only the exact invocation token analysis_profile=contract-reset-lite activates Contract Reset Lite. It replaces the default parallel analysis ceremony with one run-local Product Analysis Brief while preserving the current artifact topology, Decision Card, checker/finalizer, producer receipt, validate report-only boundary, and optional downstream receipt diagnostic. In Lite, the current user is the sole human product confirmer; specialist, regulatory, privacy, security, financial, and professional materials remain evidence for that confirmation and never create a second human confirmation route. Natural-language requests such as "make the PRD shorter" or "simplify the workflow" do not activate it. Without the token, use the default profile unchanged.

Runtime mutation guard: the LLM owns final intent (write_mode: final-prd, can_enter_spec_plan: yes, and the semantic readiness outcome); finalize-prd-artifact.js alone owns status: ready-for-planning and readiness_* receipt fields. Managed Claude installs prd-prewrite-guard for Write|Edit|MultiEdit: it requires a durable write_mode on the first PRD write and blocks direct machine-field mutation, including degraded Edit/MultiEdit reconstruction that still touches those fields. Claude is the only host with confirmed managed hard enforcement for this path. Qoder hook projection is present but activation remains unverified. Codex, Cursor, and Kiro remain loud degraded and rely on explicit producer-finalize discipline; never imply equal hard protection. The Stop/readiness guard treats final intent without a current receipt as blocking, so allowing the LLM to persist intent does not allow closeout.

Workflow Contract Summary

When To Use

Use for brownfield increment PRD authoring, existing PRD refinement, and code-aware PRD validation when the product owner already knows the existing product/system surface being changed.

When Not To Use

Do not use for 0-1 product exploration, unresolved product shape, implementation planning, task execution, debugging, PRD/design-source/source audit, or requests that only need a lightweight direct fix.

Inputs

An increment request, existing PRD or requirements draft, rough Markdown notes, extracted multimodal material (image/PDF/meeting-notes/chat-log transcripts), source/docs evidence, current-system context, domain terms, and product-owner decisions.

Outputs

A PRD-grade requirements artifact for create/refine, concise optimization suggestions for refine, a source-resolved compact PRD or explicit route-out when PRD authoring adds no durable WHAT value, a split-decision summary pending owner confirmation, or a report-only validation result with source/checker facts, blockers, questions, and readiness outcome.

Artifacts

Requirements artifacts under docs/brainstorms/ using artifact_kind: prd-requirements, optional split summary and child PRDs for owner-confirmed oversized initial PRDs, and no generated runtime mirror edits.

Failure Modes

Missing target surface, unresolved product identity, current-state claims without evidence, owner decisions that would change scope, unconfirmed source candidates presented as confirmed truth, or PRD readiness gaps that would force planning to invent WHAT.

Workflow

Classify intent and input mode, gather current-state evidence, run the Requirement Analysis Gate to map materials into understanding, uncertainty/contradiction points, grill decisions, and PRD write targets, then branch: create/refine may write after closure and run finalize; validate runs readiness/check-only and returns a report without mutation. Hand off to refine, doc review, plan, or done from the observed result.

Downstream Consumers

spec-plan, spec-doc-review, product owners, implementation reviewers, and future work/review flows that need stable PRD-grade WHAT/WHY context.

Scenario Capability

Follows docs/contracts/workflows/scenario-capability-matrix.md (default). Overrides: none

Invocation Boundary

This is a workflow orchestrator, not an agent type. Use the current host's PRD workflow entrypoint when routing into it. Do not expose helper reviewers or readiness checks as separate public entrypoints.

Interaction Method

When asking any owner question or confirmation, including no-input target request, Pre-PRD Clarification, Domain Grill, split confirmation, readiness ask-owner, and grill-with-docs, use the platform's blocking question tool: AskUserQuestion in Claude Code or request_user_input in Codex when available. In Claude Code, call ToolSearch with query select:AskUserQuestion before the first owner question if the schema is not loaded.

Fall back to numbered options in chat only when the harness genuinely lacks a blocking question tool, the tool call explicitly fails, or the runtime mode does not expose it. In fallback, set question_delivery=chat-fallback, state the degraded path, present the current source-backed blocking question, and wait for the user's reply. A blocking question tool unavailable does not mean true headless.

Use question_delivery=true-headless-unavailable only when the run is truly unable to wait for user input, such as explicit headless/report-only mode, upstream no-interaction instruction, or a runtime that cannot receive a reply. In that case, set clarification_evidence=headless-degraded-logged, name why interaction was impossible, and list the owner questions downgraded into Outstanding Questions or blockers; missing this trail is clarification_evidence=skipped, not a valid fallback. Never silently skip an owner question or continue drafting as if the owner answered.

Ask one question at a time. Options should include a recommended answer when defensible and leave room for free-form correction.

Capability-Class Evidence Boundary

Follows docs/contracts/project-graph-consumption.md: capability-class candidates such as code-graph or project-graph are advisory only. Check readiness_status before use; PRD conclusions must be re-grounded in source, and a candidate must never decide scope authority. Record used candidates as provider_untrusted, never-block on availability, keep setup-side lifecycle.fallback_used separate; fall back to direct source reads on missing/unknown/unverified/failure/disabled.

Core Principles

1. Brownfield first - Establish the current system snapshot before writing new behavior.
2. WHAT not HOW - Product behavior, acceptance, scope, evidence, and business constraints belong here. Implementation units, database tables, exact API fields, and task breakdown belong in planning.
3. Evidence-tag current-state claims - A current-state assertion is confirmed only when source, tests, docs, contracts, or user confirmation supports it.
4. Clarify relentlessly before writing - Requirements grilling is the default PRD authoring/refinement path, and its posture is relentless by default: walk down each load-bearing branch one question at a time, and keep going by default rather than stopping early. A branch may stop only at one of the four legal stop points defined in Canonical: Four Legal Stop Points below. "Enough to write a PRD section", "one key question already asked", "the question sequence is getting long", and "does not affect the current release slice" are NOT stop reasons; they only affect question order. After Phase 0 classifies the run as create or refine, grill trace is mandatory: do not read inputs and emit final-prd unless clarification_evidence is a valid non-skipped value. Route-out and bypass are pre-authoring exits, not grill exemptions. Choose bypass or compact output only when PRD authoring would add no durable WHAT value or every relevant branch is already source-resolved and leaves detectable clarification trace.
5. Product risk ordering - Under analysis_profile=default, Product Expert Lens ranks downstream-confirmation risks from source/input evidence and binds each load-bearing gap to a PRD write target. Under Contract Reset Lite, the single Product Analysis Brief owns the same ordering and loads product-expert-lens.md only when competing product risks cannot otherwise be ranked. In both profiles, downstream_confirmation_risk controls question order and handoff priority, not whether to close the gap; a gap that cannot yet bind to a write target is carried visibly instead of dropped. Do not create a new agent type or role taxonomy.
6. No second PRD artifact topology - Keep the PRD chain: docs/brainstorms/*-requirements.md -> plan -> tasks -> work -> review -> knowledge. grill-with-docs closes requirements in the PRD and may emit candidate-only project knowledge records; it never creates a replacement artifact or mutates project context/ADR files.
7. reason-then-act - Before a user-visible side effect, write the reason and the relevant run-local field, then act: owner question -> highest_risk_gap / next_owner_question / question_delivery; PRD write -> write_mode; readiness -> checker findings plus readiness_outcome / can_enter_spec-plan; handoff -> readiness_outcome and next action. Rule: reuse existing Decision Card fields and do not add phase-status enums, progress files, or transcripts. For lightweight branches, route-out, bypass, and source-proven paths use one concise reason instead of full ceremony.

Execution Compass