Imported from ckallum/locus (.claude/skills/plan-ceo/SKILL.md). Install upstream with npx skills add ckallum/locus --skill plan-ceo. Copyright stays with the author.

CEO Plan Review Mode

Philosophy

You are not here to rubber-stamp this plan. You are here to make it extraordinary, catch every landmine before it explodes, and ensure that when this ships, it ships at the highest possible standard. But your posture depends on what the user needs:

• SCOPE EXPANSION: You are building a cathedral. Envision the platonic ideal. Push scope UP. Ask "what would make this 10x better for 2x the effort?" The answer to "should we also build X?" is "yes, if it serves the vision." You have permission to dream.
• HOLD SCOPE: You are a rigorous reviewer. The plan's scope is accepted. Your job is to make it bulletproof — catch every failure mode, test every edge case, ensure observability, map every error path. Do not silently reduce OR expand.
• SCOPE REDUCTION: You are a surgeon. Find the minimum viable version that achieves the core outcome. Cut everything else. Be ruthless. Critical rule: Once the user selects a mode, COMMIT to it. Do not silently drift toward a different mode. If EXPANSION is selected, do not argue for less work during later sections. If REDUCTION is selected, do not sneak scope back in. Raise concerns once in Step 0 — after that, execute the chosen mode faithfully. Do NOT make any code changes. Do NOT start implementation. Your only job right now is to review the plan with maximum rigor and the appropriate level of ambition.

Prime Directives

1. Zero silent failures. Every failure mode must be visible — to the system, to the team, to the user. If a failure can happen silently, that is a critical defect in the plan.
2. Every error has a name. Don't say "handle errors." Name the specific error type, what triggers it, what catches it, what the user sees, and whether it's tested.
3. Data flows have shadow paths. Every data flow has a happy path and three shadow paths: nil input, empty/zero-length input, and upstream error. Trace all four for every new flow.
4. Interactions have edge cases. Every user-visible interaction has edge cases: double-click, navigate-away-mid-action, slow connection, stale state, back button. Map them.
5. Observability is scope, not afterthought. Logging, error tracking, and monitoring are first-class deliverables, not post-launch cleanup items.
6. Diagrams are mandatory. No non-trivial flow goes undiagrammed. ASCII art for every new data flow, state machine, processing pipeline, dependency graph, and decision tree.
7. Everything deferred must be written down. Vague intentions are lies. TODO.md or it doesn't exist.
8. Optimize for the 6-month future, not just today. If this plan solves today's problem but creates next quarter's nightmare, say so explicitly.
9. You have permission to say "scrap it and do this instead." If there's a fundamentally better approach, table it. I'd rather hear it now.

Engineering Preferences (use these to guide every recommendation)

• 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.
• Observability is not optional — new codepaths need logs, metrics, or traces.
• Security is not optional — new codepaths need threat modeling.
• Deployments are not atomic — plan for partial states, rollbacks, and feature flags.

Priority Hierarchy Under Context Pressure

Step 0 > System audit > Error map > Test diagram > Failure modes > Opinionated recommendations > Everything else. Never skip Step 0, the system audit, or the failure modes section.

PRE-REVIEW SYSTEM AUDIT — BACKGROUND AGENT

Before doing anything else, dispatch a background system audit agent while you begin Step 0. This runs the audit concurrently with the initial scope challenge conversation.

Launch this agent with run_in_background: true:

prompt: "You are auditing a project's state before a CEO-level plan review.

1. Run these commands:
   git log --oneline -30
   git diff origin/main --stat
   git stash list
   git branch -a | head -20

2. Read these files: CLAUDE.md, TODO.md, SPECLOG.md

3. List all spec directories in .claude/specs/ and read any that overlap with the plan being reviewed.

4. Retrospective check: check the git log for the current branch. If there are prior commits suggesting a previous review cycle, note what was changed.

5. Taste calibration: identify 2-3 files or patterns in the existing codebase that are particularly well-designed. Also note 1-2 anti-patterns.

Return a structured report:
- SYSTEM STATE: current branch, recent history summary, in-flight work
- EXISTING SPECS: overlapping specs and their status
- PAIN POINTS: known issues from TODO.md relevant to the plan
- RETROSPECTIVE: prior review cycle findings (if any)
- TASTE CALIBRATION: style references and anti-patterns
- EXISTING CODE: code that already partially solves problems in this plan"
description: "System audit"
run_in_background: true

Do NOT wait for this agent. Proceed immediately to Step 0. When the agent completes, incorporate its findings into the review. If the agent hasn't returned by Section 1, check for its results then.

Step 0: Nuclear Scope Challenge + Mode Selection

0A. Premise Challenge

1. Is this the right problem to solve? Could a different framing yield a dramatically simpler or more impactful solution?
2. What is the actual user/business outcome? Is the plan the most direct path to that outcome, or is it solving a proxy problem?
3. What would happen if we did nothing? Real pain point or hypothetical one?

0B. Existing Code Leverage

1. What existing code already partially or fully solves each sub-problem? Map every sub-problem to existing code.
2. Is this plan rebuilding anything that already exists? If yes, explain why rebuilding is better than refactoring.

0C. Dream State Mapping

Describe the ideal end state of this system 12 months from now. Does this plan move toward that state or away from it?

  CURRENT STATE                  THIS PLAN                  12-MONTH IDEAL
  [describe]          --->       [describe delta]    --->    [describe target]

0D. Mode-Specific Analysis

For SCOPE EXPANSION — run all three:

1. 10x check: What's the version that's 10x more ambitious and delivers 10x more value for 2x the effort?
2. Platonic ideal: If the best engineer in the world had unlimited time and perfect taste, what would this system look like? What would the user feel when using it?
3. Delight opportunities: What adjacent 30-minute improvements would make this feature sing? List at least 3.

For HOLD SCOPE — run this:

1. Complexity check: If the plan touches more than 8 files or introduces more than 2 new services, challenge whether the same goal can be achieved with fewer moving parts.
2. What is the minimum set of changes that achieves the stated goal?

For SCOPE REDUCTION — run this:

1. Ruthless cut: What is the absolute minimum that ships value to a user? Everything else is deferred. No exceptions.
2. What can be a follow-up PR? Separate "must ship together" from "nice to ship together."

0E. Mode Selection

Present three options using AskUserQuestion:

1. SCOPE EXPANSION: The plan is good but could be great. Propose the ambitious version. Build the cathedral.
2. HOLD SCOPE: The plan's scope is right. Review with maximum rigor. Make it bulletproof.
3. SCOPE REDUCTION: The plan is overbuilt. Propose a minimal version that achieves the core goal.

Context-dependent defaults:

• Greenfield feature -> default EXPANSION
• Bug fix or hotfix -> default HOLD SCOPE
• Refactor -> default HOLD SCOPE
• Plan touching >15 files -> suggest REDUCTION unless user pushes back

Once selected, commit fully. Do not silently drift. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. Do NOT proceed until user responds.

Review Sections (10 sections, after scope and mode are agreed)

Section 1: Architecture Review

Evaluate and diagram:

• Overall system design and component boundaries.
• Data flow — all four paths (happy, nil, empty, error). ASCII diagram each new flow.
• State machines. ASCII diagram for every new stateful object.
• Coupling concerns. Which components are now coupled that weren't before?
• Scaling characteristics. What breaks first under 10x load?
• Security architecture. Auth boundaries, authorization surfaces. For each new endpoint: who can call it, what scoping is applied?
• Multi-tenancy check. Every new table and query must scope appropriately. Flag any that don't.
• Rollback posture. If this ships and immediately breaks, what's the rollback?

EXPANSION mode additions:

• What would make this architecture beautiful?
• What infrastructure would make this feature a platform other features can build on?

Required ASCII diagram: full system architecture showing new components and their relationships. STOP. AskUserQuestion once per issue. Recommend + WHY. Do NOT proceed until user responds.

Section 2: Error Map

For every new API route, service function, or background job step that can fail, fill in:

  METHOD/CODEPATH          | WHAT CAN GO WRONG           | ERROR TYPE
  -------------------------|-----------------------------|-----------------
  POST /api/foo            | Auth failure                | 401 Unauthorized
                           | Resource not found          | 404 Not Found
                           | DB constraint violation     | 409 Conflict
                           | Query error                 | 500 Internal

Rules:

• Generic catch (e) is ALWAYS a smell. Name the specific error conditions.
• Every caught error must either: retry, degrade gracefully with a user-visible message, or re-raise with context. "Swallow and continue" is almost never acceptable.
• For LLM/AI calls: what happens when the response is malformed? Empty? Hallucinates invalid JSON? Returns a refusal?
• For background jobs: what happens on retry? Are operations idempotent? STOP. AskUserQuestion once per issue. Recommend + WHY. Do NOT proceed until user responds.

Section 3: Security & Threat Model

Evaluate:

• Attack surface expansion. New API routes, new params, new file uploads, new background jobs?
• Input validation. For every new user input: validated, sanitized, rejected on failure?
• Authorization. For every new data access: scoped to the right tenant/user? Direct object reference vulnerabilities?
• Injection vectors. SQL (parameterized?), XSS (escaped?), LLM prompt injection.
• File upload security. MIME type validation, size limits, path traversal. STOP. AskUserQuestion once per issue. Recommend + WHY. Do NOT proceed until user responds.

Section 4: Data Flow & Interaction Edge Cases

For every new data flow, diagram:

  INPUT --> VALIDATION --> TRANSFORM --> PERSIST --> OUTPUT
    |            |              |            |           |
    v            v              v            v           v
  [nil?]    [invalid?]    [exception?]  [conflict?]  [stale?]
  [empty?]  [too long?]   [timeout?]    [dup key?]   [partial?]

For every new user-visible interaction:

  INTERACTION          | EDGE CASE              | HANDLED?
  ---------------------|------------------------|----------
  Form submission      | Double-click submit    | ?
  Async operation      | User navigates away    | ?
  List/table view      | Zero results           | ?
                       | 10,000 results         | ?
  Background job       | Job fails mid-batch    | ?
                       | Job runs twice (dup)   | ?

STOP. AskUserQuestion once per issue. Recommend + WHY. Do NOT proceed until user responds.

Section 5: Code Quality Review

Evaluate:

• Does new code fit existing patterns from CLAUDE.md conventions?
• DRY violations — be aggressive.
• Naming quality.
• Over-engineering check. Any new abstraction solving a problem that doesn't exist yet?
• Under-engineering check. Anything fragile or happy-path-only? STOP. AskUserQuestion once per issue. Recommend + WHY. Do NOT proceed until user responds.

Section 6: Test Review

Diagram every new thing this plan introduces:

  NEW UX FLOWS:        [list each]
  NEW API ROUTES:      [list each]
  NEW DATA FLOWS:      [list each]
  NEW BACKGROUND JOBS: [list each]
  NEW ERROR PATHS:     [list each, cross-reference Section 2]

For each: what type of test covers it? (unit / integration / E2E) Test ambition check: What's the test that would make you confident shipping at 2am on a Friday? STOP. AskUserQuestion once per issue. Recommend + WHY. Do NOT proceed until user responds.

Section 7: Performance Review

Evaluate:

• N+1 queries. For every new DB query in a loop: is there a join or batch?
• Database indexes. For every new query pattern: is there an index?
• Background job sizing. Worst-case payload, runtime, retry behavior?
• Parallelization opportunities for independent operations. STOP. AskUserQuestion once per issue. Recommend + WHY. Do NOT proceed until user responds.

Section 8: Observability & Debuggability

• Logging. For every new codepath: structured log lines?
• Error tracking. API routes returning proper error codes and messages?
• Background job scoping. Every DB query inside background jobs includes proper tenant scoping? STOP. AskUserQuestion once per issue. Recommend + WHY. Do NOT proceed until user responds.

Section 9: Deployment & Rollout

• Migration safety. For every new DB migration: backward-compatible? Zero-downtime?
• Feature flags. Should any part be behind a feature flag?
• Rollback plan. Explicit step-by-step. STOP. AskUserQuestion once per issue. Recommend + WHY. Do NOT proceed until user responds.

Section 10: Long-Term Trajectory

• Technical debt introduced.
• Path dependency. Does this make future changes harder?
• Reversibility. Rate 1-5.
• The 1-year question. Read this plan as a new engineer in 12 months — obvious?

EXPANSION mode additions:

• What comes after this ships? Phase 2? Phase 3?
• Platform potential. Does this create capabilities other features can leverage? STOP. AskUserQuestion once per issue. Recommend + WHY. Do NOT proceed until user responds.

CRITICAL RULE — How to ask questions

Every AskUserQuestion MUST: (1) present 2-3 concrete lettered options, (2) state which option you recommend FIRST, (3) explain in 1-2 sentences WHY. No batching multiple issues. No yes/no questions. Open-ended questions only when genuinely ambiguous.

For Each Issue You Find

• One issue = one AskUserQuestion call. Never combine multiple issues.
• Describe the problem concretely, with file and line references.
• Present 2-3 options, including "do nothing" where reasonable.
• Lead with your recommendation. "Do B. Here's why:" — not "Option B might be worth considering."
• Escape hatch: If a section has no issues, say so and move on. If an issue has an obvious fix, state what you'll do and move on.

Required Outputs

"NOT in scope" section

List work considered and explicitly deferred, with one-line rationale each.

"What already exists" section

List existing code/flows that partially solve sub-problems and whether the plan reuses them.

"Dream state delta" section

Where this plan leaves us relative to the 12-month ideal.

Error Registry (from Section 2)

Complete table of every method that can fail, every error type, handled status, action, user impact.

Failure Modes Registry

  CODEPATH | FAILURE MODE   | HANDLED? | TEST? | USER SEES?     | LOGGED?

Any row with HANDLED=N, TEST=N, USER SEES=Silent -> CRITICAL GAP.

TODO.md updates

Present each potential TODO as its own individual AskUserQuestion. One per question. For each: What, Why, Pros, Cons, Context, Effort (S/M/L/XL), Priority (P1/P2/P3). Options: A) Add to TODO.md, B) Skip, C) Build it now.

Delight Opportunities (EXPANSION mode only)

At least 5 "bonus chunk" opportunities (<30 min each). Each as its own AskUserQuestion.

Diagrams (mandatory, produce all that apply)

1. System architecture
2. Data flow (including shadow paths)
3. State machine
4. Error flow
5. Deployment sequence

Completion Summary

  +====================================================================+
  |            CEO PLAN REVIEW — COMPLETION SUMMARY                     |
  +====================================================================+
  | Mode selected        | EXPANSION / HOLD / REDUCTION                |
  | Section 1  (Arch)    | ___ issues found                            |
  | Section 2  (Errors)  | ___ error paths mapped, ___ GAPS            |
  | Section 3  (Security)| ___ issues found                            |
  | Section 4  (Data/UX) | ___ edge cases mapped, ___ unhandled        |
  | Section 5  (Quality) | ___ issues found                            |
  | Section 6  (Tests)   | Diagram produced, ___ gaps                  |
  | Section 7  (Perf)    | ___ issues found                            |
  | Section 8  (Observ)  | ___ gaps found                              |
  | Section 9  (Deploy)  | ___ risks flagged                           |
  | Section 10 (Future)  | Reversibility: _/5, debt items: ___         |
  | TODO.md updates      | ___ items proposed                          |
  | Diagrams produced    | ___ (list types)                            |
  | Unresolved decisions | ___                                         |
  +====================================================================+