/spec-prd

name: spec-prd
description: "Public workflow entrypoint (spec-prd): create, write, refine, or validate planning-readiness of brownfield PRD-grade requirements for existing systems before implementation planning. Do not use for 0-1 product exploration, unresolved product shape, HOW planning/task compilation, implementation/debug/review, lightweight direct fixes, generated runtime mirror edits, or PRD/design-source/source consistency audits; route to spec-brainstorm, spec-plan/spec-write-tasks, spec-work, review workflows, spec-app-consistency-audit, or spec-debug for fix/crash requests as appropriate."

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