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
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.
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.
Read engineering context — Scan .chalk/docs/engineering/ for architecture docs. This is needed to assess feasibility of what the PRD proposes.
Run the review checklist — Evaluate the PRD against every item in the Review Checklist below. For each item, assign one of: PASS, WARN, FAIL.
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.
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
Summarize — End with a verdict: Ready for Engineering, Needs Revisions (list the blockers), or Needs Rewrite (fundamental problems).
Review Checklist
Problem & Users
| # |
Check |
Criteria |
| 1 |
Problem statement exists |
There is a dedicated section articulating the user problem, not a system problem |
| 2 |
Problem is user-centric |
Written from the user's perspective, not "the system needs to..." |
| 3 |
Links to JTBD or user research |
References a known user need, not an internal assumption |
| 4 |
Target users defined |
Specific personas or user segments are named, not "all users" |
| 5 |
Anti-personas identified |
States who this is NOT for |
Success Metrics
| # |
Check |
Criteria |
| 6 |
Metrics exist |
At least 2 success metrics are defined |
| 7 |
Metrics are measurable |
Each metric has a number or clear threshold, not "improve engagement" |
| 8 |
Metrics are time-bound |
Each metric specifies a measurement period |
| 9 |
Baselines included |
Current state is documented so improvement can be measured |
| 10 |
Metrics connect to user outcomes |
Metrics measure user value, not just system activity |
User Stories & Acceptance Criteria
| # |
Check |
Criteria |
| 11 |
User stories present |
At least one user story in "As a / I want / So that" format |
| 12 |
Stories have acceptance criteria |
Every story has at least 1 Given/When/Then criterion |
| 13 |
Acceptance criteria are testable |
A QA engineer could write a test from each criterion without asking the PM for clarification |
| 14 |
Feature-level acceptance criteria exist |
There are overall completion criteria beyond individual stories |
| 15 |
No stories that are really tasks |
Stories describe user value, not implementation steps like "Set up database table" |
Scope & Edge Cases
| # |
Check |
Criteria |
| 16 |
Out of scope defined |
There is an explicit out-of-scope section with specific exclusions |
| 17 |
Edge cases enumerated |
Error states, empty states, boundary conditions, and permission boundaries are covered |
| 18 |
No contradictions |
Out-of-scope items are not also described as in-scope elsewhere in the document |
Dependencies & Risks
| # |
Check |
Criteria |
| 19 |
Dependencies listed |
Internal, external, and technical dependencies are identified |
| 20 |
Open questions flagged |
Unresolved items are explicitly listed with owners |
| 21 |
Feasibility checked |
Proposed solution is compatible with the current architecture |
Writing Quality
| # |
Check |
Criteria |
| 22 |
Problem-first structure |
The document leads with the problem, not the solution |
| 23 |
No vague language |
Terms like "intuitive," "fast," "seamless" are replaced with specific, measurable descriptions |
| 24 |
No feature-list syndrome |
The PRD describes user outcomes, not just a list of features to build |
| 25 |
Internally consistent |
Metrics, stories, and acceptance criteria align with each other |
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.
1---2name: review-prd-23description: Review an existing PRD for completeness, quality, and anti-patterns when the user asks to review, critique, or check a PRD4---5
6# Review PRD
7
8## Overview
9
10Critically 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.
11
12## Workflow
13
141. **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.
15
162. **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.
17
183. **Read engineering context** — Scan `.chalk/docs/engineering/` for architecture docs. This is needed to assess feasibility of what the PRD proposes.
19
204. **Run the review checklist** — Evaluate the PRD against every item in the Review Checklist below. For each item, assign one of: PASS, WARN, FAIL.
21
225. **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.
23
246. **Produce the review** — Either:
25 - (a) Output the review as a response in the conversation, or
26 - (b) If the user asks for a written review, save to `.chalk/docs/product/<n>_prd_review_<slug>.md`
27
287. **Summarize** — End with a verdict: Ready for Engineering, Needs Revisions (list the blockers), or Needs Rewrite (fundamental problems).
29
30## Review Checklist
31
32### Problem & Users
33
34| # | Check | Criteria |
35|---|-------|----------|
36| 1 | Problem statement exists | There is a dedicated section articulating the user problem, not a system problem |
37| 2 | Problem is user-centric | Written from the user's perspective, not "the system needs to..." |
38| 3 | Links to JTBD or user research | References a known user need, not an internal assumption |
39| 4 | Target users defined | Specific personas or user segments are named, not "all users" |
40| 5 | Anti-personas identified | States who this is NOT for |
41
42### Success Metrics
43
44| # | Check | Criteria |
45|---|-------|----------|
46| 6 | Metrics exist | At least 2 success metrics are defined |
47| 7 | Metrics are measurable | Each metric has a number or clear threshold, not "improve engagement" |
48| 8 | Metrics are time-bound | Each metric specifies a measurement period |
49| 9 | Baselines included | Current state is documented so improvement can be measured |
50| 10 | Metrics connect to user outcomes | Metrics measure user value, not just system activity |
51
52### User Stories & Acceptance Criteria
53
54| # | Check | Criteria |
55|---|-------|----------|
56| 11 | User stories present | At least one user story in "As a / I want / So that" format |
57| 12 | Stories have acceptance criteria | Every story has at least 1 Given/When/Then criterion |
58| 13 | Acceptance criteria are testable | A QA engineer could write a test from each criterion without asking the PM for clarification |
59| 14 | Feature-level acceptance criteria exist | There are overall completion criteria beyond individual stories |
60| 15 | No stories that are really tasks | Stories describe user value, not implementation steps like "Set up database table" |
61
62### Scope & Edge Cases
63
64| # | Check | Criteria |
65|---|-------|----------|
66| 16 | Out of scope defined | There is an explicit out-of-scope section with specific exclusions |
67| 17 | Edge cases enumerated | Error states, empty states, boundary conditions, and permission boundaries are covered |
68| 18 | No contradictions | Out-of-scope items are not also described as in-scope elsewhere in the document |
69
70### Dependencies & Risks
71
72| # | Check | Criteria |
73|---|-------|----------|
74| 19 | Dependencies listed | Internal, external, and technical dependencies are identified |
75| 20 | Open questions flagged | Unresolved items are explicitly listed with owners |
76| 21 | Feasibility checked | Proposed solution is compatible with the current architecture |
77
78### Writing Quality
79
80| # | Check | Criteria |
81|---|-------|----------|
82| 22 | Problem-first structure | The document leads with the problem, not the solution |
83| 23 | No vague language | Terms like "intuitive," "fast," "seamless" are replaced with specific, measurable descriptions |
84| 24 | No feature-list syndrome | The PRD describes user outcomes, not just a list of features to build |
85| 25 | Internally consistent | Metrics, stories, and acceptance criteria align with each other |
86
87## Output
88
89When writing a review doc:
90- **File**: `.chalk/docs/product/<n>_prd_review_<slug>.md`
91- **Format**: Plain markdown, no YAML frontmatter
92- **First line**: `# PRD Review: <Feature Name>`
93- **Second line**: `Last updated: <YYYY-MM-DD> (Initial review)`
94
95Review doc structure:
96```markdown
97# PRD Review: <Feature Name>
98
99Last updated: <YYYY-MM-DD> (Initial review)
100
101## Verdict
102
103[Ready for Engineering | Needs Revisions | Needs Rewrite]
104
105## Summary
106
1071-3 sentence assessment of the PRD's overall quality and readiness.
108
109## Checklist Results
110
111| # | Check | Result | Notes |
112|---|-------|--------|-------|
113| 1 | Problem statement exists | PASS/WARN/FAIL | ... |
114| ... | ... | ... | ... |
115
116## Critical Issues (FAIL)
117
118### [Issue title]
119**What's wrong**: ...
120**Suggested fix**: ...
121
122## Warnings (WARN)
123
124### [Issue title]
125**What's wrong**: ...
126**Suggested fix**: ...
127
128## Strengths
129
130What the PRD does well. Reinforce good practices.
131```
132
133## Anti-patterns
134
135- **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.
136- **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?"
137- **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."
138- **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.
139- **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)."
140- **Skipping the verdict** — Every review must end with a clear verdict. The author needs to know whether to proceed, revise, or start over.
majiayu000