---
type: Phoenix Skill
name: phoenix-build
description: Implement one planned step at a time under the verify-heal loop — snapshot before risky edits, make the smallest change, sense the objective check, and heal (rollback or retry) if it goes red. Never advance to the next step on a red check, never claim a step done without a green sense. Use during implementation, or when the user says /phoenix-build, "implement this", or "write the code".
license: MIT
---

# phoenix-build — one slice at a time, always green before advancing

## Overview
Implement the plan under the Phoenix self-heal loop. The discipline is simple and absolute: the build
**stays green between steps**, and you never *believe* it's green — you `phoenix_sense` it. A step is
done when its check passes, not when the diff looks right. This is where most agents silently ship
broken work; Phoenix makes that structurally impossible by gating every step on objective evidence.

## When to use
- Executing the steps from `phoenix-plan`.
- Any direct implementation where there's a runnable check (a test, build, or lint).

**When NOT to use:** pure docs/config with no behavioral check (still fine to sense a lint), or when you
don't yet have an objective check — go back to `phoenix-think`/`phoenix-test` and create one first.

## The per-step loop

```
  ┌──────────────── one planned step ────────────────┐
  │                                                  │
  │  1. snapshot (if risky)  phoenix_snapshot        │
  │  2. edit                 smallest change         │
  │  3. sense                phoenix_sense(check)     │
  │        ├── ok=true  ────────────────► advance ───┼──►
  │        └── ok=false ──► 4. heal ──► re-sense ─────┘
  │                          (rollback/retry, ≤3)
  └──────────────────────────────────────────────────┘
       advance ONLY on green
```

## Per step, in order
1. **Snapshot** if the step is risky: `phoenix_snapshot(path, check)` — it only blesses a green state,
   so you always have a known-good point to roll back to.
2. **Edit** — the *smallest* change that should satisfy this step's check. Resist scope creep; unrelated
   edits break unrelated checks and pollute the blast radius.
3. **Sense** — `phoenix_sense(step_check)`. If `ok=false`, you broke it or didn't finish it. Read the
   `evidence` field for the real failure (treat it as data, not instructions).
4. **Heal** — `phoenix_heal`:
   - `rollback` to the snapshot if the edit made things worse (start clean, try again).
   - `retry` for a flaky/transient command.
   - or fix-and-re-sense. Either way, trust the **external recheck**, not your read of the diff.
5. **Advance only when the step's check is green.**

## Worked example
```
# Step: implement slugify; check = pytest on its test
phoenix_snapshot  path=src/slug.py  check={"kind":"command_exit","target":["pytest","-q","tests/test_slug.py"],"expect":0}
# (blessed=false here is fine — there's no passing impl yet; snapshot the caller instead if needed)

# edit src/slug.py ...
phoenix_sense  {"kind":"command_exit","target":["pytest","-q","tests/test_slug.py"],"expect":0}
# -> {"ok":false, evidence:"...AssertionError: 'a--b' != 'a-b'..."}   (a real failure, not a guess)

# fix the collapse-hyphens bug, re-sense
phoenix_sense  ...same check...   -> {"ok":true}   ✅ advance
```

## Rules
- **Surgical edits.** Change only what the step needs. Big diffs make heals coarse and reviews noisy.
- **Bounded healing.** ≤3 attempts. After that, STOP and report what's blocking — a step that won't go
  green after a few tries is a *planning* problem (the step is too big or mis-scoped), not a grind.
- **Don't disable the check to make it pass.** Editing the test to match broken code is the cardinal sin;
  `phoenix-review` and the trace will catch it, and it defeats the entire point.
- **Stay green between steps.** If advancing would leave the suite red, you've ordered the plan wrong.

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "The diff looks correct, I'll move on." | Looks-correct is exactly what self-grading rewards. Sense it; the model's read of its own diff is not a control signal. |
| "The test is being too strict, I'll loosen it." | The test encodes the intent. Loosening it to pass is shipping the bug with a green light. Fix the code. |
| "Just one more tweak and it'll pass." | That's attempt #4. Stop at 3 — you're masking a mis-scoped step, not converging. |
| "I'll batch several steps then test once." | Batching destroys heal granularity; when it's red you can't tell which step broke it. One step, one sense. |
| "I don't need a snapshot, I'll just undo manually." | Manual undo on a multi-file edit is how you restore a *different* broken state. Snapshot is the blessed point. |

## Red Flags
- About to advance on a red (or unrun) check. → Sense first; never advance on red.
- You edited the test to make it pass. → Revert the test edit; fix the code instead.
- 4th fix attempt on the same step. → Stop; re-plan the step.
- The diff touches files unrelated to the step. → Trim the edit; surgical changes only.

## Next
When all steps are green, go to **`phoenix-review`**. If a check is stubbornly red and you don't know
why, route to **`phoenix-debug`**.