create-prd

# Create PRD

## Quick Start
1. Copy the template: `assets/prd-template.md`
2. Fill it out in the target dossier:
   - Single-PRD dossier: `prd.md`
   - Multi-PRD dossier:
     - Overall / spine PRD at the dossier root: `prd-overall.md`
     - Slice PRDs under `prds/`: `prds/<slice_id>_<slug>/prd.md`

   Notes:
   - Lowest-level PRD filenames are always `prd.md` (no `prd-slice-*` filenames).
   - Use a short kebab-case slug like `auth-token-rotation` or `invoice-pdf-export`.
3. Pull all details from shaping inputs into the PRD so it’s implementable without extra context (no information loss)

## PRD Slicing Rubric (Reusable)

### Rules of thumb (thin PRDs)
- One PRD should deliver **one user-visible affordance** (or one backend capability with a **measurable, observable effect**), not a whole workflow.
- Each PRD must have **measurable acceptance criteria** tied to at least one **replayable verification pack** (fixture data, synthetic dataset, scripted scenario, etc.).
- Keep PRDs **vertical-ish**: UI + a thin API/data change where needed, but avoid building platform layers unless they **directly unblock the next slice**.
- If a PRD introduces a new failure mode, it must also introduce the **UX to surface it** (no silent failures).
- Prefer **scaffold then replace**: ship a deterministic baseline behind stable contracts first, then swap in ML/OCR/retrieval/LLM (or other complex components) behind the same interface.

### Examples (good slices)
- "UI affordance X triggers state Y, persists, and is visible after refresh."
- "API returns payload + stable checksum/hash so clients can detect mismatches."
- "Verifier rejects records on checksum mismatch and surfaces a user-visible error state."
- "Parser extracts a single structured list into a table with row-level provenance."

### Examples (bad slices)
- "Build ingestion + parsing + retrieval + drafting + verification + export" (too many risks bundled).
- "Implement an autonomous multi-agent copilot" (non-deterministic + typically too broad for a single slice).
- "Add full template/customisation system" (platform work without proving the core loop).

### Red flags a PRD is too fat
- Touches 3+ major subsystems/components in one go.
- Needs more than 1-2 new schemas or widespread data model churn.
- Acceptance criteria can't be tested against a pack/fixture/script.
- Contains multiple hard unknowns at once (new parsing + matching + verification together).

### Minimum PRD structure (every PRD)
The minimum structure is defined by `assets/prd-template.md` and must include:
- Introduction/Overview (problem + goal)
- Goals
- User stories
- Functional requirements (numbered)
- Non-goals (out of scope)
- Success metrics
- Open questions

Additionally, every PRD must include:
- Acceptance criteria + verification plan (pack/fixture/script)
- Failure states + user-visible UX (no silent failures)
- Metrics/logging (at least 1 signal)
- Rollback/disable path (feature flag or safe default)
- A lightweight "Sources" section pointing to shaping inputs (brief/breadboard/spike/risk-register)

## Inputs
One or more of the following:
- Problem statement + target users
- Success metric
- Constraints, risks, dependencies
- Any existing verification packs/fixtures/scripts (or willingness to create a minimal one)

## No Context Loss (Requirement)
If any of the following shaping files exist, no information should be lost from them:
- `brief.md`
- `breadboard-pack.md`
- `spike-investigation.md`
- `risk-register.md`

Guidance:
- Prefer integrating shaping details directly into the PRD sections (requirements, risks, constraints, UX, verification).
- Add a short "Sources" section with links/paths to the shaping files you used.
- If a detail does not fit cleanly into a PRD section, add it to the appendix as notes or key excerpts. Avoid dumping large verbatim blocks by default.
- Each PRD must be implementable without needing additional context outside the PRD.

Try find this information:
- `brief.md`
- `breadboard-pack.md`
- `spike-investigation.md` 
- `risk-register.md`

Where unclear, use the `ask-questions-if-underspecified` skill.

## Outputs
- Single-PRD dossier: `prd.md` in the dossier root.
- Multi-PRD dossier:
  - Overall / spine PRD in the dossier root as `prd-overall.md`.
  - Slice PRDs under `prds/<slice_id>_<slug>/prd.md`.

## Steps
1. Ask 3-5 clarifying questions (answerable as 1A, 2B) that force a thin slice:
   - What is the single user-visible affordance (or single observable backend capability)?
   - What is the primary observable effect (what changes, where can we see it)?
   - What pack/fixture/script will we use to verify acceptance criteria?
   - What new failure modes does this introduce, and how should UX surface them?
   - What is the rollback/disable path (flag/default-off/fallback)?
2. Run the slicing rubric:
   - If the scope triggers a red flag, propose a split into PRD-1/PRD-2/... and proceed with the smallest slice that unblocks the next.
3. Use the PRD template at `assets/prd-template.md`.
4. Fill sections (short, explicit; keep the template headings):
   - Introduction/Overview + goals
   - In scope + non-goals (out of scope)
   - User stories (US-001...), one sprint-sized
   - Functional requirements (FR-001...)
   - Acceptance criteria + verification plan per story (measurable; tied to a pack/fixture/script)
   - Failure states and UX (no silent failures)
   - Metrics/logging + rollback/disable path
   - Risks + dependencies
   - Success metrics + open questions
   - Sources: link to shaping inputs used
   - Appendix (optional): shaping notes / key excerpts when needed (see "No Context Loss")
5. Ensure criteria map to verification; split oversized stories. If generating multiple PRDs:
   - Create the overall/spine PRD at the dossier root as `prd-overall.md`.
   - Create each slice PRD under `prds/<slice_id>_<slug>/prd.md` (one folder per slice).

   Each PRD must be independently implementable and must not lose shaping input information.

## Verification
- PRD delivers one affordance / one observable capability.
- Acceptance criteria measurable, testable, and tied to at least one pack/fixture/script.
- Acceptance criteria mapped to verification (tests/build/smoke/scripts).
- Failure modes surfaced in UX (no silent failures).
- At least 1 metric/log signal is specified.
- Rollback/disable path is explicit (flag or safe default).
- Stories small, priority ordered.
- Location matches `docs/AGENTS.md`.
- If there are multiple PRDs for a dossier:
  - the overall/spine PRD is `prd-overall.md` in the dossier root
  - each slice lives under `prds/<slice_id>_<slug>/prd.md` (folder-per-slice; lowest-level PRD filename is always `prd.md`)
- Sources section links to shaping inputs used.
- No information is lost from shaping inputs (details are integrated into the PRD or captured in the appendix).