review-plan

Review a Plan

Process

1. Load the plan and its context: Read the plan file(s) and any siblings. Plans are HTML — .plans/<slug>/plan.html (single-PR) or the overview.html / data-model.html / plan.html / decisions.html / verification.html / contracts.html set (multi-PR), plus inc-<N>-notes.md. Legacy plans may still be Markdown (*.md) — read whichever exists. Machine fields live on data-* attributes (increments: data-inc, data-size, data-depends, data-files, data-done); read those when checking dependency ordering and done-criteria. Read the relevant .agents/standards/ files that apply to the planned work.

1. Review for technical soundness:
2. Are the architectural decisions correct given the codebase?
3. Are the dependencies between increments properly ordered?
4. Are there missing increments or gaps in the sequence?
5. Will each increment actually pass CI independently?

1. Review for convention compliance:
2. Does the plan follow the project's standards?
3. Are files placed in the right directories?
4. Does the naming follow conventions?
5. Are there patterns in .agents/common-mistakes/ that the plan risks repeating?

1. Review for conversation fidelity: If reviewing a plan produced during an active conversation, check whether all decisions, constraints, and answered questions from the discussion are captured in the plan. A correct plan that doesn't match what was agreed is worse than a slightly imperfect plan that does. Skip this step if reviewing a plan file without conversation context.

1. Review for implementability:
2. Is each increment scoped tightly enough to implement in one session?
3. Are the "done criteria" specific and verifiable?
4. Are there ambiguities that will force the implementer to make undocumented decisions?

1. Summarize findings:
2. MUST FIX — Issues that would cause implementation failure or architectural problems
3. SHOULD FIX — Issues that would cause friction or technical debt
4. CONSIDER — Suggestions for improvement

Rules

• Reviewing a plan is 10x cheaper than fixing a bad implementation
• The best time to catch a missing dependency is before any code exists
• Convention compliance in the plan prevents convention violations in the code
• An adversarial reviewer should argue _against_ the plan — not just validate it
• Big-output discipline. Heavy command output (project check, full git diff, repo-wide search, long log, large fetch) goes to /tmp/hawk-<skill>-<step>.log, then rg -n '<pattern>' /tmp/hawk-<skill>-<step>.log | head -50 extracts what you need. Read the file only with offset/limit. See README → Big-output discipline.