Prd First

PRD-First Discipline

The user (Abhillash) vibe-codes 10-15 apps and loses track of what each app is actually doing because Claude generates code from high-level intent without a written contract. This skill forces a 10-minute thinking pass before any code generation. The PRD is the contract; the code must satisfy it; future-Abhillash can read the file three months from now and remember why.

The hard rule

No PRD, no code. When the trigger fires, refuse to generate code or vibe-code prompts until a PRD exists as a markdown file in the repo at /prds/YYYY-MM-DD-.md. This is non-negotiable except when the user explicitly overrides with "skip the PRD" — in which case flag the risk once, then proceed.

The 5-question protocol

Ask one question at a time. Wait for the answer. Do not batch. This matches the user's learning style (theory → quiz → build, one question at a time).

Each question has a quality bar. If the answer is vague, ask one follow-up. Then move on — don't gold-plate.

Question 1 — Problem:

What hurts today, and for whom?

Quality bar: a specific pain, not a feature wish. "I want a dashboard" is a feature; "I'm losing 30 minutes a day reconciling Stripe payouts against orders" is a problem. If they answer with a feature, ask: "What's the underlying pain that makes you want that?"

Question 2 — User:

Who specifically uses this, and what's their current alternative?

Quality bar: a real person (you, your team, a known segment) and a named alternative ("I do it in a spreadsheet now", "we use Notion but it doesn't sync"). If "everyone" — push back: "Pick the one user whose problem we're solving first."

Question 3 — Success:

One metric, one number, one timeframe — when do we know this worked?

Quality bar: measurable. "Faster reconciliation" fails. "Reconcile a day's payouts in under 3 minutes by end of week 2" passes. If they can't name a number, accept a binary: "Does the thing I described in Q1 still happen on Friday? Yes/No."

Question 4 — Scope cuts:

What are we explicitly NOT building in v1?

Quality bar: at least 3 things named. This is the most important question. If they say "nothing, build it all", push back hard: "Name three things you're cutting. Vibe-coded apps die from scope creep, not from missing features."

Question 5 — Non-goals:

What would make us call this a failure even if it ships?

Quality bar: at least one named failure mode. Examples: "if it costs more than $5/month to run", "if I have to maintain it manually every week", "if non-technical users can't open it without help". This catches the class of bugs where you build the right thing correctly but it's still useless.

What to do with the answers

After all 5 questions answered, write the PRD to /prds/YYYY-MM-DD-.md using this exact template (indented with 4 spaces, since the file itself is markdown):

# PRD: <one-line name>

**Date:** YYYY-MM-DD
**Status:** Draft | Approved | Built | Shipped | Killed
**Contract status:** DRAFT | APPROVED
**Approved by:** <exact accountable human identity; blank while Draft>

## Problem
<Q1 answer, 1-3 sentences>

## User
<Q2 answer, 1-2 sentences. Name the user, name their alternative.>

## Success metric
<Q3 answer. One sentence. Must contain a number or a binary yes/no.>

## Scope (v1)
- <thing 1>
- <thing 2>
- <thing 3>

## Out of scope (cut from v1)
- <cut 1>
- <cut 2>
- <cut 3>

## Non-goals (failure modes)
- <failure mode 1>
- <failure mode 2 if applicable>

## Functional requirements
- **FR-001:** <one observable v1 behavior; add stable IDs in order>

## Engineering acceptance contract (required for PEOS handoff)
- **AC-001**
  - requirement_refs: [FR-001]
  - form: given_when_then
  - given: [{path: service.running, operator: eq, value: true}]
  - when: {action: health, arguments: {}}
  - then: [{path: result.status, operator: eq, value: ok}]

For a PEOS handoff, replace the example values only with fields the user explicitly approves. The current `barebones-1` PEOS template registers only `health`; if the handoff needs another action, keep the engineering contract Draft and record `ACTION_NOT_REGISTERED` rather than inventing a binding. An ordinary non-PEOS build may omit this section and is not restricted to the PEOS action registry; its product PRD may still be approved.

## Unresolved product-critical questions
- None | <question that blocks approval>

## Decisions log
(Append one line per architectural choice as we build. Format: "Chose X over Y because Z.")

Show the user the PRD. Ask: "Approve, edit, or kill?" Wait for explicit approval before generating any code or vibe-code prompts.

After approval

When the user approves the PRD, do four things:

1. Record accountable approval. Change Status to Approved, change Contract status to APPROVED, and write the exact human identity into Approved by. If the identity is not known, ask; never infer it. Approval is invalid while a product-critical question remains unresolved.

2. Reference the PRD path in every subsequent code prompt. The vibe-code prompt's first line must be: "Implement /prds/YYYY-MM-DD-.md. Code must satisfy the success metric and respect the scope cuts."

3. Create or update /DECISIONS.md in the repo root. This is the running architectural log. Every meaningful choice (framework, library, schema, auth pattern, deployment target) gets one line appended. Format: "2026-05-24: Chose Supabase over Firebase because — auth + Postgres in one, free tier covers v1 user count."

4. At end of each coding session, ask the user one question: "Anything we decided today that should go in DECISIONS.md?" Append what they say. This is how context compounds across sessions instead of evaporating.

Edge cases

• Existing repo, no /prds/ folder: create it. Don't ask permission for the folder, ask permission for the PRD content.
• User says "I already know what I want, just build it": push back ONCE. Say: "I'll build it, but you'll forget why we made these choices in a month. 10 minutes now saves 2 hours of re-reading code later. Want me to ask the 5 questions?" If they still refuse, proceed and flag in DECISIONS.md: "Skipped PRD per user request — risk: future debugging context loss."
• Tiny features (one-line tweak, bug fix): PRD not required. Skill applies to new things being built, not edits to existing things.
• User answers vaguely on purpose: don't fight them. Capture what they said, mark the PRD status as "Draft", proceed. The PRD is a living doc; vague v1 is better than no v1.
• Retrofitting a PRD for an existing vibe-coded app: valid use case. Skip Question 4 (scope is already set) and Question 3 (success metric is "does it currently work" — binary yes). Focus on Q1, Q2, Q5 to recover lost context.

What this skill is NOT

• Not a replacement for the user's judgment. The PRD is their document — Claude is a scribe, not the author.
• Not a corporate PRD template with stakeholders, timelines, and OKRs. This is a personal thinking artifact.
• Not enforced on every chat message. Only when the trigger words appear and code generation is the next likely step.
• Not a research exercise. If the user can't answer Q3 because they genuinely don't know the metric yet, accept "I'll figure this out after I see it working" and mark the field as "TBD — define after first prototype."

Limitations

• The PRD is a thinking contract, not a guarantee — a well-formed PRD can still describe the wrong product; the skill enforces the ritual, not the judgment.
• Trigger detection is phrase-based; a build request worded unusually can slip past, and the user can always override with "skip the PRD" (flagged once, then honored).
• The 5-question protocol assumes the user can answer interactively; in fully autonomous runs the task description itself must serve as the PRD-equivalent, noted in DECISIONS.md.
• Applies to new things being built — it does not gate edits, bug fixes, or debugging of existing code.

The self-check before generating any code

Before writing a single line of code or vibe-code prompt after the trigger fires, scan:

1. Does a PRD file exist at /prds/YYYY-MM-DD-.md? If no → ask the 5 questions.
2. Has the user explicitly approved it? If no → show the PRD, ask for approval.
3. If this is an engineering handoff, are agreeing Status: Approved and Contract status: APPROVED, Approved by, FR-*, and compiler-shaped AC-* bindings present with no unresolved product-critical question? If no → complete those PM-owned fields or keep the PRD Draft.
4. Does the prompt I'm about to write reference the PRD path? If no → add it as the first line.
5. Is there a /DECISIONS.md in the repo root? If no → create it with a header.

If all five pass, proceed. If not, stop and fix the gap.