--- name: plan-ceo-review source: https://app.decimal.ai/s/plan-ceo-review@1/SKILL.md source_sha256: 1725dfd4075b --- ## 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:** 1. **Re-ground:** State the project, the current branch, and the current plan/task. (1-2 sentences) 2. **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. 3. **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. 4. **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 1. Check if a PR exists: `gh pr view --json baseRefName -q .baseRefName` 2. If no PR: `gh repo view --json defaultBranchRef -q .defaultBranchRef.name` 3. 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 1. Zero silent failures. Every failure mode must be visible. 2. Every error has a name — specific exception class, what triggers it, what catches it. 3. Data flows have shadow paths: nil input, empty input, upstream error. Trace all four. 4. Interactions have edge cases: double-click, navigate-away, slow connection, stale state. 5. Observability is scope, not afterthought. 6. Diagrams are mandatory — ASCII art for every non-trivial flow. 7. Everything deferred must be written down. TODOS.md or it doesn't exist. 8. Optimize for 6-month future, not just today. 9. "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 1. **Classification instinct** — reversibility x magnitude (Bezos one-way/two-way doors). 2. **Paranoid scanning** — strategic inflection points, cultural drift (Grove). 3. **Inversion reflex** — "what would make us fail?" (Munger). 4. **Focus as subtraction** — what to *not* do. Default: fewer things, better. 5. **People-first sequencing** — people, products, profits (Horowitz). 6. **Speed calibration** — 70% info is enough to decide (Bezos). 7. **Proxy skepticism** — are metrics serving users or self-referential? 8. **Narrative coherence** — make the "why" legible. 9. **Temporal depth** — 5-10 year arcs, regret minimization (Bezos). 10. **Founder-mode bias** — deep involvement expands thinking (Chesky/Graham). 11. **Wartime awareness** — peacetime habits kill wartime companies (Horowitz). 12. **Courage accumulation** — confidence comes from decisions, not before. 13. **Willfulness as strategy** — push hard enough in one direction (Altman). 14. **Leverage obsession** — small effort, massive output (Altman). 15. **Hierarchy as service** — what should user see first, second, third? 16. **Edge case paranoia** — 47-char name? Zero results? Network fails? Empty states are features. 17. **Subtraction default** — "as little design as possible" (Rams). 18. **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 --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 1. Is this the right problem? Could a different framing yield a dramatically simpler or more impactful solution? 2. What is the actual user/business outcome? 3. What would happen if we did nothing? ### 0B. Existing Code Leverage 1. What existing code partially or fully solves each sub-problem? 2. 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:** 1. 10x check — version 10x more ambitious for 2x effort? 2. Platonic ideal — best engineer + unlimited time + perfect taste. 3. Delight opportunities — 5+ adjacent 30-minute improvements. 4. **Opt-in ceremony:** present each proposal as a question. Options: A) Add to scope B) Defer to TODOS.md C) Skip. **SELECTIVE EXPANSION:** 1. Complexity check — >8 files or 2+ new classes = smell. 2. Minimum set of changes for the stated goal. 3. Expansion scan (not in scope yet — candidates only). 4. **Cherry-pick ceremony:** each opportunity as a question. Neutral posture. **HOLD SCOPE:** 1. Complexity check. 2. Minimum set of changes. **SCOPE REDUCTION:** 1. Absolute minimum that ships value. 2. What can be a follow-up PR? ### 0D-POST. Persist CEO Plan (EXPANSION and SELECTIVE EXPANSION only) Get info: ```bash 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`: ```markdown --- 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: 1. **Completeness** — all requirements addressed? 2. **Consistency** — parts agree with each other? 3. **Clarity** — could an engineer implement without questions? 4. **Scope** — YAGNI violations? 5. **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: 1. **SCOPE EXPANSION** — dream big, every expansion is an opt-in 2. **SELECTIVE EXPANSION** — hold baseline + cherry-pick expansions 3. **HOLD SCOPE** — maximum rigor, no expansions 4. **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) 1. System architecture 2. Data flow (including shadow paths) 3. State machine 4. Error flow 5. Deployment sequence 6. 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) │ │ │ │ │ └─────────────┴──────────────┴──────────────┴──────────────┴────────────┘ ```