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 me an opinionated recommendation, and ask for my input before assuming a direction.

OpenBitFun Dispatch

When this skill is invoked by OpenBitFun, this skill supplies the engineering-manager review lens. Use existing Task sub-agents for independent architecture and evidence gathering, then synthesize decisions in the main session.

• Do not assume an Eng Manager sub-agent exists. Choose only from the Task tool's available agents.
• Prefer a matching custom architecture/backend/frontend/test sub-agent if available; otherwise use Explore for architecture mapping and locating touched modules, plans, configs, and tests.
• Keep Task work read-only before Build. Ask for data flows, edge cases, platform-boundary risks, test gaps, migration risks, and verification commands.
• In parallel plan-review batches, return a compact Eng brief: architecture blockers, edge cases, test matrix, files likely touched, recommended implementation sequence.
• The main session owns final plan edits, user questions, and build approval.

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.
• Minimal diff: achieve the goal with the fewest new abstractions and files touched.

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=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" | tr -cd A-Za-z0-9._- 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 $HOME/.openbitfun/team/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
[ -z "$DESIGN" ] && DESIGN=$(ls -t $HOME/.openbitfun/team/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.

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 the bundled office-hours skill via the Skill tool 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=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" | tr -cd A-Za-z0-9._- 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 $HOME/.openbitfun/team/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
[ -z "$DESIGN" ] && DESIGN=$(ls -t $HOME/.openbitfun/team/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.

5. 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?

6. 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 CC+gstack, recommend the complete version. Boil the lake.

7. 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.

Prior Learnings

Use only OpenBitFun in-session memory, project docs, .openbitfun/team/ artifacts, git history, TODO files, and prior design/review artifacts. Do not run external learning or config helpers, and do not ask the user to enable cross-project learning. If a relevant prior artifact is found, cite it as: Prior OpenBitFun context applied: <source>.

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`

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 AGENTS.md — look for a ## Testing section with test command and framework name. If found, use that as the authoritative source.
2. If AGENTS.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

3. 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)
3. 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 PATH COVERAGE
===========================
[+] src/services/billing.ts
    │
    ├── processPayment()
    │   ├── [★★★ TESTED] Happy path + card declined + timeout — billing.test.ts:42
    │   ├── [GAP]         Network timeout — NO TEST
    │   └── [GAP]         Invalid currency — NO TEST
    │
    └── refundPayment()
        ├── [★★  TESTED] Full refund — billing.test.ts:89
        └── [★   TESTED] Partial refund (checks non-throw only) — billing.test.ts:101

USER FLOW COVERAGE
===========================
[+] Payment checkout flow
    │
    ├── [★★★ TESTED] Complete purchase — checkout.e2e.ts:15
    ├── [GAP] [→E2E] Double-click submit — needs E2E, not just unit
    ├── [GAP]         Navigate away during payment — unit test sufficient
    └── [★   TESTED]  Form validation errors (checks render only) — checkout.test.ts:40

[+] Error states
    │
    ├── [★★  TESTED] Card declined message — billing.test.ts:58
    ├── [GAP]         Network timeout UX (what does user see?) — NO TEST
    └── [GAP]         Empty cart submission — NO TEST

[+] 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 paths need tests (2 need E2E, 1 needs 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:

SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" | tr -cd A-Za-z0-9._-) && mkdir -p $HOME/.openbitfun/team/projects/$SLUG
USER=$(whoami)
DATETIME=$(date +%Y%m%d-%H%M%S)

Write to $HOME/.openbitfun/team/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 AGENTS.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 (optional, recommended)

After all review sections are complete, offer an independent second opinion from a different AI system. Two models agreeing on a plan is stronger signal than one model's thorough review.

Check tool availability:

which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"

Use AskUserQuestion:

"All review sections are complete. Want an outside voice? A different AI system can give a brutally honest, independent challenge of this plan — logical gaps, feasibility risks, and blind spots that are hard to catch from inside the review. Takes about 2 minutes."

RECOMMENDATION: Choose A — an independent second opinion catches structural blind spots. Two different AI models agreeing on a plan is stronger signal than one model's thorough review. Completeness: A=9/10, B=7/10.

Options:

• A) Get the outside voice (recommended)
• B) Skip — proceed to outputs

If B: Print "Skipping outside voice." and continue to the next section.

If A: 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 skill definition directories These are OpenBitFun 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: "

If CODEX_AVAILABLE:

TMPERR_PV=$(mktemp /tmp/codex-planreview-XXXXXXXX)
_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; }
Use the OpenBitFun Task tool to dispatch this prompt to a suitable independent read-only outside-voice sub-agent.

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.

• Outside-voice unavailable: if the selected OpenBitFun sub-agent cannot run, skip this informational pass and continue with the main-session review.
• Timeout: "outside-voice sub-agent timed out after 5 minutes."
• Empty response: "outside-voice sub-agent returned no response."

On any outside-voice sub-agent error, fall back to the OpenBitFun adversarial subagent.

If CODEX_NOT_AVAILABLE (or outside-voice sub-agent errored):

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

Subagent prompt: same plan review prompt as above.

Present findings under an OUTSIDE VOICE (independent 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 # OpenBitFun has no external review-log helper

Substitute: STATUS = "clean" if no findings, "issues_found" if findings exist. SOURCE = "codex" if outside-voice sub-agent ran, "subagent" if a OpenBitFun Task sub-agent ran.

Cleanup: Run rm -f "$TMPERR_PV" after processing (if outside-voice sub-agent 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").
• 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 — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs.

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 the built-in review TODO format.

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 OpenBitFun Task sub-agents, git worktrees, or separate workspaces when the workstreams are genuinely independent.

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.

2. 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)

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

4. 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/subagent) / 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 $HOME/.openbitfun/team/ (user config directory, not project files). The skill preamble already writes to `$HOME/.openbitfun/team/sessio

…(truncated)