| description | Review architecture plans against their original requirements |
|---|---|
| argument-hint | <requirements-name> (e.g. 260325-01-currency-support) |
You are reviewing the architecture planning output for a feature. Your job is to audit the plan files against the original requirements and flag any drift, omissions, or contradictions.
All files live in .claudhh-workspace/ (which is gitignored):
- Requirements file:
.claudhh-workspace/requirements/$1.md - Plan files:
.claudhh-workspace/plans/$1*.md(glob for all iterations and variants)
Given a requirements name like 260325-01-currency-support:
- The requirements file is
.claudhh-workspace/requirements/260325-01-currency-support.md - Plan files follow the pattern
.claudhh-workspace/plans/260325-01X-currency-support[-variant].mdwhere:Xis an iteration letter (a, b, c, d, e...)-variantis an optional suffix like-dhh-feedback,-impl,-code-review- Later letters are later iterations (e supersedes d, which supersedes c, etc.)
-
Read the requirements file first. Understand every requirement, constraint, and acceptance criterion.
-
Find all plan files matching the prefix. List them in chronological/iteration order.
-
Identify the final plan — the highest-lettered iteration without a
-dhh-feedbackor-code-reviewsuffix. If there's an-implvariant at the highest letter, that's the implementation plan. -
Read the final plan carefully. Also skim key intermediate versions and DHH feedback files to understand how the plan evolved.
-
Write your review to a file. The review file goes in the plans directory with the same version letter as the plan being reviewed, suffixed with
-codex-review. For example, if you're reviewing260325-01e-currency-support.md, write your review to.claudhh-workspace/plans/260325-01e-currency-support-codex-review.md.The review file should contain these sections:
State which plan file you reviewed (the full filename).
For each requirement/constraint in the requirements file, state whether the final plan:
- Covered — the plan addresses it explicitly
- Partially covered — addressed but with gaps or ambiguity
- Missing — not addressed at all
- Contradicted — the plan does something that conflicts with the requirement
Identify any places where the plan has drifted from the requirements through the iteration process. Sometimes DHH feedback or implementation concerns cause the plan to evolve away from what was originally asked for. Flag these — they may be intentional trade-offs or accidental omissions.
Flag anything in the final plan that was NOT in the requirements. This isn't necessarily bad, but it should be called out.
Any architectural risks, missing edge cases, or implementation concerns you spot.
A numbered list of concrete changes you recommend making to the plan. Be specific enough that each item is actionable.
A brief overall assessment: does the final plan faithfully implement what the requirements asked for?
-
Present the review to the user. Summarize your findings and list the suggested changes. Ask the user which changes (if any) they'd like to incorporate.
-
After the user confirms, create a new plan file with the next version letter. For example, if you reviewed version
e, the new plan is versionf:.claudhh-workspace/plans/260325-01f-currency-support.md. The new plan should be based on the reviewed plan with the agreed-upon changes incorporated. Do NOT create the new plan until the user has confirmed which changes to make.
- Be specific. Quote from both the requirements and plan files.
- If a requirement was deliberately changed based on DHH feedback, note that — it's not drift if it was a conscious decision documented in a feedback file.
- Focus on substance, not formatting. The plan files may have different structures.
- If you can't find the requirements file or plan files, say so clearly rather than guessing.
- Always write the review file before presenting findings — the file is the artifact, the chat summary is just a convenience.