Product spec (PRD-first)
An approved PRD records intended behavior. Live implementation, decisions, and external source-of-truth contracts can reveal that it is stale. Classify divergence before editing: code defect, undocumented approved change, stale spec, or unresolved decision. Reconcile the authoritative artifact instead of copying drift silently.
Mode detection
- Challenge - user is unsure whether to build: run only the scope gate, report, stop.
- Create - no PRD covers this area.
- Update (most common) - a PRD exists: surgical edits only.
Scope gate (always, before writing anything)
Answer in five lines; recommend kill or shrink when answers are weak:
- What user problem does this solve - who, doing what, blocked how?
- What is the smallest version that solves it? Everything else goes to "later".
- Can existing functionality already do this?
- Cost vs measurable business value: implementation + operational + maintenance, against what it directly contributes to the core product.
- Why now?
Create mode
- Clarify only what's genuinely missing - one question at a time, multiple-choice where possible (persona, problem, success measure, constraints).
- Find the repo's PRD home (
docs/prd/, docs/prd.md, PRODUCT.md) and match its structure; otherwise use assets/prd-template.md.
- Every non-trivial P0 requirement: Given/When/Then acceptance criteria plus at least two materially different edge cases. Do not invent filler for a genuinely atomic rule. NFRs are feature-specific; non-goals are mandatory.
- State system-of-record and ownership boundaries explicitly ("Service A is the system of record for loans; this service must not evolve into a loan-management system").
- Include a negative-constraints section: what must NOT be built or changed.
Update mode
- Read the PRD and the source of truth (design doc, implementation, decision) first; produce a change map before editing.
- Preserve requirement IDs - update content, not IDs. Mark superseded requirements; never delete silently. Insert with sub-IDs (FR-017a). Add a version + change-log entry. Update cross-references.
- After editing, validate against the codebase: implemented-but-undocumented features, descoped requirements, contract drift.
Self-review - spec smells
Flag before presenting: solution masquerading as requirement · vague metric ("improve UX") · missing non-goals · requirement without testable criteria · TBD without owner · "while we're at it" scope creep.
Run the Definition-of-Ready checklist from the template. Present for approval when approval is part of the repository workflow; implementation proceeds via plan once scope is explicit and authorized.
1---2name: spec3description: Use when defining or changing WHAT to build - a new feature idea, a PRD to write or update, or scope that needs challenging before implementation starts.4---56# Product spec (PRD-first)78An approved PRD records intended behavior. Live implementation, decisions, and external source-of-truth contracts can reveal that it is stale. Classify divergence before editing: code defect, undocumented approved change, stale spec, or unresolved decision. Reconcile the authoritative artifact instead of copying drift silently.910## Mode detection11- **Challenge** - user is unsure whether to build: run only the scope gate, report, stop.12- **Create** - no PRD covers this area.13- **Update** (most common) - a PRD exists: surgical edits only.1415## Scope gate (always, before writing anything)16Answer in five lines; recommend kill or shrink when answers are weak:171. What user problem does this solve - who, doing what, blocked how?182. What is the smallest version that solves it? Everything else goes to "later".193. Can existing functionality already do this?204. Cost vs measurable business value: implementation + operational + maintenance, against what it directly contributes to the core product.215. Why now?2223## Create mode24- Clarify only what's genuinely missing - one question at a time, multiple-choice where possible (persona, problem, success measure, constraints).25- Find the repo's PRD home (`docs/prd/`, `docs/prd.md`, `PRODUCT.md`) and match its structure; otherwise use `assets/prd-template.md`.26- Every non-trivial P0 requirement: Given/When/Then acceptance criteria plus at least two materially different edge cases. Do not invent filler for a genuinely atomic rule. NFRs are feature-specific; non-goals are mandatory.27- State system-of-record and ownership boundaries explicitly ("Service A is the system of record for loans; this service must not evolve into a loan-management system").28- Include a negative-constraints section: what must NOT be built or changed.2930## Update mode31- Read the PRD and the source of truth (design doc, implementation, decision) first; produce a change map before editing.32- Preserve requirement IDs - update content, not IDs. Mark superseded requirements; never delete silently. Insert with sub-IDs (FR-017a). Add a version + change-log entry. Update cross-references.33- After editing, validate against the codebase: implemented-but-undocumented features, descoped requirements, contract drift.3435## Self-review - spec smells36Flag before presenting: solution masquerading as requirement · vague metric ("improve UX") · missing non-goals · requirement without testable criteria · TBD without owner · "while we're at it" scope creep.3738Run the Definition-of-Ready checklist from the template. Present for approval when approval is part of the repository workflow; implementation proceeds via `plan` once scope is explicit and authorized.
OmexIT