plan-review

name	plan-review
description	Multi-lens auto-review of an IMPLEMENTATION PLAN (not code). Strategy → Design (if UI) → Engineering phases. All decisions auto-resolved via 6 Decision Principles. Triggers: "review plan", "autoplan".
allowed-tools	["Bash","Read","Write","Edit","Grep","Glob"]
when_to_use	Use automatically after writing-plans completes. NOT for reviewing code — use code-review for that.
produces	docs/superomni/reviews/review-[branch]-[session]-[date].md
consumes	["docs/superomni/plans/plan-[branch]-[session]-[date].md"]
dispatch-agent	planner-reviewer

Preamble (Core)

Status protocol — end every session with one of: DONE (evidence provided) · DONE_WITH_CONCERNS (list each) · BLOCKED (state what blocks you) · NEEDS_CONTEXT (state what you need).

Auto-advance — pipeline: THINK → PLAN → REVIEW → BUILD → VERIFY → RELEASE. Only human gate is spec approval at THINK. On DONE at other stages, print [STAGE] DONE -> advancing to [NEXT-STAGE] and invoke the next skill. On any non-DONE status at any stage, STOP.

Output directory — all artifacts go in docs/superomni/<kind>/<kind>-[branch]-[session]-[date].md. See CLAUDE.md for the full directory map.

TACIT-DENSE — before high-tacit decisions, classify D1 (domain expertise) · D2 (user-facing UX) · D3 (team culture) · D4 (novel pattern). On hit, output TACIT-DENSE [D#]: [question] — My default: [recommendation]. See reference for actions.

Anti-sycophancy — take a position on every significant question. Name flaws directly. No filler ("that's interesting", "you might consider", "that could work").

Telemetry (local only) — at session end, log bin/analytics-log. Nothing leaves the machine.

See preamble-ref.md for detailed protocols.

Plan Review Pipeline

Goal: Review a plan through multiple lenses before execution begins. Catch problems before they become expensive mistakes.

One command. Rough plan in, fully reviewed plan out.

The 6 Decision Principles (Reference)

1. Choose completeness — cover more edge cases
2. Boil lakes — fix everything in blast radius if <1 day effort
3. Pragmatic — two equal options? Pick the cleaner one
4. DRY — duplicates existing? Reject. Reuse what exists.
5. Explicit over clever — 10-line obvious > 200-line abstraction
6. Bias toward action — flag concerns but don't block

Conflict resolution:

• Strategy phase: Principles 1+2 dominate (completeness + lake-boiling)
• Engineering phase: Principles 5+3 dominate (explicit + pragmatic)
• Design phase: Principles 5+1 dominate (explicit + completeness)

Decision Classification

Mechanical — one clearly right answer given constraints. Auto-decide silently, don't burden the user. Taste — reasonable engineers could disagree. Auto-resolve using the 6 Decision Principles and log the rationale. Do NOT ask the user.

---

Auto Mode (Default)

Plan review ALWAYS runs in full auto mode when triggered from the pipeline:

• Mechanical decisions: Auto-resolve silently using the 6 Decision Principles. Log each decision.
• Taste decisions: Auto-resolve using best judgment and the 6 Decision Principles. Log rationale. Do NOT surface to user.
• All 3 phases (Strategy, Design, Engineering) run automatically.
• No final gate — auto-advance to BUILD immediately on DONE.

Auto-decision log format:

AUTO-DECISION LOG ([Phase])
  [P1] [topic]: [decision made] — Principle [N]
  [TASTE-AUTO] [topic]: [decision made] — Principle [N] — Rationale: [why]

---

Phase 1: Strategy Review (CEO Lens)

Dispatch the planner-reviewer agent in strategy mode with the plan document as input. The agent will run the full process (problem extraction, scope review, strategic questions) and return a CEO ADVISOR REVIEW block. Incorporate its findings into the strategy section below. (Strategy-review content was consolidated from the retired ceo-advisor agent into planner-reviewer.)

Questions:

1. Premise validity — are assumptions stated or just assumed?
2. Scope calibration — right amount of work? Not too much, not too little?
3. Alternatives considered — was the chosen approach selected, not just defaulted to?
4. What already exists — is anything being reinvented? (DRY check)
5. Risk identification — what are the top 3 risks if this goes wrong?
6. Success definition — is there a measurable definition of done?

STRATEGY REVIEW
  Premises: [explicit | implicit | missing]
  Scope:    [right-sized | too large | too small]
  Alternatives: [considered | not documented]
  DRY:      [reuses existing | reinvents wheel]
  Risks:    [list top 3]
  Strategy mode: [Mode chosen: EXPANSION | SELECTIVE EXPANSION | HOLD SCOPE | REDUCTION]

Auto-resolve: Verify premises against the spec and existing codebase. If premises are valid, proceed silently. If premises are questionable, log the concern and apply Principle 6 (bias toward action) to proceed.

---

Phase 2: Design Review (conditional)

Only run this phase if the plan includes UI or user-facing changes.

Dispatch the frontend-designer agent with the plan document and any relevant UI context as input. The agent will rate all 10 design dimensions (0-10), run its AI Slop detection checklist, edit the plan to add missing design requirements, and return a DESIGN REVIEW block. Incorporate its findings and any plan edits directly into the review output.

Check:

• Information hierarchy — is the most important thing most prominent?
• Missing states — loading, empty, error, partial/degraded?
• Responsive strategy — does it work at different screen sizes?
• Accessibility — keyboard nav, screen readers, color contrast?
• Error recovery — can users recover from mistakes?

DESIGN REVIEW (if applicable)
  States covered: loading ✓/✗ | empty ✓/✗ | error ✓/✗
  Responsive: [strategy described | missing]
  Accessibility: [addressed | not addressed]

---

Phase 3: Engineering Review

For doc-alignment & declaration-precedence discipline (declaration precedence, quantitative-claim pinning, forbidden-token-as-drifted-expression), see the Convention section in docs/SKILL-DATA-FLOW.md.

Dispatch the planner-reviewer agent in engineering mode with the plan document and any relevant source files as input. The agent will run the full architecture review process (layer audit, coupling check, tech choices, scalability) and return an ARCHITECTURE REVIEW block. Incorporate its P0/P1 findings below.

Check:

• Architecture soundness — appropriate layers, minimal coupling?
• Test coverage plan — what will be tested, at what level?
• Performance risks — N+1 queries, large payloads, unbounded operations?
• Error path handling — every error case has a handling strategy?
• Security considerations — auth, input validation, injection risks?
• Backward compatibility — does this break existing behavior?
• Blast radius — how many files/systems does this touch?

ENGINEERING REVIEW
  Architecture: [sound | concerns: ...]  (from planner-reviewer engineering mode)
  Test plan:    [comprehensive | gaps: ...]
  Performance:  [no risks | risks: ...]
  Security:     [clean | concerns: ...]
  Blast radius: [N files, N systems]

---

Decision Audit Trail

#	Phase	Decision	Type	Principle	Rationale
1	Strategy	[decision]	M/T	P1-P6	[why]

---

Final Gate: Auto-Resolved Taste Decisions

All TASTE decisions are auto-resolved using the 6 Decision Principles. Log each decision with rationale:

TASTE DECISIONS — AUTO-RESOLVED
═══════════════════════════════════════

1. [Decision description]
   Chosen: [option] — Principle [N] — Rationale: [why]

2. [Decision description]
   Chosen: [option] — Principle [N] — Rationale: [why]

═══════════════════════════════════════

Do NOT present taste decisions to the user or wait for input. Apply best judgment and proceed.

---

Plan Review Report

PLAN REVIEW COMPLETE
════════════════════════════════════════
Phases completed:     [1, 2 (skipped), 3] or [1, 2, 3]
Issues found:         [N]
Decisions made:       [N mechanical, N taste — all auto-resolved]
Plan status:          APPROVED | APPROVED_WITH_NOTES | NEEDS_REVISION

Revisions applied:
  - [revision 1]

Taste decisions auto-resolved:
  - [decision 1: chosen option — rationale]

Status: DONE | NEEDS_CONTEXT
════════════════════════════════════════

REVIEW auto-advances — after reporting DONE, immediately advance to BUILD. All decisions (mechanical and taste) have been auto-resolved. No user confirmation is required. The THINK stage (brainstorm + spec approval) is the only human gate in the pipeline.

Save Review Artifact

Persist the review result before auto-advancing:

_REVIEW_DATE=$(date +%Y%m%d)
_REVIEW_BRANCH=$(git branch --show-current 2>/dev/null | tr '/' '-' || echo "unknown")
_PLAN_FILE=$(ls docs/superomni/plans/plan-*.md 2>/dev/null | sort | tail -1)

if [ -n "$_PLAN_FILE" ]; then
  _PLAN_BASE=$(basename "$_PLAN_FILE" .md)
  _REVIEW_SESSION=$(echo "$_PLAN_BASE" | sed -E "s/^plan-${_REVIEW_BRANCH}-//" | sed -E 's/-[0-9]{8}$//')
fi

if [ -z "$_REVIEW_SESSION" ]; then
  _REVIEW_SESSION="plan-review"
fi

mkdir -p docs/superomni/reviews
_REVIEW_FILE="docs/superomni/reviews/plan-review-${_REVIEW_BRANCH}-${_REVIEW_SESSION}-${_REVIEW_DATE}.md"

Write the full PLAN REVIEW COMPLETE report block to $_REVIEW_FILE and include all decision logs.