ultra-plan

What this skill does

# Ultra Plan

ultrathink

Build a detailed, architecturally sound implementation plan for the provided issues, changes, updates, or features. This is a **rigid workflow** -- follow every phase in order. Do not skip phases or combine them. Each phase produces a distinct deliverable that gates the next.

> **See also:** `/create-plan` for requirements-driven planning. `/plan-improvements` for codebase analysis and improvement recommendations.

## Inputs

The user provides one or more of:
- A bug list, feature request list, or change set
- A GitHub issue or PR with identified problems
- A review document or audit with findings
- Verbal description of needed changes

If the input is ambiguous or incomplete, ask clarifying questions before starting Phase 0.

## Arguments

| Argument | Description |
|----------|-------------|
| (none) | Default mode: run the full rigid workflow (Phases 0-6) |
| `--refresh` | Drift detection mode: compare existing plan against current code state (see below) |

## Drift Detection Mode (`--refresh`)

When invoked with `--refresh`, ultra-plan skips the normal Phase 0-6 workflow and instead checks whether an existing plan still matches the codebase.

**Prerequisites:**
- IMPLEMENTATION_PLAN.md (or `--input <path>`) must exist
- If no plan file exists, report: "No implementation plan found. Run `/ultra-plan` to create one, or specify a path with `--refresh --input <path>`."

**Workflow:**

### Step 1: Read the Plan

Read the plan file. Extract all work items with their:
- Files Affected (expected file paths)
- Acceptance Criteria (expected behaviors)
- Status (PENDING, IN_PROGRESS, COMPLETE)

### Step 2: Check Each Item Against Code

For each work item (focus on COMPLETE items — they're most likely to drift):

1. **File existence:** Do the listed files still exist? Were any renamed or deleted?
2. **Acceptance criteria:** For COMPLETE items, do the acceptance criteria still hold? (Read the relevant code and check.)
3. **New code:** Has code been added in the affected areas that the plan doesn't account for?

For large plans (>8 items), use Explore sub-agents to parallelize the checks.

### Step 3: Produce Drift Report

| Work Item | Plan Status | Drift Status | Evidence | Recommended Action |
|-----------|-------------|--------------|----------|-------------------|
| [N.M] | COMPLETE | Accurate | [Files unchanged, criteria hold] | None |
| [N.M] | COMPLETE | Drifted | [File X was refactored; criterion Y no longer holds] | Update plan or re-verify |
| [N.M] | PENDING | Obsolete | [The problem was fixed by a different approach] | Remove from plan |
| [N.M] | — | New | [New file X.md was added, not in any plan item] | Add to plan or document as out-of-scope |

**Drift status values:**
- **Accurate**: Code matches what the plan describes
- **Drifted**: Code has diverged from the plan's expectations
- **Obsolete**: Plan item is no longer relevant (problem solved differently, feature removed, etc.)
- **New**: Code or files exist that the plan doesn't account for

### Step 4: Recommendations

Based on the drift report:
- If drift is minimal (≤2 items), suggest targeted plan updates
- If drift is significant (>30% of items), suggest re-running `/ultra-plan` from scratch
- For PENDING items that are now obsolete, suggest removing them

After the drift report, return to normal mode — do NOT proceed with Phase 0-6.

## Phase 0 -- Constitution Check

> **Note:** Phase 0-6 below is the default workflow. If invoked with `--refresh`, skip to the Drift Detection Mode section above.

Before investigating any items, establish the project's non-negotiable constraints. These constraints gate every subsequent phase -- no proposed solution may violate them.

**Skip conditions:** Skip Phase 0 entirely if (a) the user says "skip constitution", (b) the task is clearly L0-L1 scope per plan-gate classification, or (c) the input is a single well-scoped bug fix.

### 0a. Read Existing Constraints

Read CLAUDE.md (and any `constitution.md` if present) for documented project constraints. Look for:

| Category | What to find |
|----------|-------------|
| **Test policy** | Required coverage, test frameworks, "never skip tests" rules |
| **Deployment target** | Cloud provider, container runtime, edge constraints |
| **Stack lock-in** | Required languages, frameworks, versions, "do not add dependencies" rules |
| **Security non-negotiables** | Auth requirements, data handling rules, compliance standards |
| **Observability minimum** | Logging requirements, metric collection, alerting |
| **Definition of done baseline** | What "done" means for this project (PR required? Review required? CI must pass?) |
| **Data sovereignty** | Where data can be stored/processed, residency requirements |

### 0b. Fill Gaps (if needed)

If CLAUDE.md is comprehensive on most categories, note the constraints and proceed. If significant gaps exist (≥3 categories with no documented position), ask the user up to 7 targeted questions -- one per missing category. Frame each question with a sensible default:

> "I don't see a documented test policy. Default assumption: tests are encouraged but not gating. Is that correct, or do you have a stricter requirement?"

Record answers. These constraints apply to all subsequent phases.

### 0c. Output

Produce a **Constraints Summary** -- a compact table of all documented and answered constraints. This summary:
- Feeds into the Summary Report (Phase 5) as "Pre-Plan Gates"
- Is checked during Solution Design (Phase 4) -- every proposed change must comply
- Is included in the plan generation output for downstream consumption

## Phase 2 -- Investigation

For **each item** in the input list, investigate and document:

**Scale gate:** If the input contains **>5 items**, spawn Explore sub-agents for parallel investigation (see below). For **≤5 items**, investigate inline using the table below.

| Field | What to capture |
|-------|----------------|
| **Item** | The issue/feature as stated |
| **Root cause** | The structural reason this exists -- not the symptom. Ask "why" until you hit bedrock. |
| **Blast radius** | Every component, state, data flow, config, and contract this touches |
| **Current behavior** | What actually happens now (read the code, don't guess) |
| **Expected behavior** | What should happen after the fix/change |
| **Preserved assumptions** | Assumptions in existing code that the fix must not violate |
| **Risk** | What could go wrong if this is done poorly |

**Investigation rules:**
- Read the actual code. Trace the actual data flow. Grep for usages. Check callers and callees.
- Do not accept the first plausible explanation. Verify against reality.
- If an item seems simple, that's when you're most likely to miss something. Investigate anyway.
- Document what you found, including anything surprising.

Present Phase 2 findings as a structured table or list before proceeding.

### Sub-Agent Investigation (>5 items)

When the input list has more than 5 items, use the Agent tool with `subagent_type: "Explore"` to parallelize investigation. This preserves main context for the high-value Phases 3-6.

**Dispatch pattern:**
1. Group related items (items that likely share code paths) into clusters of 2-3
2. For each cluster, spawn an Explore sub-agent with this prompt template:

> Investigate these items in the codebase at [project root]. For each item, find and document:
> - **Root cause:** The structural reason this exists (trace the code, don't guess)
> - **Blast radius:** Every component, state, data flow, and contract this touches
> - **Current behavior:** What actually happens now (read the actual code)
> - **Expected behavior:** What should happen after the fix/change
> - **Preserved assumptions:** Assumptions the fix must not violate
> - **Risk:** What could go wrong if done poorly
>
> Items to investigate:
> [list items in this cluster]
>
> Return findings as a structured table with one row per item.

3. Launch sub-agents in pa