---
type: Phoenix Skill
name: phoenix-plan
description: Decompose a clear intent into small, individually-verifiable steps before writing code — each step a slice you can prove pass/fail with phoenix_sense, ordered so the build stays green between them. Use after phoenix-think, when you have an Intent Contract and need an executable plan, or when the user says /phoenix-plan, "break this down", or "make a plan".
license: MIT
---

# phoenix-plan — small atomic steps, each with an objective finish line

## Overview
A plan is only useful if you can *prove* each step is done. Phoenix plans in **slices the self-heal
loop can verify one at a time** — every step carries its own `phoenix_sense` check, the steps compose
up to the Intent Contract's acceptance gate, and the build stays green between them so any step is
independently revertible. A plan whose steps you can't check is a wish list.

## When to use
- After `phoenix-think` produced an Intent Contract with an acceptance check.
- Any multi-step change, refactor, or feature where order and blast radius matter.
- When a task "feels big" — planning is how you find the seams.

**When NOT to use:** a one-line change with an obvious check — just `phoenix-build` it directly.

## The planning flow

```
Intent Contract (acceptance check)
        │
        ▼
  Decompose into ordered slices
        │
        ▼  for each slice:
  ┌─────────────────────────────┐
  │ goal (one line)             │
  │ check (a phoenix_sense)     │  ← must be runnable & able to fail
  │ risky? → snapshot first     │
  └─────────────────────────────┘
        │
        ▼
  Slices compose up to the acceptance check
```

## Produce a step list like this
```
STEP 1  Add the failing test for the new behavior
        check: {"kind":"command_exit","target":["pytest","-q","tests/test_x.py::test_new"],"expect":0}
        (expected RED until step 2 — that's correct)
STEP 2  Implement the minimal code to pass step 1   risky? no
        check: same as step 1, now expected GREEN
STEP 3  Wire it into the caller                       risky? YES → snapshot caller.py first
        check: {"kind":"command_exit","target":["pytest","-q"],"expect":0}  (full suite green)
ACCEPTANCE  = step 3's full-suite check (from the Intent Contract)
```

## Rules
- **One check per step.** If you can't attach a single objective check to a step, it's too big — split it.
- **Green between steps.** Order so the suite is green after each step; that makes every step revertible
  and turns "it broke" into "roll back the last step", not "debug the whole change".
- **Name the risky steps.** Steps likely to break a passing check get a `phoenix_snapshot` before editing
  so `phoenix_heal` can roll back instantly.
- **Use the graph to scope.** Before planning a change to `X`, ask `phoenix-context` "what breaks if I
  change X?" — plan the real blast radius, not a guessed one. (Cheaper and more accurate than grepping.)
- **The last step's check = the acceptance gate.** The plan is wrong if the steps don't compose up to it.

## Sizing heuristic
A good step is one you could implement and verify in a single focused pass. If a step needs "and then
also…", that's two steps. Smaller steps = tighter heal granularity = less wasted work on a failure.

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "I'll plan it in my head and just build." | Unwritten plans have no verifiable steps; the first surprise becomes a debugging spiral. Write the checks down. |
| "This step is too small to need its own check." | A step without a check can't be healed in isolation — when it breaks you bisect the whole change. |
| "I'll figure out the blast radius as I go." | "As you go" means re-reading files every turn. Ask the graph once, plan the real scope. |
| "I'll snapshot later if I need to." | You need the snapshot *after* you've already overwritten the good state. Snapshot before the risky edit. |

## Red Flags
- A step has no runnable check. → Split or rewrite it until it does.
- The suite would be red between two steps. → Reorder so green is the resting state.
- You're guessing what a change affects. → `phoenix-context` the blast radius first.
- The plan has one giant "implement the feature" step. → That's not a plan; decompose it.

## Next
Hand each step to **`phoenix-build`** (snapshot→edit→sense→heal). For "prove this behavior" steps, route
to **`phoenix-test`**.