PRD Gate: Spec Before Code

Every sprint starts here. The point is to think through every angle, every connection and every architectural consequence BEFORE writing code, so qa-gate has a contract to verify against and we never ship a bug born from an unexamined assumption.

The rule: no approved PRD, no code. No exceptions.

Workflow

0. Human playback first. Three plain lines before anything else: the human situation (who, what went wrong, what they're trying to fix), the exact object and field changing (strict nouns from the project's canonical model file), and the Fogg read (when they notice, how hard the fix is). If the request could mean two or three things, list each meaning in one line and ask. See the playbook's process/human-first.md.
1. Classify the work (Lite or Full, decision tree below).
2. Scaffold the PRD in docs/prds/ from the template.
3. Fill every section from codebase inspection and the conversation. Mark real unknowns TBD: [what's needed to resolve]. Never leave a section blank or skip one silently. Collapsing a section needs a one-line reason.
4. Interrogate the connections. Section 6 is the heart of the document: do the codebase archaeology, don't guess. 4b. Draw the process map (section 5b, Lite: the Map line). Every screen, every state (loading, in flight, success, error, empty, expired), every email, every side (asker, confirmer, viewer). Draw it from rulings or from code, never from memory. Every box gets a line in the gate: the file and the test that prove it. No map, no approval. 4c. Fill the new-user path from the code: which new-user steps this touches, which old pieces are still wired in, file and line. 4d. Kill check if anything retires: every dependent from the code with a verdict (retires with it / re-pointed to where / still live and why), plus the guard test. No section, no approval.
5. Present to the owner for approval, map first. The owner's yes by name covers the map. Surface open questions and TBDs, each with a recommendation. Wait for an explicit yes by name. Nothing is approved in advance.
6. Build against the PRD. Its acceptance criteria are the checklist qa-gate verifies before commit. Once approved, write the sprint's gates checklist at docs/prds/gates/<plan name>.md before any build code: one gate per acceptance criterion, with the qa-gate gate last.
7. Update after ship. If decisions changed during the build, update the PRD to match what shipped and mark it Status: Shipped. A PRD that lies about the system is worse than no PRD.

Decision tree: Lite or Full

Ask: "Does this change how parts of the system connect?"

Full PRD if the work involves ANY of:

• New or changed tables or columns
• New endpoints, or changes to an endpoint's contract
• Any AI agent's behavior
• Any code path a scheduled job calls, even indirectly
• A new third-party integration or SDK
• Auth, payments, identity, permissions, or any score or status users rely on
• More than 3 files across module boundaries

Lite PRD only if ALL of these are true:

• One module, 3 files or fewer
• No schema, endpoint, agent or scheduled-job impact
• No new dependencies
• The change is cosmetic or isolated (copy, styling, log messages, config values)

When in doubt, Full. An unnecessary Full PRD costs 20 minutes. A missed connection costs days.

File convention

docs/prds/
  PRD-2026-08-15-feature-name.md    (Full)
  LITE-2026-08-15-small-change.md   (Lite)

Status at the top of every PRD: Draft -> Approved -> In Progress -> Shipped -> Superseded

Lite template

# LITE: [Change name]
Status: Draft | Date: | Sprint:

**Problem:** [1-2 sentences: what's wrong or missing, and why it matters]
**Change:** [What will be done, which files]
**Out of scope:** [What this does NOT touch]
**Connections checked:** [Confirm: no schema / no endpoints / no agents / no scheduled jobs / no new deps]
**Acceptance criteria:** [Testable statements]
**Map:** [Process map: every screen, state, email and side touched, each box with its file and test. See templates/process-map.md]
**New-user path:** [Filled from the code: new-user steps touched, old pieces still wired in, file and line. "None" needs a reason]
**Kill check:** [Only if something retires: each dependent, its verdict, the guard test. Otherwise "nothing retires"]
**Risk:** [Worst case + rollback plan]

If any "Connections checked" item turns out false while you write it, upgrade to Full immediately.

Full template

The full template is at assets/prd-template.md. Sections:

0. Human walkthrough. The trigger moment, the screen-by-screen action, the other side of the loop, and the do-nothing path (what the person sees on days 3, 7 and 14 if they never act). Written before any requirement.
1. Problem and why now. One paragraph in user terms. Name which leg of B=MAP (motivation, ability, prompt) it fixes.
2. Goals and success metrics. Measurable. For AI features: accuracy, hallucination, latency and cost targets.
3. Non-goals. Explicit exclusions. This section prevents agent drift more than any other.
4. Users and use cases, including edge cases.
5. Functional requirements and acceptance criteria. Numbered FR-1, FR-2, each testable. These are qa-gate's contract. 5b. Process map. The flow drawn box by box, with a gate line per box (file and test). The map is the contract the build is checked against. 5c. New-user path. Filled by the builder from the code. 5d. Kill check. Only if something retires.
6. Architecture and connections. THE CORE SECTION.
7. Failure modes and edge cases.
8. Rollout and rollback. Switch (feature flag) name, migration order, how to undo.
9. Open questions and rulings. Must be empty or ruled by name before Approved.
10. Task breakdown. Agent-sized chunks in dependency order, each naming its design board if it's UI.

Section 6 discipline

Fill it from the actual code, not memory:

• Data model: for every table touched, paste the current column list from the schema file. For each new or changed column: name, type, nullability, default, and which similar tables do NOT have it (the wrong-table trap).
• Dependency map: for every function or service you change, search for its callers and list them. If a scheduled job is in the chain, name it.
• Endpoint contracts: method, path, request, response, auth, before and after.
• Standing constraints: confirm in writing that the design respects every hard guard in the project's CLAUDE.md.

Approval gate

Present with:

• The process map, first
• A 3 to 5 sentence summary (what, why, biggest risk)
• The open questions, each with a recommendation
• Lite or Full, and why

Don't start until the owner says approved. If something mid-build invalidates part of the PRD: STOP, update the PRD and its map, flag it, and get re-approval on the changed sections.

Handoff to qa-gate

• Every acceptance criterion is verified before commit.
• Every box on the process map gets Match, Different or Not built before merge.
• Every retired piece passes qa-gate's kill guard: a test that fails if live code still calls it.
• Nothing a user sees is stamped Shipped until the new-user walk is done (process/new-user-walk.md).
• Every scheduled job named in Section 6 appears in qa-gate's scheduled-job check.
• Every schema change passes qa-gate's schema check.
• The qa-gate output includes: PRD: [filename] - all acceptance criteria verified: YES/NO. A NO blocks the commit.
• With a gates checklist, YES may only be written when scripts/gates-check.sh shows 0 open runnable gates.

Escalation

If the work conflicts with a standing constraint or needs architecture changes beyond the sprint: don't expand scope or work around it. Write the conflict into Open Questions, present options with trade-offs, and wait for direction.