Prd Writer

PRD Writer

A PRD here is short and operational. It is the contract between the problem and the implementation. If the success criteria are wrong, every downstream stage is wrong.

When to use

• Starting a new feature with more than a trivial change
• A refactor that crosses module boundaries
• An integration where the contract with an external system matters
• Any change where the user wants a quality gate before code lands

When NOT to use

• One-line fixes, typos, dependency bumps
• Spike work where the goal is to learn
• Bug fixes where the fix is mechanically obvious

Inputs

• feature_slug — kebab-case identifier
• problem_statement — one paragraph: what is being built and why
• (optional) source_material — links, screenshots, prior art

If problem_statement is missing, ask before drafting. Do not infer.

Source-gathering (when needed)

If the problem statement references external claims, libraries, papers, or product names, invoke:

• research-analyst — for deep multi-source synthesis (3+ sources to compare or summarize)
• search-specialist — for a single precise lookup (API signature, version, exact quote)
• evidence-auditor — to verify any claim the draft PRD attributes to an external source

These run before drafting, not after. A PRD with unverified citations is worse than one with no citations.

Output

docs/PRDs/<feature_slug>.md, copied from templates/prd-template.md and filled in. Sections:

1. Problem — 1-3 paragraphs of current state + pain
2. Success criteria — binary checkboxes
3. In scope — what is included
4. Out of scope — anti-scope
5. Dependencies — what must land first
6. Risks — specific failure modes with likelihood and mitigation
7. Open questions — unresolved items

The success criteria rule (most important)

Criteria must be binary. Each one passes a single test:

Can a fresh reader, given the criterion plus the implementation, answer yes or no without judgment?

Bad (vibes): "Improve performance", "Make the code cleaner", "Handle edge cases gracefully"

Good (binary): "P95 latency on /login under 200ms across 100 test requests", "Cyclomatic complexity ≤ 8 for every function in auth/", "On invalid email, the API returns HTTP 400 with {error: 'invalid_email'} (verified by integration test)"

If a criterion cannot be made binary, it belongs in ## 7. Open questions until resolved.

Pre-flight checklist

Before writing the file:

1. Do I have the problem statement from the user, in their words?
2. Have I distinguished problem from solution? (PRD is about WHAT, not HOW.)
3. Is every success criterion binary? If not, fix or move to open questions.
4. Is there a clear out-of-scope section?
5. Have I listed dependencies even if "none"?
6. Are risks specific failure modes, not generic phrases?
7. If the PRD cites external claims, has evidence-auditor verified them?

What happens next

The PRD feeds three downstream skills:

• task-plan — decomposes the PRD into a checkbox task list
• verify — uses the success criteria as the verification gates
• quality-review — runs the 3-agent team against the PRD before implementation starts

If the PRD is wrong, all three are wrong. Spend the time here.

Anti-patterns

• Inferring success criteria from vibes — ask the user
• Burying solution in the problem — PRD describes WHAT, not HOW
• Vague risks — "things might break" is not a risk; "the third-party API rate-limits at 100 req/min" is
• Skipping out-of-scope — if you do not write the anti-scope, scope creeps
• 500-word PRDs for 20-line features — the PRD should be proportional to the work
• Unverified citations — every external claim runs through evidence-auditor before the PRD ships
• metadata-fetcher — invoked when the PRD references a paper, library, package, or repo by identifier (DOI, package name, repo URL). Returns the structured record (version, license, OA status, last release) so the PRD cites accurate metadata. Mechanical lookup; no analysis.