self-heal

name	self-heal
description	Ambient friction detection and surgical skill correction. Embeds into all skills. Triggers at task resolution when skill instructions caused friction.
allowed-tools	Read, Write, Edit, Task, TaskCreate, TaskUpdate

Self-Heal

Quiet companion skill. Watches for friction caused by skill instructions during live sessions. At task resolution, diagnoses root cause and proposes surgical fixes with user approval.

This skill does not run on demand. It is embedded into other skills as an observer. When it detects a fixable source of friction, it surfaces automatically.

---

Directives

"Updates to skills must be surgical -- one specific instruction, smallest possible change, nothing more."

— Added 2026-02-26, source: system directive

"Nothing is written to a skill file without explicit user approval and a visible before/after diff."

— Added 2026-02-26, source: system directive

"Self-heal never modifies directives. Directives are sacred. Only workflow instructions, context descriptions, and clarifying language are in scope."

— Added 2026-02-26, source: system directive

---

Model-Lane Preflight

CHECKPOINT — Model-Lane Preflight Gate (slim, advisory-only; fires at the TOP of this skill's workflow, before any generative step):

1. SKIP silently IF ANY of: /route dispatched this invocation after running its own lane preflight (a lane advisory OR ask already printed, route otherwise ASSESSED the lane this turn, or it was deliberately suppressed — route's coverage extends to the whole endeavor whether route asked, matched, or the user declined, including skills this one chains); this skill's frontmatter sets model-lane-gate: off; the session is headless / non-interactive; this gate is executing inside a subagent (a subagent is already model-pinned via its own frontmatter); OR an advisory for this LANE already printed this endeavor AND the active model is unchanged (advise at most once per (lane, active-model) pair per endeavor).
2. Resolve this skill's lane (own lane: frontmatter → the Skill→Lane table in .claude/skills/skill-builder/references/model-lanes.md → NO LANE) and the lane's Preferred Model. IF no lane resolves OR the preferred-model cell is empty → silent no-op (correctly absent, not a gap). IF this skill declares per-function lanes AND the invocation's resolved mode has its own row → that function's lane governs; otherwise the skill-level lane covers all modes.
3. Read ACTIVE_MODEL from the session system-context line "The exact model ID is …" (strip [1m]/[200k], lowercase — model-lanes.md § Active-Model Detection; never an env var or Bash probe). IF the Preferred Model is malformed or names a clearly superseded family → emit the one-line stale-mapping advisory and proceed; never advise from a stale mapping, never validate against a hardcoded list.
4. Compare. Match → silent no-op. Mismatch → print ONE advisory line and PROCEED: "Lane advisory: this skill declares the <lane> lane (preferred <preferred>); the active model is <active> — to align, run /model <preferred> and re-invoke; proceeding as-is." Naming the command is INFORMATIONAL (named-command advisory directive, 2026-06-11): NEVER an AskUserQuestion, never a blocking wait (No-Switch-Prompt directive, 2026-06-06). A skill can NEVER switch the session model and never asks the user to.
5. Primary-lane scope. This gate fires ONCE per invocation, for the resolved PRIMARY lane. Cross-lane mid-workflow steps never re-advise — they delegate via this skill's LANE-AGENT-EMBED Delegation Map when present (see .claude/skills/skill-builder/references/lane-delegation.md). Delegation is never a substitute for THIS gate: analytical primary work runs on the analytical main model — never a creative main session orchestrating analytical-pinned agents to dodge the lane.

Review Command

When invoked as /self-heal review:

1. List all skills that have the self-heal observer embedded
2. Show count of friction events logged per skill (read each skill's self-heal-history.md if it exists)
3. Show count of patches applied vs. declined per skill
4. Flag skills missing the observer — offer to embed

---

Grounding

Before executing any diagnosis or update:

1. Read the relevant file from references/
2. State: "I will use [PROTOCOL] from references/[file] under [SECTION]"

Reference files:

• references/friction-signals.md — Complete friction signal taxonomy
• references/diagnosis-protocol.md — Root cause tracing procedure
• references/update-protocol.md — Diff construction and approval workflow

---

Observer Block — Canonical Source

The Self-Heal Observer block that embeds into other skills is defined in observer-block.md. Embedding skills must keep their inlined copy verbatim-identical to this canonical source. The audit's hooks sub-procedure can diff against this file to detect drift.

When creating a new skill, append the canonical observer block by reading observer-block.md and copying its content to the end of the new SKILL.md.