autoplan

What this skill does

# /autoplan — Auto-Review Pipeline

One command. Rough plan in, fully reviewed plan out.

/autoplan follows the deep (plan-deep-review), design, eng, and DX review skill methodologies at full depth — same rigor, same sections, same outputs as running each skill manually. The only difference: intermediate AskUserQuestion calls are auto-decided using the 6 principles below. Taste decisions (where reasonable people could disagree) and user challenges (where both reviewers think the user's stated direction should change) are surfaced at a single final approval gate.

This is a **non-interactive, fully automated** workflow with exactly two human-decision gates: premise confirmation in Phase 1, and the Final Approval Gate at the end.

---

## The 6 Decision Principles

These rules auto-answer every intermediate question:

1. **Choose completeness** — Ship the whole thing. Pick the approach that covers more edge cases.
2. **Boil lakes** — Fix everything in the blast radius (files modified by this plan + direct importers). Auto-approve expansions that are in blast radius AND < 1 day of CC effort (< 5 files, no new infra).
3. **Pragmatic** — If two options fix the same thing, pick the cleaner one. 5 seconds choosing, not 5 minutes.
4. **DRY** — Duplicates existing functionality? Reject. Reuse what exists.
5. **Explicit over clever** — 10-line obvious fix > 200-line abstraction. Pick what a new contributor reads in 30 seconds.
6. **Bias toward action** — Merge > review cycles > stale deliberation. Flag concerns but don't block.

**Conflict resolution (context-dependent tiebreakers):**
- **Deep phase:** P1 (completeness) + P2 (boil lakes) dominate.
- **Eng phase:** P5 (explicit) + P3 (pragmatic) dominate.
- **Design phase:** P5 (explicit) + P1 (completeness) dominate.
- **DX phase:** P5 (explicit) + P1 (completeness) dominate.

---

## Decision Classification

Every auto-decision is classified:

**Mechanical** — one clearly right answer. Auto-decide silently. Examples: run the adversarial subagent (always yes), reduce scope on a complete plan (always no).

**Taste** — reasonable people could disagree. Auto-decide with recommendation, but surface at the final gate. Three natural sources:
1. **Close approaches** — top two are both viable with different tradeoffs.
2. **Borderline scope** — in blast radius but 3-5 files, or ambiguous radius.
3. **Subagent disagreements** — independent subagent voice recommends differently and has a valid point.

**User Challenge** — both Claude and the independent subagent agree the user's stated direction should change. This is qualitatively different from taste decisions. When both voices recommend merging, splitting, adding, or removing features that the user specified, this is a User Challenge. It is NEVER auto-decided.

User Challenges go to the final approval gate with richer context than taste decisions:
- **What the user said:** (their original direction)
- **What both voices recommend:** (the change)
- **Why:** (the voices' reasoning)
- **What context we might be missing:** (explicit acknowledgment of blind spots)
- **If we're wrong, the cost is:** (what happens if the user's original direction was right)

The user's original direction is the default. The voices must make the case for change, not the other way around.

**Exception:** If both voices flag the change as a security vulnerability or feasibility blocker (not a preference), the AskUserQuestion framing explicitly warns: "Both voices believe this is a security/feasibility risk, not just a preference." The user still decides, but the framing is appropriately urgent.

---

## Sequential Execution — MANDATORY

Phases MUST execute in strict order: Deep → Design → Eng → DX. Each phase MUST complete fully before the next begins. NEVER run phases in parallel — each builds on the previous.

Between each phase, emit a phase-transition summary and verify that all required outputs from the prior phase are written before starting the next.

---

## What "Auto-Decide" Means

Auto-decide replaces the USER'S judgment with the 6 principles. It does NOT replace the ANALYSIS. Every section in the loaded skill files must still be executed at the same depth as the interactive version. The only thing that changes is who answers the AskUserQuestion: you do, using the 6 principles, instead of the user.

**Two exceptions — never auto-decided:**
1. Premises (Phase 1) — require human judgment about what problem to solve.
2. User Challenges — when both voices agree the user's stated direction should change (merge, split, add, remove features/workflows). The user always has context the voices lack.

**You MUST still:**
- READ the actual code, diffs, and files each section references
- PRODUCE every output the section requires (diagrams, tables, registries, scorecards)
- IDENTIFY every issue the section is designed to catch
- DECIDE each issue using the 6 principles (instead of asking the user)
- LOG each decision in the audit trail
- WRITE all required artifacts (in the plan file or conversation, per skill's spec)

**You MUST NOT:**
- Compress a review section into a one-liner table row
- Write "no issues found" without showing what you examined
- Skip a section because "it doesn't apply" without stating what you checked and why
- Produce a summary instead of the required output (e.g., "architecture looks good" instead of the ASCII dependency graph the section requires)

"No issues found" is a valid output for a section — but only after doing the analysis. State what you examined and why nothing was flagged (1-2 sentences minimum). "Skipped" is never valid for a non-skip-listed section.

---

## Phase 0: Intake + Restore Point

### Step 1: Capture restore point

Before doing anything, save the plan file's current state. If a plan file path is in conversation context, copy it to a sibling restore file:

```bash
PLAN_FILE="<path provided by user or detected>"
[ -f "$PLAN_FILE" ] || { echo "No plan file — skipping restore point."; }
if [ -f "$PLAN_FILE" ]; then
  RESTORE_PATH="${PLAN_FILE%.md}-autoplan-restore-$(date +%Y%m%d-%H%M%S).md"
  cp "$PLAN_FILE" "$RESTORE_PATH"
  echo "Restore point: $RESTORE_PATH"
fi
```

If a plan file exists, prepend a one-line HTML comment so the user can see and re-run:
`<!-- /autoplan restore point: [RESTORE_PATH] -->`

If no plan file exists, log: "Running /autoplan against branch diff (no plan file)."

### Step 2: Detect platform and base branch

Determine which branch this PR targets. Use the result as "the base branch" in every subsequent `git diff`, `git log`, and `git fetch` command.

1. `gh pr view --json baseRefName -q .baseRefName` — if succeeds, use it
2. `gh repo view --json defaultBranchRef -q .defaultBranchRef.name` — if succeeds, use it
3. Fall back to `main`.

Print the detected base branch name.

### Step 3: Read context

- Read CLAUDE.md / AGENTS.md if present, TODOS.md if present
- `git log --oneline -30`, `git diff <base> --stat`
- The plan file (if discovered above), or use the branch diff as the plan-equivalent
- **Detect UI scope:** grep the plan/diff for view/rendering terms (component, screen, form, button, modal, layout, dashboard, sidebar, nav, dialog). Require 2+ matches. Exclude false positives ("page" alone, "UI" in acronyms).
- **Detect DX scope:** grep the plan/diff for developer-facing terms (API, endpoint, REST, GraphQL, gRPC, webhook, CLI, command, flag, argument, terminal, shell, SDK, library, package, npm, pip, import, require, SKILL.md, MCP, agent, developer docs, getting started, onboarding, integration, error message). Require 2+ matches. Also trigger DX scope if the product IS a developer tool (something developers install, integrate, or build on top of).

Output: "Here's what I'm working with: [plan summary]. UI scope: [yes/no]. DX scope: [yes/no]. Starting full review pipeline with auto-decisions."

### Step 4: Locate the bork plan-* skill files

Each phase below follows a plan-* skill at full depth. Find the bork plugi