self-healing Guide
Active runtime recovery for coding agents: when something breaks mid-task, diagnose the root cause, write a fix, VERIFY by re-running the broken thing, then file a `HEAL-` entry to `.learnings/HEALS.md` with proof and any generated artifacts. Use whenever a command/test/build/lint exits non-zero or breaks, the agent hits a `ModuleNotFoundError` / `command not found` / `EACCES` / `permission denied` / port conflict / dependency or lockfile mismatch / wrong runtime version / venv not activated / stale `node_modules` / dirty git state / missing `.env`, the agent needs a helper / glue script / bulk-rename / one-off tool that doesn't exist yet, an external API/tool/MCP returns an unexpected error or hits a rate limit, a snapshot test flakes or any test fails intermittently, or the agent catches itself about to retry the same broken approach. Search `HEALS.md` by `Pattern-Key` first — most heals are recurrences (increment `Recurrence-Count`; don't duplicate). Verify is mandatory and unforgeable: mark `pending-verify` honestly if sandboxed/offline, `abandoned` if the fix can't be made to work. Pairs with `self-improvement` (which promotes recurring heals at `Recurrence-Count >= 3` to durable memory like CLAUDE.md / AGENTS.md / new skills) but owns the verify-before-persist discipline that self-improvement doesn't. Trigger eagerly on any failure shape above — an agent that fixes things ad-hoc without filing a HEAL is leaving silent recurrences in the codebase, which is exactly the failure mode this skill exists to prevent.
When to use self-healing
Active runtime recovery for coding agents: when something breaks mid-task, diagnose the root cause, write a fix, VERIFY by re-running the broken thing, then file a `HEAL-` entry to `.learnings/HEALS.md` with proof and any generated artifacts. Use whenever a command/test/build/lint exits non-zero or breaks, the agent hits a `ModuleNotFoundError` / `command not found` / `EACCES` / `permission denied` / port conflict / dependency or lockfile mismatch / wrong runtime version / venv not activated / stale `node_modules` / dirty git state / missing `.env`, the agent needs a helper / glue script / bulk-rename / one-off tool that doesn't exist yet, an external API/tool/MCP returns an unexpected error or hits a rate limit, a snapshot test flakes or any test fails intermittently, or the agent catches itself about to retry the same broken approach. Search `HEALS.md` by `Pattern-Key` first — most heals are recurrences (increment `Recurrence-Count`; don't duplicate). Verify is mandatory and unforgeable: mark `pending-verify` honestly if sandboxed/offline, `abandoned` if the fix can't be made to work. Pairs with `self-improvement` (which promotes recurring heals at `Recurrence-Count >= 3` to durable memory like CLAUDE.md / AGENTS.md / new skills) but owns the verify-before-persist discipline that self-improvement doesn't. Trigger eagerly on any failure shape above — an agent that fixes things ad-hoc without filing a HEAL is leaving silent recurrences in the codebase, which is exactly the failure mode this skill exists to prevent.
How to use self-healing
self-healing is a Claude skill in the SKILL.md format. Add it to your Claude environment from the source repository below, then it activates as a user-invocable skill when your task matches its description.