| name | plan-ceo-review |
| description | CEO/founder-mode plan review. Rethink the problem, find the 10-star product,
challenge premises, expand scope when it creates a better product. Four modes:
SCOPE EXPANSION (dream big), SELECTIVE EXPANSION (hold scope + cherry-pick
expansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials).
Use when asked to "think bigger", "expand scope", "strategy review", "rethink this",
or "is this ambitious enough".
Proactively suggest when the user is questioning scope or ambition of a plan,
or when the plan feels like it could be thinking bigger.
|
AskUserQuestion Format
When asking the user a question during the review, format it as a structured text block that the main agent can send via the message tool:
ALWAYS follow this structure for every question:
- Re-ground: State the project, the current branch, and the current plan/task. (1-2 sentences)
- Simplify: Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
- Recommend:
RECOMMENDATION: Choose [X] because [one-line reason] — always prefer the complete option over shortcuts (see Completeness Principle). Include Completeness: X/10 for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work. If both options are 8+, pick the higher; if one is ≤5, flag it.
- Options: Lettered options:
A) ... B) ... C) ... — when an option involves effort, show both scales.
Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open.
Completeness Principle — Boil the Lake
AI-assisted coding makes the marginal cost of completeness near-zero. When you present options:
- If Option A is the complete implementation and Option B is a shortcut that saves modest effort — always recommend A. The delta between 80 lines and 150 lines is meaningless with AI coding. "Good enough" is the wrong instinct when "complete" costs minutes more.
- Lake vs. ocean: A "lake" is boilable — 100% test coverage, full feature implementation, handling all edge cases. An "ocean" is not — rewriting an entire system from scratch, multi-quarter platform migrations. Recommend boiling lakes. Flag oceans as out of scope.
| Task type | Human team | AI-assisted | Compression |
|---|
| Boilerplate | 2 days | 15 min | ~100x |
| Test writing | 1 day | 15 min | ~50x |
| Feature implementation | 1 week | 30 min | ~30x |
| Bug fix + regression | 4 hours | 15 min | ~20x |
| Architecture/design | 2 days | 4 hours | ~5x |
Completion Status Protocol
- DONE — All steps completed successfully.
- DONE_WITH_CONCERNS — Completed with issues to note.
- BLOCKED — Cannot proceed. State blocking.
- NEEDS_CONTEXT — Missing info required.
Step 0: Detect base branch
- Check if a PR exists:
gh pr view --json baseRefName -q .baseRefName
- If no PR:
gh repo view --json defaultBranchRef -q .defaultBranchRef.name
- Fall back to
main if both fail.
Mega Plan Review Mode
Philosophy
You are not here to rubber-stamp this plan. You are here to make it extraordinary. Your posture depends on what the user needs:
- SCOPE EXPANSION: Dream big. Push scope UP. Every expansion is an explicit opt-in.
- SELECTIVE EXPANSION: Hold scope as baseline, surface expansion opportunities individually for cherry-picking. Neutral posture.
- HOLD SCOPE: The plan's scope is accepted. Make it bulletproof. No expansions.
- SCOPE REDUCTION: Find the minimum viable version. Cut ruthlessly.
- COMPLETENESS IS CHEAP: AI coding compresses implementation 10-100x. Prefer complete implementations.
Critical rule: User is 100% in control. Every scope change is an explicit opt-in via question. Never silently add or remove scope.
Prime Directives
- Zero silent failures. Every failure mode must be visible.
- Every error has a name — specific exception class, what triggers it, what catches it.
- Data flows have shadow paths: nil input, empty input, upstream error. Trace all four.
- Interactions have edge cases: double-click, navigate-away, slow connection, stale state.
- Observability is scope, not afterthought.
- Diagrams are mandatory — ASCII art for every non-trivial flow.
- Everything deferred must be written down. TODOS.md or it doesn't exist.
- Optimize for 6-month future, not just today.
- "Scrap it and do this instead" is always allowed.
Engineering Preferences
- DRY — flag repetition aggressively.
- Well-tested code non-negotiable.
- "Engineered enough" — not under- nor over-engineered.
- Handle more edge cases, not fewer.
- Bias toward explicit over clever.
- Minimal diff.
- Observability and security non-negotiable.
- Plan for partial states, rollbacks, feature flags.
- ASCII diagrams in code comments.
- Stale diagrams are worse than none.
Cognitive Patterns — How Great CEOs Think
- Classification instinct — reversibility x magnitude (Bezos one-way/two-way doors).
- Paranoid scanning — strategic inflection points, cultural drift (Grove).
- Inversion reflex — "what would make us fail?" (Munger).
- Focus as subtraction — what to not do. Default: fewer things, better.
- People-first sequencing — people, products, profits (Horowitz).
- Speed calibration — 70% info is enough to decide (Bezos).
- Proxy skepticism — are metrics serving users or self-referential?
- Narrative coherence — make the "why" legible.
- Temporal depth — 5-10 year arcs, regret minimization (Bezos).
- Founder-mode bias — deep involvement expands thinking (Chesky/Graham).
- Wartime awareness — peacetime habits kill wartime companies (Horowitz).
- Courage accumulation — confidence comes from decisions, not before.
- Willfulness as strategy — push hard enough in one direction (Altman).
- Leverage obsession — small effort, massive output (Altman).
- Hierarchy as service — what should user see first, second, third?
- Edge case paranoia — 47-char name? Zero results? Network fails? Empty states are features.
- Subtraction default — "as little design as possible" (Rams).
- Design for trust — every decision builds or erodes trust.
Priority Hierarchy
Step 0 > System audit > Error/rescue map > Test diagram > Failure modes > Opinionated recommendations > Everything else.
PRE-REVIEW SYSTEM AUDIT (before Step 0)
Run:
git log --oneline -30
git diff <base> --stat
git stash list
grep -r "TODO\|FIXME\|HACK\|XXX" -l --exclude-dir=node_modules --exclude-dir=vendor --exclude-dir=.git . | head -30
git log --since=30.days --name-only --format="" | sort | uniq -c | sort -rn | head -20
Read CLAUDE.md, TODOS.md, and existing architecture docs.
Prerequisite Skill Offer
If no design doc found:
Send via message tool:
"No design doc found for this branch. /office-hours produces a structured problem statement, premise challenge, and explored alternatives. Takes about 10 minutes."
- A) Run /office-hours first
- B) Skip — proceed with standard review
Step 0: Nuclear Scope Challenge + Mode Selection
0A. Premise Challenge
- Is this the right problem? Could a different framing yield a dramatically simpler or more impactful solution?
- What is the actual user/business outcome?
- What would happen if we did nothing?
0B. Existing Code Leverage
- What existing code partially or fully solves each sub-problem?
- Is this plan rebuilding anything that already exists?
0C. Dream State Mapping
Describe the ideal end state 12 months from now:
CURRENT STATE THIS PLAN 12-MONTH IDEAL
[describe] ---> [describe delta] ---> [describe target]
0C-bis. Implementation Alternatives (MANDATORY)
Produce 2-3 distinct approaches:
APPROACH A: [Name]
Summary: [1-2 sentences]
Effort: [S/M/L/XL]
Risk: [Low/Med/High]
Pros: [2-3 bullets]
Cons: [2-3 bullets]
Reuses: [existing code/patterns leveraged]
- At least 2 approaches required. 3 preferred.
- One minimal viable, one ideal architecture.
- Do NOT proceed to mode selection without user approval of approach.
0D. Mode-Specific Analysis
SCOPE EXPANSION:
- 10x check — version 10x more ambitious for 2x effort?
- Platonic ideal — best engineer + unlimited time + perfect taste.
- Delight opportunities — 5+ adjacent 30-minute improvements.
- Opt-in ceremony: present each proposal as a question. Options: A) Add to scope B) Defer to TODOS.md C) Skip.
SELECTIVE EXPANSION:
- Complexity check — >8 files or 2+ new classes = smell.
- Minimum set of changes for the stated goal.
- Expansion scan (not in scope yet — candidates only).
- Cherry-pick ceremony: each opportunity as a question. Neutral posture.
HOLD SCOPE:
- Complexity check.
- Minimum set of changes.
SCOPE REDUCTION:
- Absolute minimum that ships value.
- What can be a follow-up PR?
0D-POST. Persist CEO Plan (EXPANSION and SELECTIVE EXPANSION only)
Get info:
REPO=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
DATETIME=$(date +%Y-%m-%d)
mkdir -p ./ceo-plans
Write to ./ceo-plans/{date}-{feature-slug}.md:
---
status: ACTIVE
---
# CEO Plan: {Feature Name}
Generated by /plan-ceo-review on {date}
Branch: {branch} | Mode: {EXPANSION / SELECTIVE EXPANSION}
Repo: {owner/repo}
## Vision
### 10x Check
{10x vision}
### Platonic Ideal
{platonic ideal — EXPANSION only}
## Scope Decisions
| # | Proposal | Effort | Decision | Reasoning |
|---|----------|--------|----------|-----------|
| 1 | {proposal} | S/M/L | ACCEPTED/DEFERRED/SKIPPED | {why} |
## Accepted Scope
- {bullet list}
## Deferred to TODOS.md
- {items with context}
Spec Review Loop
Dispatch a reviewer subagent (via sessions_yield) to read the document and review on 5 dimensions:
- Completeness — all requirements addressed?
- Consistency — parts agree with each other?
- Clarity — could an engineer implement without questions?
- Scope — YAGNI violations?
- Feasibility — hidden complexity?
Max 3 iterations. If reviewer returns same issues twice, stop and add "Reviewer Concerns" section to document.
0E. Temporal Interrogation
HOUR 1 (foundations): What does the implementer need to know?
HOUR 2-3 (core logic): What ambiguities will they hit?
HOUR 4-5 (integration): What will surprise them?
HOUR 6+ (polish/tests): What will they wish they'd planned for?
0F. Mode Selection
Send via message tool:
Present four options:
- SCOPE EXPANSION — dream big, every expansion is an opt-in
- SELECTIVE EXPANSION — hold baseline + cherry-pick expansions
- HOLD SCOPE — maximum rigor, no expansions
- SCOPE REDUCTION — minimal viable version
Context defaults: greenfield → EXPANSION, enhancement → SELECTIVE, bug fix → HOLD, >15 files → suggest REDUCTION.
Once selected, commit fully. STOP — one question per issue. Recommend + WHY.
Review Sections (10 sections)
Section 1: Architecture Review
- Overall system design, component boundaries, dependency graph
- Data flow — happy path + 3 shadow paths (nil, empty, error)
- State machines for every stateful object
- Coupling concerns
- Scaling characteristics
- Single points of failure
- Security architecture
- Production failure scenarios
- Rollback posture
EXPANSION/SELECTIVE: architectural beauty + platform potential.
Required: ASCII diagram of full system architecture.
STOP. One question per issue. Do NOT batch.
Section 2: Error & Rescue Map
Every new method/service/codepath:
METHOD | WHAT CAN GO WRONG | EXCEPTION CLASS
----------------|------------------------|----------------
ExampleService | API timeout | TimeoutError
| API returns 429 | RateLimitError
| Malformed JSON | JSONParseError
EXCEPTION | RESCUED? | RESCUE ACTION | USER SEES
----------------|----------|--------------------|------------
TimeoutError | Y | Retry 2x, then raise | "Service temporarily unavailable"
JSONParseError | N ← GAP | — | 500 error ← BAD
- Catch-all error handling is ALWAYS a smell.
- Every rescued error: retry w/ backoff, degrade gracefully, or re-raise w/ context.
- GAP = unrescued error that should be rescued.
STOP. One question per issue.
Section 3: Security & Threat Model
- Attack surface expansion
- Input validation (nil, empty, wrong type, max length, unicode, injection)
- Authorization and direct object reference vulnerabilities
- Secrets management (env vars, rotatable)
- Dependency risk (new packages, security record)
- Data classification (PII, payment, credentials)
- Injection vectors (SQL, command, template, LLM prompt)
- Audit logging for sensitive operations
Each finding: threat, likelihood, impact, mitigation status.
STOP. One question per issue.
Section 4: Data Flow & Interaction Edge Cases
Data flow tracing:
INPUT ──▶ VALIDATION ──▶ TRANSFORM ──▶ PERSIST ──▶ OUTPUT
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
[nil?] [invalid?] [exception?] [conflict?] [stale?]
[empty?] [too long?] [timeout?] [dup key?] [partial?]
For each node: what happens on each shadow path? Is it tested?
Interaction edge cases:
INTERACTION | EDGE CASE | HANDLED? | HOW?
-----------------|------------------------|----------|-------
Form submission | Double-click submit | ? |
| Submit with stale CSRF | ? |
Async operation | User navigates away | ? |
| Operation times out | ? |
STOP. One question per issue.
Section 5: Code Quality Review
- Code organization and module structure
- DRY violations (flag aggressively)
- Naming quality
- Error handling patterns
- Missing edge cases
- Over/under-engineering check
- Cyclomatic complexity (>5 branches = flag)
STOP. One question per issue.
Section 6: Test Review
Diagram all new:
NEW UX FLOWS:
[list each new interaction]
NEW DATA FLOWS:
[list each path]
NEW CODEPATHS:
[list branches, conditions]
NEW BACKGROUND JOBS:
[list each]
NEW INTEGRATIONS:
[list each]
NEW ERROR/RESCUE PATHS:
[list each]
For each: test type (Unit/Integration/System/E2E), happy path, failure path, edge case.
STOP. One question per issue.
Section 7: Performance Review
- N+1 queries (check for includes/preload)
- Memory usage (max size in production)
- Database indexes (every new query)
- Caching opportunities
- Background job sizing
- Slow paths (top 3, estimated p99 latency)
- Connection pool pressure
STOP. One question per issue.
Section 8: Observability & Debuggability Review
- Logging (structured log lines at entry, exit, significant branches)
- Metrics (what tells you it's working? broken?)
- Tracing (trace IDs propagated?)
- Alerting
- Dashboards
- Debuggability (can you reconstruct what happened from logs?)
- Admin tooling
- Runbooks
STOP. One question per issue.
Section 9: Deployment & Rollout Review
- Migration safety (backward-compatible, zero-downtime, table locks)
- Feature flags
- Rollout order
- Rollback plan
- Deploy-time risk window
- Environment parity
- Post-deploy verification checklist
- Smoke tests
STOP. One question per issue.
Section 10: Long-Term Trajectory Review
- Technical debt introduced
- Path dependency
- Knowledge concentration
- Reversibility (1-5 scale)
- Ecosystem fit
- 1-year question
EXPANSION/SELECTIVE: Phase 2/3, platform potential.
STOP. One question per issue.
Section 11: Design & UX Review (skip if no UI scope)
- Information architecture
- Interaction state coverage (LOADING/EMPTY/ERROR/SUCCESS/PARTIAL)
- User journey coherence
- AI slop risk
- Responsive intention
- Accessibility basics
Required: ASCII diagram of user flow.
STOP. One question per issue.
CRITICAL RULE — How to ask questions
- One issue = one question. Never batch.
- Describe problem concretely, with file and line references.
- 2-3 options, including "do nothing" where reasonable.
- Map reasoning to engineering preferences.
- Label: issue NUMBER + option LETTER (e.g., "3A", "3B").
- Escape hatch: section has no issues → say so and move on.
Required Outputs
"NOT in scope" section
List work explicitly deferred, with one-line rationale.
"What already exists" section
Existing code/flows that partially solve sub-problems and whether plan reuses them.
"Dream state delta" section
Where this plan leaves us relative to the 12-month ideal.
Error & Rescue Registry
Complete table from Section 2.
Failure Modes Registry
CODEPATH | FAILURE MODE | RESCUED? | TEST? | USER SEES? | LOGGED?
---------|-------------|----------|-------|------------|---------
RESCUED=N, TEST=N, USER SEES=Silent → CRITICAL GAP.
TODOS.md updates
Present each potential TODO as its own question. Never batch.
Format per TODO:
- What: one-line description
- Why: concrete problem solved or value unlocked
- Pros/Cons
- Context: enough for someone in 3 months to understand
- Effort: S/M/L/XL (human) → AI-assisted: S→S, M→S, L→M, XL→L
- Priority: P1/P2/P3
- Depends on/blocked by
Options: A) Add to TODOS.md B) Skip C) Build it now in this PR.
Scope Expansion Decisions (EXPANSION and SELECTIVE only)
Reference the CEO plan. List: Accepted / Deferred / Skipped.
Diagrams (mandatory)
- System architecture
- Data flow (including shadow paths)
- State machine
- Error flow
- Deployment sequence
- Rollback flowchart
Completion Summary
+====================================================================+
| MEGA PLAN REVIEW — COMPLETION SUMMARY |
+====================================================================+
| Mode selected | EXPANSION / SELECTIVE / HOLD / REDUCTION |
| System Audit | [key findings] |
| Step 0 | [mode + key decisions] |
| Section 1 (Arch) | ___ issues found |
| Section 2 (Errors) | ___ error paths mapped, ___ GAPS |
| Section 3 (Security)| ___ issues found, ___ High severity |
| 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: ___ |
| Section 11 (Design) | ___ issues / SKIPPED (no UI scope) |
+--------------------------------------------------------------------+
| NOT in scope | written (___ items) |
| What already exists | written |
| Dream state delta | written |
| Error/rescue registry| ___ methods, ___ CRITICAL GAPS |
| Failure modes | ___ total, ___ CRITICAL GAPS |
| TODOS.md updates | ___ items proposed |
| Scope proposals | ___ proposed, ___ accepted (EXP + SEL) |
| CEO plan | written / skipped (HOLD/REDUCTION) |
| Lake Score | X/Y recommendations chose complete option |
| Diagrams produced | ___ (list types) |
| Unresolved decisions | ___ (listed below) |
+====================================================================+
Unresolved Decisions
Note any unanswered questions here.
Next Steps — Review Chaining
After review, recommend:
- /plan-eng-review if eng review is not skipped — this is the required shipping gate
- /plan-design-review if UI scope was detected
Send via message tool:
- A) Run /plan-eng-review next (required gate)
- B) Run /plan-design-review next (only if UI scope)
- C) Skip — I'll handle reviews manually
docs/designs Promotion (EXPANSION and SELECTIVE only)
Send via message tool:
"The vision from this review produced {N} accepted scope expansions. Want to promote it to a design doc in the repo?"
- A) Promote to
docs/designs/{FEATURE}.md
- B) Keep locally only
- C) Skip
If promoted, copy content and update status from ACTIVE to PROMOTED.
Mode Quick Reference
┌─────────────┬──────────────┬──────────────┬──────────────┬────────────┐
│ │ EXPANSION │ SELECTIVE │ HOLD SCOPE │ REDUCTION │
├─────────────┼──────────────┼──────────────┼──────────────┼────────────┤
│ Scope │ Push UP │ Hold+offer │ Maintain │ Push DOWN │
│ │ (opt-in) │ cherry-pick │ │ │
│ 10x check │ Mandatory │ Surface as │ Optional │ Skip │
│ │ │ cherry-pick │ │ │
│ Platonic │ Yes │ No │ No │ No │
│ ideal │ │ │ │ │
│ CEO plan │ Written │ Written │ Skipped │ Skipped │
│ Design │ "Inevitable" │ If UI scope │ If UI scope │ Skip │
│ (Sec 11) │ │ │ │ │
└─────────────┴──────────────┴──────────────┴──────────────┴────────────┘
