all-the-vibes/atv-phoenix/phoenix-self-heal

phoenix-self-heal — sense, snapshot, heal; the loop at the heart of Phoenix

Overview

This is the primitive every Phoenix lifecycle skill is built on, usable standalone: objectively sense whether work succeeded, keep a blessed snapshot to fall back to, and heal (bounded) when a check goes red — with recovery confirmed by an independent recheck, never by self-judgment. It gives an agent the one organ it's missing: knowing it failed, and fixing it, with evidence.

When to use

• Any code change with a runnable check (test/build/lint).
• Risky edits where you want a guaranteed rollback point.
• As the inner loop of phoenix-build, phoenix-test, and phoenix-debug.

The four tools

• phoenix_sense(check) — objective check. kind ∈ command_exit (run argv, pass iff exit==expect,

default 0), file_sha256, regex_in_file. Returns {ok, signal, evidence}. No LLM, no opinion. target accepts an argv array (preferred) or a string; expect accepts an int or string.

• phoenix_snapshot(path, check) — save path as last-good only if `check` passes (never blesses

a broken state). Returns {blessed, snap_id}.

• phoenix_heal(strategy, ctx) — rollback (restore a blessed snapshot) or retry (re-run a command

≤3×). healed=true only if ctx.recheck passes after the action. Bounded; reversible.

• phoenix_verify_trace() — audit the tamper-evident hash-chained log.

Example

{"check":{"kind":"command_exit","target":["pytest","-q"],"expect":0}}                       # sense
{"path":"src/app.py","check":{"kind":"command_exit","target":["pytest","-q"],"expect":0}}    # snapshot (blesses if green)
{"strategy":"rollback","ctx":{"path":"src/app.py","snap_id":"app.py.1a2b…",                    # heal
  "recheck":{"kind":"command_exit","target":["pytest","-q"],"expect":0}}}

The loop

  baseline ─► phoenix_sense ─► ok? ──no──► (not ready; create a check first)
                               │ yes
                               ▼
                       phoenix_snapshot (bless green state)
                               │
                               ▼
                          ── edit ──
                               │
                       phoenix_sense ─► ok? ──yes──► done (green, proven)
                               │ no
                               ▼
                       phoenix_heal (rollback/retry, ≤3) ─► re-sense ─► green? 
                               │ no after 3 → STOP, report what's blocking

Rules

• Snapshot only blesses green. You can never accidentally save a broken state as your fallback.
• Heal is confirmed externally. healed=true requires the independent recheck to pass after the

action — the heal never grades itself.

• Bounded. ≤3 attempts, then stop and report. Unbounded healing is token-burning, not progress.
• Reversible by default. Rollback restores a blessed snapshot atomically; nothing is destroyed

without a known-good point to return to.

Common Rationalizations

Red Flags

• Claiming success with no phoenix_sense. → Run the check.
• Editing without a snapshot on a risky change. → Snapshot the blessed state first.
• 4th heal attempt. → Stop; this is a planning problem (phoenix-plan) or a real bug (phoenix-debug).
• Trusting "healed" without the external recheck. → Confirm green via the recheck, not the diff.

Next

Standalone, this is enough to verify-and-fix one change. For full work, route through the lifecycle: phoenix-think → plan → build (↔ test/debug) → review → ship.