all-the-vibes/atv-phoenix/phoenix-plan

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

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`.