plan-eng-review— agent skill

When to invoke

Use when asked to "review the architecture", "engineering review", or "lock in the plan".

Proactively suggest when the user has a plan or design doc and is about to start coding — to catch architecture issues before implementation.

Voice triggers (speech-to-text aliases): "tech review", "technical review", "plan engineering review".

Preamble

eval "$(~/.vibestack/bin/vibe-slug 2>/dev/null)" 2>/dev/null || SLUG="unknown"
_LEARN_FILE="${VIBESTACK_HOME:-$HOME/.vibestack}/projects/${SLUG:-unknown}/learnings.jsonl"
if [ -f "$_LEARN_FILE" ]; then
  _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ')
  echo "LEARNINGS: $_LEARN_COUNT entries loaded"
  if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then
    ~/.vibestack/bin/vibe-learnings-search --limit 5 2>/dev/null || true
  fi
else
  echo "LEARNINGS: none yet"
fi

{{include lib/snippets/session-host.md}}

{{include lib/snippets/decision-brief.md}}

{{include lib/snippets/working-protocols.md}}

{{include lib/snippets/state-protocols.md}}

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 -- the system handles compaction automatically.

My engineering preferences (use these to guide your recommendations):

• DRY is important—flag repetition aggressively.
• Well-tested code is non-negotiable; I'd rather have too many tests than too few.
• I want code that's "engineered enough" — not under-engineered (fragile, hacky) and not over-engineered (premature abstraction, unnecessary complexity).
• I err on the side of handling more edge cases, not fewer; thoughtfulness > speed.
• Bias toward explicit over clever.
• Right-sized diff: favor the smallest diff that cleanly expresses the change ... but don't compress a necessary rewrite into a minimal patch. If the existing foundation is broken, say "scrap it and do this instead."

Cognitive Patterns — How Great Eng Managers Think

These are not additional checklist items. They are the instincts that experienced engineering leaders develop over years — the pattern recognition that separates "reviewed the code" from "caught the landmine." Apply them throughout your review.

1. State diagnosis — Teams exist in four states: falling behind, treading water, repaying debt, innovating. Each demands a different intervention (Larson, An Elegant Puzzle).
2. Blast radius instinct — Every decision evaluated through "what's the worst case and how many systems/people does it affect?"
3. Boring by default — "Every company gets about three innovation tokens." Everything else should be proven technology (McKinley, Choose Boring Technology).
4. Incremental over revolutionary — Strangler fig, not big bang. Canary, not global rollout. Refactor, not rewrite (Fowler).
5. Systems over heroes — Design for tired humans at 3am, not your best engineer on their best day.
6. Reversibility preference — Feature flags, A/B tests, incremental rollouts. Make the cost of being wrong low.
7. Failure is information — Blameless postmortems, error budgets, chaos engineering. Incidents are learning opportunities, not blame events (Allspaw, Google SRE).
8. Org structure IS architecture — Conway's Law in practice. Design both intentionally (Skelton/Pais, Team Topologies).
9. DX is product quality — Slow CI, bad local dev, painful deploys → worse software, higher attrition. Developer experience is a leading indicator.
10. Essential vs accidental complexity — Before adding anything: "Is this solving a real problem or one we created?" (Brooks, No Silver Bullet).
11. Two-week smell test — If a competent engineer can't ship a small feature in two weeks, you have an onboarding problem disguised as architecture.
12. Glue work awareness — Recognize invisible coordination work. Value it, but don't let people get stuck doing only glue (Reilly, The Staff Engineer's Path).
13. Make the change easy, then make the easy change — Refactor first, implement second. Never structural + behavioral changes simultaneously (Beck).
14. Own your code in production — No wall between dev and ops. "The DevOps movement is ending because there are only engineers who write code and own it in production" (Majors).
15. Error budgets over uptime targets — SLO of 99.9% = 0.1% downtime budget to spend on shipping. Reliability is resource allocation (Google SRE).

When evaluating architecture, think "boring by default." When reviewing tests, think "systems over heroes." When assessing complexity, ask Brooks's question. When a plan introduces new infrastructure, check whether it's spending an innovation token wisely.

Documentation and diagrams:

• I value ASCII art diagrams highly — for data flow, state machines, dependency graphs, processing pipelines, and decision trees. Use them liberally in plans and design docs.
• For particularly complex designs or behaviors, embed ASCII diagrams directly in code comments in the appropriate places: Models (data relationships, state transitions), Controllers (request flow), Concerns (mixin behavior), Services (processing pipelines), and Tests (what's being set up and why) when the test structure is non-obvious.
• Diagram maintenance is part of the change. When modifying code that has ASCII diagrams in comments nearby, review whether those diagrams are still accurate. Update them as part of the same commit. Stale diagrams are worse than no diagrams — they actively mislead. Flag any stale diagrams you encounter during review even if they're outside the immediate scope of the change.

BEFORE YOU START:

Design Doc Check

setopt +o nomatch 2>/dev/null || true  # zsh compat
SLUG=$(~/.claude/skills/browse/bin/remote-slug 2>/dev/null || 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 ~/.vibestack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.vibestack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1)
[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found"

If a design doc exists, read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a Supersedes: field, note that this is a revised design — check the prior version for context on what changed and why.

{{include lib/snippets/brain-preflight.md}}

Prerequisite Skill Offer

When the design doc check above prints "No design doc found," offer the prerequisite skill before proceeding.

Say to the user via AskUserQuestion:

"No design doc found for this branch. /office-hours produces a structured problem statement, premise challenge, and explored alternatives — it gives this review much sharper input to work with. Takes about 10 minutes. The design doc is per-feature, not per-product — it captures the thinking behind this specific change."

Options:

• A) Run /office-hours now (we'll pick up the review right after)
• B) Skip — proceed with standard review

If they skip: "No worries — standard review. If you ever want sharper input, try /office-hours first next time." Then proceed normally. Do not re-offer later in the session.

If they choose A:

Say: "Running /office-hours inline. Once the design doc is ready, I'll pick up the review right where we left off."

Read the /office-hours skill file at ~/.claude/skills/office-hours/SKILL.md using the Read tool.

If unreadable: Skip with "Could not load /office-hours — skipping." and continue.

Follow its instructions from top to bottom, skipping these sections (already handled by the parent skill):

• Preamble (run first)
• AskUserQuestion Format
• Completeness Principle — Boil the Lake
• Search Before Building
• Contributor Mode
• Completion Status Protocol
• Telemetry (run last)
• Step 0: Detect platform and base branch
• Review Readiness Dashboard
• Plan File Review Report
• Prerequisite Skill Offer
• Plan Status Footer

Execute every other section at full depth. When the loaded skill's instructions are complete, continue with the next step below.

After /office-hours completes, re-run the design doc check:

setopt +o nomatch 2>/dev/null || true  # zsh compat
SLUG=$(~/.claude/skills/browse/bin/remote-slug 2>/dev/null || 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 ~/.vibestack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.vibestack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1)
[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found"

If a design doc is now found, read it and continue the review. If none was produced (user may have cancelled), proceed with standard review.

Step 0: Scope Challenge

Before reviewing anything, answer these questions:

1. What existing code already partially or fully solves each sub-problem? Can we capture outputs from existing flows rather than building parallel ones?
2. What is the minimum set of changes that achieves the stated goal? Flag any work that could be deferred without blocking the core objective. Be ruthless about scope creep.
3. Complexity check: If the plan touches more than 8 files or introduces more than 2 new classes/services, treat that as a smell and 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:

• Does the runtime/framework have a built-in? Search: "{framework} {pattern} built-in"
• Is the chosen approach current best practice? Search: "{pattern} best practice {current year}"
• Are there known footguns? Search: "{framework} {pattern} pitfalls"

If WebSearch is unavailable, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only."

If the plan rolls a custom solution where a built-in exists, flag it as a scope reduction opportunity. Annotate recommendations with [Layer 1], [Layer 2], [Layer 3], or [EUREKA] (see preamble's Search Before Building section). If you find a eureka moment — a reason the standard approach is wrong for this case — present it as an architectural insight.

1. TODOS cross-reference: Read TODOS.md if it exists. Are any deferred items blocking this plan? Can any deferred items be bundled into this PR without expanding scope? Does this plan create new work that should be captured as a TODO?

1. Completeness check: Is the plan doing the complete version or a shortcut? With AI-assisted coding, the cost of completeness (100% test coverage, full edge case handling, complete error paths) is 10-100x cheaper than with a human team. If the plan proposes a shortcut that saves human-hours but only saves minutes with Claude Code + vibestack, recommend the complete version. Boil the lake.

1. Distribution check: If the plan introduces a new artifact type (CLI binary, library package, container image, mobile app), does it include the build/publish pipeline? Code without distribution is code nobody can use. Check:

• Is there a CI/CD workflow for building and publishing the artifact?
• Are target platforms defined (linux/darwin/windows, amd64/arm64)?
• How will users download or install it (GitHub Releases, package manager, container registry)?

If the plan defers distribution, flag it explicitly in the "NOT in scope" section — don't let it silently drop.

If the complexity check triggers (8+ files or 2+ new classes/services), proactively recommend scope reduction via AskUserQuestion — explain what's overbuilt, propose a minimal version that achieves the core goal, and ask whether to reduce or proceed as-is. If the complexity check does not trigger, present your Step 0 findings and proceed directly to Section 1.

Always work through the full interactive review: one section at a time (Architecture → Code Quality → Tests → Performance) with at most 8 top issues per section.

Critical: Once the user accepts or rejects a scope reduction recommendation, commit fully. Do not re-argue for smaller scope during later review sections. Do not silently reduce scope or skip planned components.

Review Sections (after scope is agreed)

Anti-skip rule: Never condense, abbreviate, or skip any review section (1-4) regardless of plan type (strategy, spec, code, infra). Every section in this skill exists for a reason. "This is a strategy doc so implementation sections don't apply" is always wrong — implementation details are where strategy breaks down. If a section genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.

Anti-shortcut clause: The plan file is the OUTPUT of the interactive review, not a substitute for it. Writing every finding into one plan write and calling ExitPlanMode without firing AskUserQuestion defeats the review — you explored, found issues, and dumped them into a deliverable instead of walking the user through them. If you have ANY non-trivial finding in any review section, the path from finding to ExitPlanMode goes THROUGH AskUserQuestion. Zero findings in every section is the only path to ExitPlanMode that bypasses AskUserQuestion. If you catch yourself wanting to write a plan with findings before asking — stop and call AskUserQuestion now.

{{include lib/snippets/prior-learnings.md}}

1. Architecture review

Evaluate:

• Overall 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 in 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 this introduces a new artifact (binary, package, container), how does it get built, published, and updated? Is the CI/CD pipeline part of the plan or deferred?

STOP. For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.

Confidence Calibration

Every finding MUST include a confidence score (1-10):

Finding format:

\[SEVERITY] (confidence: N/10) file:line — description\

Example: \[P1] (confidence: 9/10) app/models/user.rb:42 — SQL injection via string interpolation in where clause\ \[P2] (confidence: 5/10) app/controllers/api/v1/users_controller.rb:18 — Possible N+1 query, verify with production logs\

Pre-emit verification gate (kills the "field doesn't exist" FP class)

Before any finding is promoted to the report, the gate requires:

1. Quote the specific code line that motivates the finding — file:line plus

the verbatim text of the line(s) that triggered it. If the finding is "field X doesn't exist on model Y", quote the lines of class Y where the field would live. If "dict.get() might return None", quote the dict initialization. If "race condition between A and B", quote both A and B.

1. If you cannot quote the motivating line(s), the finding is unverified.

Force its confidence to 4-5 (suppressed from the main report). It still goes into the appendix so reviewers can audit calibration, but the user does NOT see it in the critical-pass output. Do not work around this by inventing speculative confidence 7+ — that defeats the gate.

Framework-meta nudge: When the symbol is generated by a framework metaclass, descriptor, ORM Meta inner-class, or migration history (Django Meta, Rails has_many/scope, SQLAlchemy relationship/Column, TypeORM decorators, Sequelize init/belongsTo, Prisma generated client), quote the meta-construct (the Meta block, the migration, the decorator, the schema file) instead of expecting the literal name in the class body. The verification is "I read the source that creates this symbol", not "I grep'd for the name and didn't find it." Deeper framework-aware verification (model introspection, migration-history-aware checks, ORM dialect detection) is deliberately out of scope for this lighter gate.

The FP classes this gate kills:

Calibration learning: If you report a finding with confidence < 7 and the user confirms it IS a real issue, that is a calibration event. Your initial confidence was too low. Log the corrected pattern as a learning so future reviews catch it with higher confidence.

2. Code quality review

Evaluate:

• Code organization and module structure.
• DRY violations—be aggressive here.
• Error handling patterns and missing edge cases (call these out explicitly).
• Technical debt hotspots.
• Areas that are over-engineered or under-engineered relative to my preferences.
• Existing ASCII diagrams in touched files — are they still accurate after this change?

STOP. For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.

3. Test review

100% coverage is the goal. Evaluate every codepath in the plan and ensure the plan includes tests for each one. If the plan is missing tests, add them — the plan should be complete enough that implementation includes full test coverage from the start.

Test Framework Detection

Before analyzing coverage, detect the project's test framework:

1. Read CLAUDE.md — look for a ## Testing section with test command and framework name. If found, use that as the authoritative source.
2. If CLAUDE.md has no testing section, auto-detect:

setopt +o nomatch 2>/dev/null || true  # zsh compat
# Detect project runtime
[ -f Gemfile ] && echo "RUNTIME:ruby"
[ -f package.json ] && echo "RUNTIME:node"
[ -f requirements.txt ] || [ -f pyproject.toml ] && echo "RUNTIME:python"
[ -f go.mod ] && echo "RUNTIME:go"
[ -f Cargo.toml ] && echo "RUNTIME:rust"
# Check for existing test infrastructure
ls jest.config.* vitest.config.* playwright.config.* cypress.config.* .rspec pytest.ini phpunit.xml 2>/dev/null
ls -d test/ tests/ spec/ __tests__/ cypress/ e2e/ 2>/dev/null

1. If no framework detected: still produce the coverage diagram, but skip test generation.

Step 1. Trace every codepath in the plan:

Read the plan document. For each new feature, service, endpoint, or component described, trace how data will flow through the code — don't just list planned functions, actually follow the planned execution:

1. Read the plan. For each planned component, understand what it does and how it connects to existing code.
2. Trace data flow. Starting from each entry point (route handler, exported function, event listener, component render), follow the data through every branch:

• Where does input come from? (request params, props, database, API call)
• What transforms it? (validation, mapping, computation)
• Where does it go? (database write, API response, rendered output, side effect)
• What can go wrong at each step? (null/undefined, invalid input, network failure, empty collection)

1. Diagram the execution. For each changed file, draw an ASCII diagram showing:

• Every function/method that was added or modified
• Every conditional branch (if/else, switch, ternary, guard clause, early return)
• Every error path (try/catch, rescue, error boundary, fallback)
• Every call to another function (trace into it — does IT have untested branches?)
• Every edge: what happens with null input? Empty array? Invalid type?

This is the critical step — you're building a map of every line of code that can execute differently based on input. Every branch in this diagram needs a test.

Step 2. Map user flows, interactions, and error states:

Code coverage isn't enough — you need to cover how real users interact with the changed code. For each changed feature, think through:

• User flows: What sequence of actions does a user take that touches this code? Map the full journey (e.g., "user clicks 'Pay' → form validates → API call → success/failure screen"). Each step in the journey needs a test.
• Interaction edge cases: What happens when the user does something unexpected?
• Double-click/rapid resubmit
• Navigate away mid-operation (back button, close tab, click another link)
• Submit with stale data (page sat open for 30 minutes, session expired)
• Slow connection (API takes 10 seconds — what does the user see?)
• Concurrent actions (two tabs, same form)
• Error states the user can see: For every error the code handles, what does the user actually experience?
• Is there a clear error message or a silent failure?
• Can the user recover (retry, go back, fix input) or are they stuck?
• What happens with no network? With a 500 from the API? With invalid data from the server?
• Empty/zero/boundary states: What does the UI show with zero results? With 10,000 results? With a single character input? With maximum-length input?

Add these to your diagram alongside the code branches. A user flow with no test is just as much a gap as an untested if/else.

Step 3. Check each branch against existing tests:

Go through your diagram branch by branch — both code paths AND user flows. For each one, search for a test that exercises it:

• Function processPayment() → look for billing.test.ts, billing.spec.ts, test/billing_test.rb
• An if/else → look for tests covering BOTH the true AND false path
• An error handler → look for a test that triggers that specific error condition
• A call to helperFn() that has its own branches → those branches need tests too
• A user flow → look for an integration or E2E test that walks through the journey
• An interaction edge case → look for a test that simulates the unexpected action

Quality scoring rubric:

• ★★★ Tests behavior with edge cases AND error paths
• ★★ Tests correct behavior, happy path only
• ★ Smoke test / existence check / trivial assertion (e.g., "it renders", "it doesn't throw")

E2E Test Decision Matrix

When checking each branch, also determine whether a unit test or E2E/integration test is the right tool:

RECOMMEND E2E (mark as [→E2E] in the diagram):

• Common user flow spanning 3+ components/services (e.g., signup → verify email → first login)
• Integration point where mocking hides real failures (e.g., API → queue → worker → DB)
• Auth/payment/data-destruction flows — too important to trust unit tests alone

RECOMMEND EVAL (mark as [→EVAL] in the diagram):

• Critical LLM call that needs a quality eval (e.g., prompt change → test output still meets quality bar)
• Changes to prompt templates, system instructions, or tool definitions

STICK WITH UNIT TESTS:

• Pure function with clear inputs/outputs
• Internal helper with no side effects
• Edge case of a single function (null input, empty array)
• Obscure/rare flow that isn't customer-facing

REGRESSION RULE (mandatory)

IRON RULE: When the coverage audit identifies a REGRESSION — code that previously worked but the diff broke — a regression test is added to the plan as a critical requirement. No AskUserQuestion. No skipping. Regressions are the highest-priority test because they prove something broke.

A regression is when:

• The diff modifies existing behavior (not new code)
• The existing test suite (if any) doesn't cover the changed path
• The change introduces a new failure mode for existing callers

When uncertain whether a change is a regression, err on the side of writing the test.

Step 4. Output ASCII coverage diagram:

Include BOTH code paths and user flows in the same diagram. Mark E2E-worthy and eval-worthy paths:

CODE PATHS                                            USER FLOWS
[+] src/services/billing.ts                           [+] Payment checkout
  ├── processPayment()                                  ├── [★★★ TESTED] Complete purchase — checkout.e2e.ts:15
  │   ├── [★★★ TESTED] happy + declined + timeout      ├── [GAP] [→E2E] Double-click submit
  │   ├── [GAP]         Network timeout                 └── [GAP]        Navigate away mid-payment
  │   └── [GAP]         Invalid currency
  └── refundPayment()                                 [+] Error states
      ├── [★★  TESTED] Full refund — :89                ├── [★★  TESTED] Card declined message
      └── [★   TESTED] Partial (non-throw only) — :101  └── [GAP]        Network timeout UX

LLM integration: [GAP] [→EVAL] Prompt template change — needs eval test

COVERAGE: 5/13 paths tested (38%)  |  Code paths: 3/5 (60%)  |  User flows: 2/8 (25%)
QUALITY: ★★★:2 ★★:2 ★:1  |  GAPS: 8 (2 E2E, 1 eval)

Legend: ★★★ behavior + edge + error | ★★ happy path | ★ smoke check [→E2E] = needs integration test | [→EVAL] = needs LLM eval

Fast path: All paths covered → "Test review: All new code paths have test coverage ✓" Continue.

Step 5. Add missing tests to the plan:

For each GAP identified in the diagram, add a test requirement to the plan. Be specific:

• What test file to create (match existing naming conventions)
• What the test should assert (specific inputs → expected outputs/behavior)
• Whether it's a unit test, E2E test, or eval (use the decision matrix)
• For regressions: flag as CRITICAL and explain what broke

The plan should be complete enough that when implementation begins, every test is written alongside the feature code — not deferred to a follow-up.

Test Plan Artifact

After producing the coverage diagram, write a test plan artifact to the project directory so /qa and /qa-only can consume it as primary test input:

eval "$(~/.vibestack/bin/vibe-slug 2>/dev/null)" && mkdir -p ~/.vibestack/projects/$SLUG
USER=$(whoami)
DATETIME=$(date +%Y%m%d-%H%M%S)

Write to ~/.vibestack/projects/{slug}/{user}-{branch}-eng-review-test-plan-{datetime}.md:

# Test Plan
Generated by /plan-eng-review on {date}
Branch: {branch}
Repo: {owner/repo}

## Affected Pages/Routes
- {URL path} — {what to test and why}

## Key Interactions to Verify
- {interaction description} on {page}

## Edge Cases
- {edge case} on {page}

## Critical Paths
- {end-to-end flow that must work}

This file is consumed by /qa and /qa-only as primary test input. Include only the information that helps a QA tester know what to test and where — not implementation details.

For LLM/prompt changes: check the "Prompt/LLM changes" file patterns listed in CLAUDE.md. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. Then use AskUserQuestion to confirm the eval scope with the user.

STOP. For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.

4. Performance review

Evaluate:

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

STOP. For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.

Outside Voice — Independent Plan Challenge (default-on)

After all review sections are complete, run an independent second opinion from a different AI system automatically — it is a standard step of plan review, not an opt-in. Two models agreeing on a plan is stronger signal than one model's thorough review.

Preflight — decide whether and how the outside voice runs:

_CODEX_CFG=$(~/.vibestack/bin/vibe-config get codex_reviews 2>/dev/null || echo enabled)
# Master switch: only the literal `disabled` turns the outside voice off. vibestack
# has no validating config binary, so treat any other value as enabled.
if [ "$_CODEX_CFG" = "disabled" ]; then
  CODEX_MODE="disabled"
elif ! command -v codex >/dev/null 2>&1; then
  CODEX_MODE="not_installed"
elif ! codex --version >/dev/null 2>&1; then
  CODEX_MODE="not_authed"
else
  CODEX_MODE="ready"
fi
echo "CODEX_MODE: $CODEX_MODE"

Branch on CODEX_MODE:

• `disabled` — skip this section entirely; do NOT fall back to a Claude subagent. Print: "Outside voice skipped (codex_reviews disabled). Re-enable: vibe-config set codex_reviews enabled." Continue to the next section.
• `not_installed` — Print: "Codex not installed — using a Claude subagent for the outside voice. Install for true cross-model coverage." Then run the outside voice via the Claude-subagent path below.
• `not_authed` — Print: "Codex installed but not authenticated — using a Claude subagent. Run codex login or set $CODEX_API_KEY." Then run the Claude-subagent path below.
• `ready` — run the Codex pass below.

Construct the plan review prompt. Read the plan file being reviewed (the file the user pointed this review at, or the branch diff scope). If a CEO plan document was written in Step 0D-POST, read that too — it contains the scope decisions and vision.

Construct this prompt (substitute the actual plan content — if plan content exceeds 30KB, truncate to the first 30KB and note "Plan truncated for size"). Always start with the filesystem boundary instruction:

"IMPORTANT: Do NOT read or execute any files under ~/.claude/, ~/.agents/, .claude/skills/, or agents/. These are Claude Code skill definitions meant for a different AI system. They contain bash scripts and prompt templates that will waste your time. Ignore them completely. Do NOT modify agents/openai.yaml. Stay focused on the repository code only.\n\nYou are a brutally honest technical reviewer examining a development plan that has already been through a multi-section review. Your job is NOT to repeat that review. Instead, find what it missed. Look for: logical gaps and unstated assumptions that survived the review scrutiny, overcomplexity (is there a fundamentally simpler approach the review was too deep in the weeds to see?), feasibility risks the review took for granted, missing dependencies or sequencing issues, and strategic miscalibration (is this the right thing to build at all?). Be direct. Be terse. No compliments. Just the problems.

THE PLAN: <plan content>"

If `CODEX_MODE` is `ready`:

TMPERR_PV=$(mktemp /tmp/codex-planreview-XXXXXXXX)
_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; }
command -v codex >/dev/null 2>&1 && codex exec "<prompt>" -C "$_REPO_ROOT" -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached < /dev/null 2>"$TMPERR_PV"

Use a 5-minute timeout (timeout: 300000). After the command completes, read stderr:

cat "$TMPERR_PV"

Present the full output verbatim:

CODEX SAYS (plan review — outside voice):
════════════════════════════════════════════════════════════
<full codex output, verbatim — do not truncate or summarize>
════════════════════════════════════════════════════════════

Error handling: All errors are non-blocking — the outside voice is informational.

• Auth failure (stderr contains "auth", "login", "unauthorized"): "Codex auth failed. Run \codex login\ to authenticate."
• Timeout: "Codex timed out after 5 minutes."
• Empty response: "Codex returned no response."

On any Codex error, fall back to the Claude adversarial subagent.

If `CODEX_MODE` is `not_installed` or `not_authed` (or Codex errored):

Dispatch via the Agent tool. The subagent has fresh context — genuine independence.

Subagent prompt: same plan review prompt as above.

Present findings under an OUTSIDE VOICE (Claude subagent): header.

If the subagent fails or times out: "Outside voice unavailable. Continuing to outputs."

Cross-model tension:

After presenting the outside voice findings, note any points where the outside voice disagrees with the review findings from earlier sections. Flag these as:

CROSS-MODEL TENSION:
  [Topic]: Review said X. Outside voice says Y. [Present both perspectives neutrally.
  State what context you might be missing that would change the answer.]

User Sovereignty: Do NOT auto-incorporate outside voice recommendations into the plan. Present each tension point to the user. The user decides. Cross-model agreement is a strong signal — present it as such — but it is NOT permission to act. You may state which argument you find more compelling, but you MUST NOT apply the change without explicit user approval.

For each substantive tension point, use AskUserQuestion:

"Cross-model disagreement on [topic]. The review found [X] but the outside voice argues [Y]. [One sentence on what context you might be missing.]"

>

RECOMMENDATION: Choose [A or B] because [one-line reason explaining which argument is more compelling and why]. Completeness: A=X/10, B=Y/10.

Options:

• A) Accept the outside voice's recommendation (I'll apply this change)
• B) Keep the current approach (reject the outside voice)
• C) Investigate further before deciding
• D) Add to TODOS.md for later

Wait for the user's response. Do NOT default to accepting because you agree with the outside voice. If the user chooses B, the current approach stands — do not re-argue.

If no tension points exist, note: "No cross-model tension — both reviewers agree."

Persist the result:

true # vibe-review-log '{"skill":"codex-plan-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}'

Substitute: STATUS = "clean" if no findings, "issues_found" if findings exist. SOURCE = "codex" if Codex ran, "claude" if subagent ran.

Cleanup: Run rm -f "$TMPERR_PV" after processing (if Codex was used).

Outside Voice Integration Rule

Outside voice findings are INFORMATIONAL until the user explicitly approves each one. Do NOT incorporate outside voice recommendations into the plan without presenting each finding via AskUserQuestion and getting explicit approval. This applies even when you agree with the outside voice. Cross-model consensus is a strong signal — present it as such — but the user makes the decision.

CRITICAL RULE — How to ask questions

Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:

• One issue = one AskUserQuestion call. Never combine multiple issues into one question.
• Describe the problem concretely, with file and line references.
• Present 2-3 options, including "do nothing" where that's reasonable.
• For each option, specify in one line: effort (human: ~X / CC: ~Y), risk, and maintenance burden. If the complete option is only marginally more effort than the shortcut with CC, recommend the complete option.
• Map the reasoning to my engineering preferences above. One sentence connecting your recommendation to a specific preference (DRY, explicit > clever, minimal diff, etc.).
• Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
• Coverage vs kind: for every per-issue AskUserQuestion you raise in this review, decide whether the options differ in coverage or in kind. If coverage (e.g., more tests vs fewer, complete error handling vs happy-path-only, full edge-case coverage vs shortcut), include Completeness: N/10 on each option. If kind (e.g., architectural choice between two different systems, posture-over-posture, A/B/C where each is a different kind of thing), skip the score and add one line: Note: options differ in kind, not coverage — no completeness score. Do NOT fabricate scores on kind-differentiated questions — filler scores are worse than no score.
• Escape hatch (tightened): If a section has zero findings, state "No issues, moving on" and proceed. If it has findings, use AskUserQuestion for each — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Only skip AskUserQuestion when the decision is genuinely trivial (e.g., a typo fix) AND there are no meaningful alternatives. When in doubt, ask.

{{include lib/snippets/tasks-section-emit.md}}

Required outputs

"NOT in scope" section

Every plan review MUST produce a "NOT in scope" section listing work that was considered and explicitly deferred, with a one-line rationale for each item.

"What already exists" section

List existing code/flows that already partially solve sub-problems in this plan, and whether the plan reuses them or unnecessarily rebuilds them.

TODOS.md updates

After all review sections are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in .claude/skills/review/TODOS-format.md.

For each TODO, describe:

• What: One-line description of the work.
• Why: The concrete problem it solves or value it unlocks.
• Pros: What you gain by doing this work.
• Cons: Cost, complexity, or risks of doing it.
• Context: Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
• Depends on / blocked by: Any prerequisites or ordering constraints.

Then present options: A) Add to TODOS.md B) Skip — not valuable enough C) Build it now in this PR instead of deferring.

Do NOT just append vague bullet points. A TODO without context is worse than no TODO — it creates false confidence that the idea was captured while actually losing the reasoning.

Diagrams

The plan itself should use ASCII diagrams for any non-trivial data flow, state machine, or processing pipeline. Additionally, identify which files in the implementation 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 identified in the test review diagram, list one realistic way it could fail in production (timeout, nil reference, race condition, stale data, etc.) 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 it as a critical gap.

Worktree parallelization strategy

Analyze the plan's implementation steps for parallel execution opportunities. This helps the user split work across git worktrees (via Claude Code's Agent tool with isolation: "worktree" or parallel workspaces).

Skip if: all steps touch the same primary module, or the plan has fewer than 2 independent workstreams. In that case, write: "Sequential implementation, no parallelization opportunity."

Otherwise, produce:

1. Dependency table — for each implementation step/workstream:

Work at the module/directory level, not file level. Plans describe intent ("add API endpoints"), not specific files. Module-level ("controllers/, models/") is reliable; file-level is guesswork.

1. Parallel lanes — group steps into lanes:

• Steps with no shared modules and no dependency go in separate lanes (parallel)
• Steps sharing a module directory go in the same lane (sequential)
• Steps depending on other steps go in later lanes

Format: Lane A: step1 → step2 (sequential, shared models/) / Lane B: step3 (independent)

1. Execution order — which lanes launch in parallel, which wait. Example: "Launch A + B in parallel worktrees. Merge both. Then C."

1. Conflict flags — if two parallel lanes touch the same module directory, flag it: "Lanes X and Y both touch module/ — potential merge conflict. Consider sequential execution or careful coordination."

Completion summary

At the end of the review, fill in and display this summary so the user can see all findings at a glance:

• 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

Retrospective learning

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

Formatting rules

• NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
• Label with NUMBER + LETTER (e.g., "3A", "3B").
• One sentence max per option. Pick in under 5 seconds.
• After each review section, pause and ask for feedback before moving on.

Review Log

After producing the Completion Summary above, persist the review result.

PLAN MODE EXCEPTION — ALWAYS RUN: This command writes review metadata to ~/.vibestack/ (user config directory, not project files). The review dashboard depends on this data. Skipping this command breaks the review readiness dashboard in /ship.

true # vibe-review-log '{"skill":"plan-eng-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"issues_found":N,"mode":"MODE","commit":"COMMIT"}'

Substitute values from the Completion Summary:

• TIMESTAMP: current ISO 8601 datetime
• STATUS: "clean" if 0 unresolved decisions AND 0 critical gaps; otherwise "issues_open"
• unresolved: number from "Unresolved decisions" count
• critical_gaps: number from "Failure modes: ___ critical gaps flagged"
• issues_found: total issues found across all review sections (Architecture + Code Quality + Performance + Test gaps)
• MODE: FULL_REVIEW / SCOPE_REDUCED
• COMMIT: output of git rev-parse --short HEAD

{{include lib/snippets/review-readiness-dashboard.md}}

Plan File Review Report

After displaying the Review Readiness Dashboard in conversation output, also update the plan file itself so review status is visible to anyone reading the plan.

Detect the plan file

1. Check if there is an active plan file in this conversation (the host provides plan file

paths in system messages — look for plan file references in the conversation context).

1. If not found, skip this section silently — not every review runs in plan mode.

Generate the report

Read the review log output you already have from the Review Readiness Dashboard step above. Parse each JSONL entry. Each skill logs different fields:

• plan-ceo-review: \status\, \unresolved\, \critical_gaps\, \mode\, \scope_proposed\, \scope_accepted\, \scope_deferred\, \commit\

→ Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred" → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"

• plan-eng-review: \status\, \unresolved\, \critical_gaps\, \issues_found\, \mode\, \commit\

→ Findings: "{issues_found} issues, {critical_gaps} critical gaps"

• plan-design-review: \status\, \initial_score\, \overall_score\, \unresolved\, \decisions_made\, \commit\

→ Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"

• plan-devex-review: \status\, \initial_score\, \overall_score\, \product_type\, \tthw_current\, \tthw_target\, \mode\, \persona\, \competitive_tier\, \unresolved\, \commit\

→ Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"

• devex-review: \status\, \overall_score\, \product_type\, \tthw_measured\, \dimensions_tested\, \dimensions_inferred\, \boomerang\, \commit\

→ Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"

• codex-review: \status\, \gate\, \findings\, \findings_fixed\

→ Findings: "{findings} findings, {findings_fixed}/{findings} fixed"

All fields needed for the Findings column are now present in the JSONL entries. For the review you just completed, you may use richer details from your own Completion Summary. For prior reviews, use the JSONL fields directly — they contain all required data.

Produce this markdown table:

\\\`markdown

VIBESTACK REVIEW REPORT

\\\`

Below the table, add these lines (omit CODEX / CROSS-MODEL when not applicable; VERDICT is always present):

• CODEX: (only if codex-review ran) — one-line summary of codex fixes
• CROSS-MODEL: (only if both Claude and Codex reviews exist) — overlap analysis
• VERDICT: list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").

If Eng Review is not CLEAR and not skipped globally, append "eng review required".

{{include lib/snippets/unresolved-decisions-status.md}}

Write to the plan file

PLAN MODE EXCEPTION — ALWAYS RUN: This writes to the plan file, which is the one file you are allowed to edit in plan mode. The plan file review report is part of the plan's living status.

Use a single delete-then-append flow — do NOT replace the section in place. The "replace mid-file" path is what lets an old report get left mid-file when content was added after it.

1. Search the plan file for a \## VIBESTACK REVIEW REPORT\ section anywhere in the file.
2. If found, delete the entire section — from \## VIBESTACK REVIEW REPORT\ through the next \## \ heading or end of file — to empty string with the Edit tool. If the Edit fails (concurrent edit changed the content), re-read the plan file and retry once.
3. Append the fresh report section at the END of the plan file.
4. Verify with the Read tool that \## VIBESTACK REVIEW REPORT\ is the last \## \ heading in the file. If it isn't, repeat steps 2-3 once.

{{include lib/snippets/exit-plan-mode-gate.md}}

{{include lib/snippets/askuserquestion-split.md}}

{{include lib/snippets/capture-learnings.md}}

Next Steps — Review Chaining

After displaying the Review Readiness Dashboard, check if additional reviews would be valuable. Read the dashboard output to see which reviews have already been run and whether they are stale.

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. If an existing design review's commit hash shows it predates significant changes found in this eng review, note that it may be stale.

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

Note staleness of existing CEO or design reviews if this eng review found assumptions that contradict them, or if the commit hash shows significant drift.

If no additional reviews are needed (or skip_eng_review is true in the dashboard config, meaning this eng review was optional): state "All relevant reviews complete. Run /ship when ready."

Use AskUserQuestion with only the 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

Unresolved decisions

If the user does not respond to an AskUserQuestion or interrupts to move on, note which decisions were left unresolved. At the end of the review, list these as "Unresolved decisions that may bite you later" — never silently default to an option.