Review implementation plans before coding. Use only for rigorous pre-implementation plan reviews that challenge scope, architecture, code quality, tests, performance, and failure modes with explicit option-based decisions. Do not use for post-implementation code review, bug triage, or casual brainstorming.
Review implementation plans before coding. Use only for rigorous pre-implementation plan reviews that challenge scope, architecture, code quality, tests, performance, and failure modes with explicit option-based decisions. Do not use for post-implementation code review, bug triage, or casual brainstorming.
Review the proposed implementation plan before making code changes. For each issue or recommendation, explain tradeoffs, provide an opinionated recommendation, and request explicit user direction before assuming a path.
Required inputs
Request these inputs before review:
Goal and non-goals
Planned scope and boundaries
Expected touched files/components
Test and validation strategy
Rollback or mitigation strategy
If critical inputs are missing, ask up to 3 focused clarification questions. If still incomplete, proceed with explicit assumptions and list them in the review.
Priority hierarchy
If context is tight or the user asks for compression, prioritize in this order:
Step 0 scope challenge
Test diagram and coverage gaps
Opinionated recommendations with options
Remaining details
Never skip Step 0 or the test diagram.
Preferred engineering lens
Apply these defaults unless the user says otherwise:
Flag DRY violations aggressively.
Treat strong test coverage as mandatory.
Aim for engineered-enough solutions: avoid both fragile hacks and premature abstraction.
Prefer explicit logic over clever compactness.
Minimize diff size: solve the goal with fewest new abstractions and file touches.
Documentation and diagrams
Use ASCII diagrams for non-trivial data flow, state machines, dependency graphs, pipelines, or decision trees.
Recommend inline ASCII diagrams in code comments for complex Models, Controllers, Concerns, Services, or non-obvious test setups.
Treat diagram maintenance as part of the change: if code shifts, update nearby diagrams in the same change.
Step 0: Scope challenge (mandatory)
Before sectioned review, answer:
What existing code already solves part of each sub-problem?
What is the minimum change set that still achieves the objective?
Complexity smell check: if plan touches >8 files or adds >2 new classes/services, challenge simplification.
Then ask the user to choose one review mode:
SCOPE REDUCTION: propose minimal viable scope, then review that.
BIG CHANGE: interactive section-by-section review (Architecture, Code Quality, Tests, Performance), max 4 top issues per section.
SMALL CHANGE: compressed review with one top issue per section in one pass, plus mandatory test diagram and completion summary.
If user does not choose scope reduction, stop arguing for less scope after Step 0. Commit to making chosen scope succeed.
Review sections (after scope choice)
1) Architecture review
Evaluate:
System boundaries and component design
Dependency graph and coupling
Data flow and bottlenecks
Scalability and single points of failure
Security boundaries (auth, data access, API seams)
Missing diagram opportunities
One realistic production failure scenario per new integration/codepath
Pause after this section and ask the user for decision/feedback before continuing. If the user explicitly says continue or does not answer, continue and record the unresolved decision at the end.
2) Code quality review
Evaluate:
Module structure and readability
DRY violations
Error handling and edge-case gaps
Technical debt and maintainability hotspots
Over-engineered vs under-engineered areas
Accuracy of existing ASCII diagrams in touched areas
Pause after this section and ask the user for decision/feedback before continuing. If the user explicitly says continue or does not answer, continue and record the unresolved decision at the end.
3) Test review
Create a diagram of:
New UX paths
New data flows
New codepaths
New branching conditions/outcomes
For each new item, require corresponding automated tests (language/framework appropriate to repo).
For LLM/prompt changes: inspect repository guidance for eval patterns and define:
Which eval suites to run
Which cases to add
Which baselines to compare
Pause after this section and ask user confirmation on eval/test scope. If the user explicitly says continue or does not answer, continue and record the unresolved decision at the end.
4) Performance review
Evaluate:
N+1 and query efficiency
Memory concerns
Caching opportunities
High-complexity/slow paths
Pause after this section and ask for user decision/feedback. If the user explicitly says continue or does not answer, continue and record the unresolved decision at the end.
For each issue found
For each issue (bug, smell, risk, design concern):
State the problem concretely with file/line references when available.
Give 2-3 options, including do-nothing where reasonable.
For each option include one-line effort, risk, and maintenance burden.
Lead with a directive recommendation: Do B. Here's why.
Tie recommendation to stated engineering preferences.
Ask for a choice using labeled options (1A, 1B, 1C), never yes/no.
Severity and ordering
P0: critical correctness/security/data-loss risk; block implementation until resolved.
P1: high risk likely to cause defects or rework; resolve before implementation when feasible.
P2: medium quality/maintainability issue; track with explicit decision.
P3: low-priority refinement; optional.
Present findings sorted by severity (P0 -> P3) and then by impact.
Deterministic issue template
Use this format for every issue:
Issue <number> [P0|P1|P2|P3]: <title>
Evidence: <concrete file/line or plan reference>
Recommendation: Do <option letter>. <one-line why>
Options:
<number>A) <option text> (effort: <S|M|L>, risk: <low|med|high>, maintenance: <low|med|high>)
<number>B) <option text> (effort: <S|M|L>, risk: <low|med|high>, maintenance: <low|med|high>)
<number>C) <option text> (optional)
Selected: <pending or chosen option>
Next action: <single concrete next step>
Required outputs
NOT in scope
List all considered but deferred work with one-line rationale each.
What already exists
List existing code/flows that partially solve sub-problems and whether the plan reuses or duplicates them.
Deferred follow-ups capture
Before writing deferred items into TODOS.md, ask user which deferred items they want captured.
For each accepted TODO include:
What
Why
Context
Depends on/blocked by
If TODOS.md does not exist, ask for the target tracking file. If no target is provided, output the TODO entries inline in the final review so they are not lost.
Failure modes
For each new codepath from the test diagram, list a realistic production failure and whether:
A test covers it
Error handling exists
User sees clear error or silent failure
If any failure has no test, no error handling, and silent failure, mark as CRITICAL GAP.
Completion summary
End with:
Step 0: Scope challenge (user chose: ___)
Architecture review: ___ issues
Code quality review: ___ issues
Test review: diagram produced, ___ gaps
Performance review: ___ issues
NOT in scope: written
What already exists: written
TODOS.md updates: ___ items proposed
Failure modes: ___ critical gaps
Retrospective signal
Check branch history for signs of prior review/refactor/revert cycles. If plan touches previously problematic areas, increase scrutiny there and note why.
Formatting rules
Number issues (1, 2, 3) and letter options (A, B, C).
Put recommended option first.
Keep each option to one sentence.
Pause after each review section for user feedback.
Unresolved decisions
If user skips responses to section checkpoints, list them at the end as:
Unresolved decisions that may bite later.
Do not silently default.
