Plan Eng Review

Plan Review Mode

Review this plan thoroughly before making any code changes. For every issue or recommendation, explain the concrete tradeoffs, give an opinionated recommendation, and ask for input before assuming a direction.

Priority hierarchy

If the user asks you to compress or the system triggers context compaction: Step 0 > Test diagram > Opinionated recommendations > Everything else. Never skip Step 0 or the test diagram. Do not preemptively warn about context limits.

Read references/cognitive-patterns-eng.md

Read references/cognitive-patterns-eng.md (relative to this skill's directory). These 15 cognitive patterns guide how you think throughout the review. Apply them -- they are not a checklist, they are instincts.

Documentation and diagrams

• Use ASCII art diagrams liberally for data flow, state machines, dependency graphs, processing pipelines, and decision trees.
• For complex designs, embed ASCII diagrams directly in code comments: Models (data relationships, state transitions), Controllers (request flow), Concerns (mixin behavior), Services (processing pipelines), Tests (non-obvious setup).
• Diagram maintenance is part of the change. When modifying code near ASCII diagrams, verify they are still accurate. Update them in the same commit. Stale diagrams are worse than no diagrams. Flag stale diagrams even outside immediate scope.

PRE-REVIEW SYSTEM AUDIT

Design Doc Check

setopt +o nomatch 2>/dev/null || true
SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
DESIGN=$(ls -t ~/dev/plans/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/dev/plans/$SLUG/*-design-*.md 2>/dev/null | head -1)
[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found"

If found, read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a Supersedes: field, check the prior version for context on what changed and why.

If not found, follow the Prerequisite Skill Offer instructions from the shared office-hours-offer.md reference.

Step 0: Scope Challenge

Before reviewing anything, answer these questions:

1. Reuse check: What existing code already partially or fully solves each sub-problem? Can we capture outputs from existing flows rather than building parallel ones?
2. Minimal diff: What is the minimum set of changes that achieves the stated goal? Flag any work that could be deferred without blocking the core objective.
3. Complexity check: If the plan touches 8+ files or introduces 2+ new classes/services, challenge whether the same goal can be achieved with fewer moving parts.
4. Search check: For each architectural pattern, infrastructure component, or concurrency approach the plan introduces, search for built-ins, current best practices, and known pitfalls. Annotate recommendations with [Layer 1], [Layer 2], [Layer 3], or [EUREKA]. If WebSearch is unavailable, note: "Search unavailable -- proceeding with in-distribution knowledge only."
5. TODOS cross-reference: Read TODOS.md if it exists. Are any deferred items blocking this plan? Can any be bundled without expanding scope? Does this plan create new TODOs?
6. Completeness check: Is the plan doing the complete version or a shortcut? With AI-assisted coding, completeness is 10-100x cheaper. Boil the lake.
7. Distribution check: If the plan introduces a new artifact type (CLI binary, library package, container image), does it include the build/publish pipeline? Code without distribution is code nobody can use. Check CI/CD workflow, target platforms, and install method. If deferred, flag it explicitly.

If the complexity check triggers, proactively recommend scope reduction via AskUserQuestion. If not, present Step 0 findings and proceed to Section 1.

Critical: Once the user accepts or rejects a scope reduction, commit fully. Do not re-argue in later sections. Do not silently reduce scope.

Review Sections

Always work through the full interactive review: Architecture, Code Quality, Tests, Performance. At most 8 top issues per section.

AskUserQuestion rule for all review sections: For each issue found, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Map reasoning to engineering preferences (from shared reference). Do NOT batch multiple issues. Only proceed to the next section after ALL issues are resolved. Escape hatch: If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on.

1. Architecture review

Evaluate:

• System design and component boundaries
• Dependency graph and coupling concerns
• Data flow patterns and potential bottlenecks
• Scaling characteristics and single points of failure
• Security architecture (auth, data access, API boundaries)
• Whether key flows deserve ASCII diagrams in the plan or code comments
• For each new codepath or integration point, describe one realistic production failure scenario and whether the plan accounts for it
• Distribution architecture: if a new artifact, how does it get built, published, updated?

2. Code quality review

Evaluate:

• Code organization and module structure
• DRY violations -- be aggressive here
• Error handling patterns and missing edge cases (call out explicitly)
• Technical debt hotspots
• Over-engineered or under-engineered areas relative to engineering preferences
• Existing ASCII diagrams in touched files -- are they still accurate?

3. Test review

Read references/test-coverage-audit.md (relative to this skill's directory). Follow the full 5-step process: trace codepaths, map user flows, check existing tests, output ASCII coverage diagram, add missing tests to the plan. This is the most detailed section of the review.

4. Performance review

Evaluate:

• N+1 queries and database access patterns
• Memory-usage concerns
• Caching opportunities
• Slow or high-complexity code paths

Distribution Architecture Check

This plan introduces a distributable artifact. Verify these are addressed in the plan:

• CI/CD workflow for building and publishing
• Target platforms (linux/darwin/windows, amd64/arm64)
• User install/download method (GitHub Releases, package manager, container registry)
• Version update mechanism

If any are missing, raise as architecture issues. Code without distribution is code nobody can use.

High-Complexity Scope Reduction

This plan exceeds the complexity threshold. Before proceeding past Step 0, proactively recommend scope reduction via AskUserQuestion:

• Explain what's overbuilt
• Propose a minimal version that achieves the core goal
• Ask whether to reduce or proceed as-is

If the user chooses to proceed as-is, commit fully and do not re-argue in later sections.

Outside Voice

After all review sections are complete, follow the outside voice pattern from the shared outside-voice.md reference. Use the plan review prompt variant (challenge logical gaps, overcomplexity, feasibility risks, missing dependencies, strategic miscalibration).

Confidence Calibration

Read references/confidence-calibration.md (relative to this skill's directory) before presenting findings. Every finding must include a confidence score using that rubric.

Required Outputs

Diagrams

The plan itself should use ASCII diagrams for any non-trivial data flow, state machine, or processing pipeline. Identify which implementation files should get inline ASCII diagram comments -- particularly Models with complex state transitions, Services with multi-step pipelines, and Concerns with non-obvious mixin behavior.

Failure modes

For each new codepath from the test review diagram, list one realistic failure mode (timeout, nil reference, race condition, stale data) and whether:

1. A test covers that failure
2. Error handling exists for it
3. The user would see a clear error or a silent failure

If any failure mode has no test AND no error handling AND would be silent, flag as a critical gap.

Worktree parallelization

Read references/worktree-parallelization.md (relative to this skill's directory) and produce the parallelization analysis.

Completion summary

At the end of the review, display this summary:

• Step 0: Scope Challenge -- ___ (scope accepted as-is / scope reduced per recommendation)
• Architecture Review: ___ issues found
• Code Quality Review: ___ issues found
• Test Review: diagram produced, ___ gaps identified
• Performance Review: ___ issues found
• NOT in scope: written
• What already exists: written
• TODOS.md updates: ___ items proposed to user
• Failure modes: ___ critical gaps flagged
• Outside voice: ran (codex/claude) / skipped
• Parallelization: ___ lanes, ___ parallel / ___ sequential
• Lake Score: X/Y recommendations chose complete option

Write Review to Plan

After the Completion Summary, append a ## Review Report section to the plan file. Include: mode, key decisions, critical gaps count, unresolved count, and the completion summary table. If the plan file already has a ## Review Report section, replace it.

Handoff Note Cleanup

SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
rm -f ~/dev/plans/$SLUG/*-$BRANCH-*-handoff*.md 2>/dev/null || true

Retrospective learning

Check the git log for this branch. If prior commits suggest a previous review cycle (review-driven refactors, reverted changes), note what changed and whether the current plan touches the same areas. Be more aggressive reviewing previously problematic areas.

Spec review loop support

If the user is iterating on a spec or design doc (multiple review rounds), track what changed between rounds. Focus review energy on new or modified sections rather than re-reviewing stable parts. Note which previous findings were addressed and which remain open.

Next Steps -- Review Chaining

After completing the review, recommend next review(s) based on findings.

Suggest /plan-design-review if UI changes exist and no design review has been run -- detect from the test diagram, architecture review, or any section that touched frontend components, CSS, views, or user-facing interaction flows.

Mention /plan-ceo-review if this is a significant product change and no CEO review exists -- soft suggestion, not a push. Only mention if the plan introduces new user-facing features, changes product direction, or expands scope substantially.

Use AskUserQuestion with only applicable options:

• A) Run /plan-design-review (only if UI scope detected and no design review exists)
• B) Run /plan-ceo-review (only if significant product change and no CEO review exists)
• C) Ready to implement -- run /ship when done