auto-healer

name

auto-healer

description

Use the moment you fix a bug, see a failure recur, or are about to re-fix code you've touched before. `heal.py fix` logs the bug + scored attempt in ONE call (the low-friction primary path); `heal.py match` recalls prior FALSIFIED hypotheses for a file/error before you re-fix, so you don't re-derive dead ends. A per-repo bug+attempt ledger keyed by cwd makes a root defect resurfacing 'in a different shape' visible across sessions. Pull the web via /heal — never pushed. Pairs with stuck-detection (the in-session ladder); this is the cross-session memory.

Auto-Healer

Siloed bandaids recur because each fix is blind to the last. This is the cross-session ledger that makes the web visible. Five concepts, each named once: a bug is a root defect; an attempt is one tried fix, scored worked/failed/partial; a tag is a facet:value label; a link is a relation between two bugs; review is the pull that surfaces the web.

Capture: one call (the primary path)

The moment you fix — or fail to fix — something, log it in ONE call:

python3 skills/auto-healer/heal.py fix --summary "..." \
  --tags area:hook,class:race --hypothesis "..." --fix "..." --outcome worked

--outcome is REQUIRED (worked|failed|partial). Log failed/partial too — those are exactly what surface STUCK and ESCALATE; a ledger of only-worked fixes hides its own payoff. Omitting --bug mints a new bug, but if it looks like a recurrence of a LIVE bug, fix REFUSES to mint a duplicate and tells you to re-run --bug <id> --recurred (recurrence is a counter bump on the existing bug — the count is the signal — never a fresh bug). --force-new overrides when it is genuinely distinct.

Finer control is still there: bug add → attempt add <id> → attempt outcome <aid>; bug status <id> recurred|healed|wontfix; bug tag; bug link <id> <other>.

Recall: look before you re-fix

Before drafting a fix for anything you recognize — or any file/area you've touched before — pull what's already known so you don't re-walk falsified hypotheses:

python3 skills/auto-healer/heal.py match --file path/to/x.py --error "..."

match is read-only; it prints the matching bugs with every FAILED hypothesis (the negative space) and any worked fix. This is the recall half of stuck-detection's "search the record before re-fixing" — same pull, the cross-session source. Logging is discipline; so is looking up.

Tagging discipline

Tags are facet:value. REUSE facet names — area:, class:, symptom:, file:, root: — so clusters coalesce. Drifting facet names splits the web (harness-authoring "one name per concept"). The relational value lives in shared facets + links, not free-text summaries.

The /heal review (pull only)

heal.py review (current repo) or --all-repos surfaces, ESCALATE-first: ESCALATE TO SOURCE (recurring + a failed fix), STUCK (>=2 failed, still live — bandaid risk), RECURRING, TAG CLUSTERS (>=2 live bugs share a facet), LINKED CLUSTERS. --json emits the same predicates for machine consumers (one definition, no drift); --escalate-only is the /retro feed. A NO EVAL GUARD mark means a recurring/escalate bug has no regression eval yet — fix it once, guard it forever (below).

Closing the loop: escalate → /retro → immunity

ESCALATE is the autophagic handoff. Route it via /retro — mechanical cause → propose a hook; knowledge gap → skill/reference; design flaw → ADR (grep memory/decisions/ first; a prior ADR may already have rejected this fix class — see stuck-detection). Once routed, run heal.py escalate route <bug-id> --session <id> so it stops re-escalating on every /heal. It stays healing-aware: a routed bug RE-escalates if a new failed attempt lands after the route, and only fully drops when healed/wontfix — routing once can never make an unhealed root go dark.

When you bug status <id> healed (or fix --outcome worked), heal prints a ready-to-paste /capture-eval scaffold (it never writes evals/ itself — that is write-locked). Land the eval via /capture-eval so the defect can't silently regress: a bug that recurs AFTER being healed is the strongest signal an eval is missing.

Boundary vs stuck-detection

stuck-detection is the IN-session ladder (stop / switch strategy / escalate on a repeated failure). auto-healer is the CROSS-session record: when stuck-detection fires, log the bug here (fix ... --outcome failed) so the next session inherits the falsified hypotheses instead of re-deriving them.

Storage & rollup

state/heal/<repo-key>/{bugs,attempts}.jsonl under the harness root — machine-local, gitignored, keyed per working repo. heal.py rollup --label <repo-basename> [--trim-days 90] versions a STATS-ONLY digest into memory/heal/<label>/<YYYY-MM>.json (mirrors memory/calibration/; lessons still route via /retro, never raw prose) and decays resolved healed records older than N days — never wontfix, which is the falsified-hypothesis memory this skill exists to keep. /gc and /meta-retro run the rollup; cartograph --audit reads the same stats as an advisory harness vital sign.