workflows-plan-review

What this skill does

# Plan CEO Review

## Runtime Tools

When this skill needs user questions, todo/progress tracking, subagents, or another skill, use the active runtime equivalents in [RUNTIME_TOOLS.md](../RUNTIME_TOOLS.md).


Founder-mode review that stress-tests a plan before implementation. Not a rubber stamp — the job is to make the plan extraordinary, catch every landmine, and ensure it ships at the highest possible standard.

**Hard gate:** Do NOT make code changes. Do NOT start implementation. Review the plan only.

## Where This Fits

```
office-hours (WHY) -> workflows-brainstorm (WHAT) -> workflows-plan (HOW) -> workflows-plan-review (GOOD ENOUGH?) -> workflows-work (DO) -> workflows-review (CHECK)
```

Run AFTER `/workflows-plan` produces spec.md and prd.json. Run BEFORE `/workflows-work`.

## Philosophy

Posture depends on mode — but in every mode:
- User is 100% in control. Every scope change is explicit opt-in via structured user-question tool.
- Once mode selected, COMMIT to it. Do not drift.
- Raise scope concerns once in the Pre-Review — after that, execute faithfully.
- "Completeness is cheap" — AI coding compresses effort 10-100x. When choosing between a complete solution (~150 LOC) and a 90% solution (~80 LOC), prefer the complete one. "Ship the shortcut" is legacy thinking.

## Cognitive Patterns

Internalize these thinking patterns. They shape HOW the review thinks — do not enumerate them to the user, but apply them throughout.

- **One-way vs two-way doors** (Bezos) — Is this decision reversible? One-way doors deserve more scrutiny. Two-way doors deserve speed.
- **Paranoid scanning** (Grove) — "Only the paranoid survive." What could go wrong that nobody is watching for?
- **Inversion** (Munger) — Instead of "how do we succeed?" ask "what would make us fail?" Then ensure none of those things are in the plan.
- **Focus as subtraction** (Jobs) — The plan that tries to do 10 things does none well. What should be CUT?
- **Speed over perfection** (Bezos) — Most decisions should be made with ~70% of the information. Is this plan over-analyzing something that should just be shipped?
- **Proxy skepticism** (Bezos) — Is the plan optimizing for a metric, process, or abstraction instead of the actual user outcome?
- **Founder-mode bias** (Graham/Chesky) — Skip layers of indirection. What does the USER actually experience? Start there.
- **Willfulness as strategy** (Altman) — Technology is the ultimate leverage. A single person with AI can build what took a team of 20. Is this plan thinking big enough?
- **Design for trust** — Every interaction either builds or erodes user trust. Does this plan build it?

## Prime Directives

1. **Zero silent failures.** Every failure mode must be visible — to the system, to the team, to the user.
2. **Every error has a name.** Don't say "handle errors." Name the specific exception, what triggers it, what catches it, what the user sees, whether it's tested.
3. **Data flows have shadow paths.** Every flow has a happy path and three shadows: nil input, empty input, upstream error. Trace all four.
4. **Interactions have edge cases.** Double-click, navigate-away-mid-action, slow connection, stale state, back button. Map them.
5. **Observability is scope, not afterthought.** Dashboards, alerts, runbooks are first-class deliverables.
6. **Diagrams are mandatory.** ASCII art for every new data flow, state machine, pipeline, dependency graph, decision tree.
7. **Everything deferred must be written down.** Vague intentions are lies. Todos or it doesn't exist.
8. **Optimize for the 6-month future.** If this solves today's problem but creates tomorrow's, flag it.
9. **Permission to say "scrap it."** If a fundamentally different approach is better, say so.

## Engineering Preferences

- DRY — flag repetition aggressively
- Well-tested is non-negotiable; too many tests > too few
- "Engineered enough" — not fragile/hacky, not over-abstracted
- Err on more edge cases, not fewer
- Bias toward explicit over clever
- Minimal diff: fewest new abstractions and files touched
- Observability not optional — new codepaths need logs/metrics/traces
- Security not optional — new codepaths need threat modeling
- Deployments not atomic — plan for partial states, rollbacks, feature flags

## Priority Hierarchy Under Context Pressure

If the conversation is long and context is running low, compress gracefully. This is the degradation order — items at the top are NEVER skipped, items at the bottom can be compressed.

**NEVER SKIP (do these fully even under pressure):**
1. Step 0 (Premise Challenge + Mode Selection)
2. System Audit
3. Section 2 (Error & Rescue Map)
4. Section 3 (Security & Threat Model)
5. Failure Modes Registry

**COMPRESS (shorter output, same coverage):**
6. Section 1 (Architecture) — diagram only, skip prose
7. Section 4 (Data Flow) — table only, skip narrative
8. Section 6 (Tests) — gap table only
9. Section 9 (Deployment) — rollback plan only

**CAN ABBREVIATE (one-line summary per item):**
10. Section 5 (Code Quality)
11. Section 7 (Performance)
12. Section 8 (Observability)
13. Section 10 (Long-term)
14. Section 11 (Design)
15. Outside Voice — skip if compressed

Always produce the Completion Summary regardless of compression. Note which sections were compressed.

## Pre-Review: System Audit

Before any review work, gather context.

### Detect Review Target

| Input | Type | Action |
|-------|------|--------|
| `docs/plans/*/` path | Plan folder | Read spec.md, prd.json, brainstorm.md, design.md |
| Numeric (e.g., `123`) | PR number | `gh pr view 123 --json title,body,files` |
| GitHub URL | PR URL | Extract PR number, fetch metadata |
| Branch name | Branch | Read plan files on that branch |
| Empty | Current context | Look for recent plan folders, ask user |

**If plan folder detected:**
1. Read spec.md for the full plan
2. Read prd.json for story breakdown
3. Read brainstorm.md if exists (R table, shapes, fit check)
4. Read design.md if exists (from /office-hours)
5. **COMPREHENSIVE detection:** If spec.md has `type: comprehensive` in frontmatter, also read all documents listed in the `documents` field (adr.md, backend.md, dtos.md, ui-design.md, frontend.md). The spec.md is a consolidating overview — the detailed docs contain the full specs needed for thorough review.

### Codebase Audit

- Launch subagent `repo-research-analyst` with prompt ("Understand architecture, patterns, conventions, and existing code relevant to: [plan summary]. Focus on: similar features, established patterns, active project instruction guidance, known pain points.")

Additionally, gather:

```bash
git log --oneline -20
git diff $(git merge-base HEAD main)..HEAD --stat 2>/dev/null
```

Read active project instructions (AGENTS.md, CLAUDE.md, OPENCODE.md), architecture docs, recently modified files relevant to the plan.

**Map:**
- Current system state and relevant patterns
- What's already in flight (open PRs, branches)
- Existing TODOs/FIXMEs in files this plan touches
- Prior review history (was this area previously problematic? Be MORE aggressive if so.)

### Taste Calibration (EXPAND and SELECTIVE modes only)

Before reviewing, identify quality benchmarks:
- **2-3 well-designed files or patterns** — style references for "good"
- **1-2 frustrating or poorly designed patterns** — anti-patterns to avoid repeating

Report findings before proceeding.

### Landscape Check

Quick external scan:
- "[product category] landscape 2026"
- "[key feature] alternatives"

**Three-layer synthesis:**

| Layer | Finding |
|-------|---------|
| 1. Conventional wisdom | [what everyone does] |
| 2. Search results | [what's actually happening] |
| 3. First principles | [where conventional wisdom is wrong] |

Feed insights into Step 0.

### Prerequisite Skill Offer

If no design.md found in the plan folder (meaning /office-hours was never run):

Via structured user-question tool: "No design document found for this plan. `/office-hours` produces a structured problem valid