Review PRD

Overview

Critically review a Product Requirements Document for structural completeness, substantive quality, and common anti-patterns. A good review catches what the author missed, not what they formatted wrong.

Workflow

1. Locate the PRD — If $ARGUMENTS is a file path, read it directly. If it is a name or keyword, search .chalk/docs/product/ for matching PRD files. If multiple matches exist, list them and ask the user to pick one.

2. Read product context — Load .chalk/docs/product/0_product_profile.md and any JTBD docs to understand the product's goals, target users, and strategic direction. This context is needed to assess whether the PRD aligns with the product.

3. Read engineering context — Scan .chalk/docs/engineering/ for architecture docs. This is needed to assess feasibility of what the PRD proposes.

4. Run the review checklist — Evaluate the PRD against every item in the Review Checklist below. For each item, assign one of: PASS, WARN, FAIL.

5. Write detailed findings — For every WARN or FAIL, explain specifically what is wrong and suggest a concrete fix. Do not just say "needs improvement" — say what the improvement is.

6. Produce the review — Either:

   • (a) Output the review as a response in the conversation, or
   • (b) If the user asks for a written review, save to .chalk/docs/product/<n>_prd_review_<slug>.md

7. Summarize — End with a verdict: Ready for Engineering, Needs Revisions (list the blockers), or Needs Rewrite (fundamental problems).

Review Checklist

Problem & Users

Success Metrics

User Stories & Acceptance Criteria

Scope & Edge Cases

Dependencies & Risks

Writing Quality

Output

When writing a review doc:

• File: .chalk/docs/product/<n>_prd_review_<slug>.md
• Format: Plain markdown, no YAML frontmatter
• First line: # PRD Review: <Feature Name>
• Second line: Last updated: <YYYY-MM-DD> (Initial review)

Review doc structure:

# PRD Review: <Feature Name>

Last updated: <YYYY-MM-DD> (Initial review)

## Verdict

[Ready for Engineering | Needs Revisions | Needs Rewrite]

## Summary

1-3 sentence assessment of the PRD's overall quality and readiness.

## Checklist Results

| # | Check | Result | Notes |
|---|-------|--------|-------|
| 1 | Problem statement exists | PASS/WARN/FAIL | ... |
| ... | ... | ... | ... |

## Critical Issues (FAIL)

### [Issue title]
**What's wrong**: ...
**Suggested fix**: ...

## Warnings (WARN)

### [Issue title]
**What's wrong**: ...
**Suggested fix**: ...

## Strengths

What the PRD does well. Reinforce good practices.

Anti-patterns

• Rubber-stamping — Never approve a PRD just because it has the right section headings. A PRD with all sections filled but poor content is worse than a short PRD with honest gaps, because it creates false confidence.
• Format-only reviews — Checking that Given/When/Then syntax is correct while ignoring whether the criteria are actually testable is the most common review failure. Read each criterion and ask: "Could I write an automated test from this sentence alone?"
• Not checking testability — "The page loads quickly" passes a format check but fails a testability check. Push for "Given a user on a 3G connection, when they load the dashboard, then the first contentful paint occurs within 2 seconds."
• Ignoring product context — A PRD that conflicts with the product profile or duplicates an existing PRD is a structural problem, not a cosmetic one. Always cross-reference.
• Suggestions without specifics — "The metrics section needs work" is not actionable. Say "Metric 2 ('improve retention') needs a baseline (current: X%), a target (Y%), and a timeframe (within Z weeks of launch)."
• Skipping the verdict — Every review must end with a clear verdict. The author needs to know whether to proceed, revise, or start over.