# Self Healing

> Self-Healing Skill

- Skill: `raphael67/self-healing` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add raphael67/self-healing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/raphael67/self-healing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: raphael67 (https://skillmd.com/u/raphael67)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/raphael67/self-healing

---


# Self-Healing Skill

You are running the self-healing pipeline. Parse `$ARGUMENTS` for `days=N`
(default 7) and `phase=` (default `all`).

- `phase=learn` → run Phases 1–4 only.
- `phase=hygiene` → run Phase 5 only.
- `phase=consolidate` → run Phase 6 only.
- `phase=all` → run everything in order.

Follow the selected phases exactly.

## Phase 1: Extract Issues

Parse `$ARGUMENTS` for `days=N` (default 7).

```bash
python3 "$(dirname "$0")/tools/extract_issues.py" --days <N>
```

Wait for it to complete. Read `/tmp/self-healing-extracted.json` and report the metadata summary. If there are 0 extractions, stop here and tell the user.

## Phase 2: Classify Issues

Read the extractions from `/tmp/self-healing-extracted.json`.

Batch the extractions into groups of ~50. For each batch, spawn a **parallel Task subagent** (use `subagent_type: "task"`) with the classification prompt from `prompts/classify.md`.

Each subagent receives:
- The classification prompt
- Its batch of extractions as JSON

Collect all classification results. Filter to only `mistake` classifications. Group them by category.

Write the grouped results to `/tmp/self-healing-issues.md` in this format:

```markdown
# Self-Healing Issues Report
Generated: <timestamp>
Sessions scanned: N | Projects: N | Total mistakes: N

## FILE_PATH_ERROR (N issues)
- **Description**: <description>
  - Session: `<session_file>` line <line_number>
  - Timestamp: <timestamp>

## WRONG_TOOL (N issues)
...
```

Report the category counts to the user.

If there are 0 mistakes, stop here.

## Phase 3: Extract Solutions

### Delegate `COMMUNICATION_STYLE` first

If the `COMMUNICATION_STYLE` category has issues, **remove it from the set handled here**
and hand the whole group to the `claude-style` agent (`Agent` tool,
`subagent_type: "claude-style"`, delegation mode), passing for each finding its
description, `session_file`, and `line_number`.

That agent owns `~/.claude/rules/communication.md` and is its only writer. Do not write
style rules to `self-healing.md` and do not let a `COMMUNICATION_STYLE` finding reach the
solve subagents below — a style rule living in two stores is how contradictory duplicates
appear. Relay the agent's report to the user with the rest of the phase-3 results.

### Remaining categories

For each **other** mistake category that has issues, spawn a **parallel Task subagent** (use `subagent_type: "task"`) with the solution extraction prompt from `prompts/solve.md`.

Each subagent receives:
- The solution prompt
- All mistakes in its category
- For each mistake, read 50 lines of context from the session file around the `line_number` (use offset/limit) and include it

Collect all solution results. Separate into `learnings` (resolved) and `unresolved`.

### Write Solved Learnings to Memory

For each learning with confidence `high` or `medium`:

**Project-scoped** (`scope: "project"`):
- Write to `~/.claude/projects/<encoded-project-path>/memory/self-healing.md`
- The encoded project path uses dashes: `/Users/foo/bar` -> `-Users-foo-bar`
- Append the rule under a `## Self-Healing Rules` header
- Format: `- <rule> _(confidence: <level>, source: <source_description>)_`

**Global-scoped** (`scope: "global"`):
- Write to the current project's memory: `~/.claude/projects/<current-project>/memory/self-healing.md`
- Mark with `[GLOBAL]` prefix so it's recognized across projects
- Format: `- [GLOBAL] <rule> _(confidence: <level>, source: <source_description>)_`

Before writing, read any existing `self-healing.md` to avoid duplicating rules. If a rule already exists, skip it. If an existing rule contradicts a new one, replace the old rule.

## Phase 4: Unsolved Problems (Interactive)

If there are unresolved issues from Phase 3:

Present each to the user with:
- What happened (description + context summary)
- Which session/project it occurred in
- Why it wasn't resolved

For each, ask the user to choose:
1. **Add memory rule** - User provides a rule, you write it to memory
2. **Ignore** - Skip this issue
3. **Investigate** - Read more session context and analyze further

Apply the user's decisions.

## Phase 5: Memory Hygiene

Goal: find memories that are dead, duplicated, or contradictory — and fix them
**only after user approval**.

1. **Inventory**: list every store `~/.claude/projects/*/memory/` with content.
   For each store, read `MEMORY.md` and every memory file.
2. **Detect, with evidence** (fan out one subagent per large store if needed):
   - **Dead references**: every concrete path, binary, flag, script, or project
     directory a memory cites — verify it exists (`ls`, `command -v`, Glob).
     A memory whose load-bearing reference is gone is a deletion candidate;
     cite the verified-absent path as proof. Also flag stores whose own project
     directory no longer exists (slug will never load again).
   - **Duplicates**: two files covering the same fact (within or across stores),
     or a memory duplicating what the repo/CLAUDE.md/global rules already
     record → propose a merge (say which file survives) or a deletion.
   - **Contradictions**: memories contradicting each other or the current
     config (global CLAUDE.md, rules, hooks) → propose which side is right,
     with evidence.
   - **Index drift**: MEMORY.md lines pointing to missing files, files missing
     from MEMORY.md, or content blocks inlined in MEMORY.md (index must be
     one pointer line per memory).
3. **Report**: write an actionable table to
   `/tmp/self-healing-hygiene.md` — one row per finding:
   `store | file | finding | evidence | proposed action (DELETE/MERGE/REWRITE/REINDEX)`.
   Show the user the summary counts and the table location.
4. **MANDATORY REVIEW GATE**: present the proposed actions via AskUserQuestion
   (group them sensibly, one question per turn, max 4 options; iterate if more
   groups). **Apply ONLY the actions the user approves. A refusal or an
   unselected group leaves every concerned file byte-identical — no partial
   application, no "harmless" cleanups on the side.** Before any deletion,
   verify an archive copy exists (e.g. a git-tracked archive or an explicit
   `cp` to a user-designated location) — if none exists, create one and say where.
5. After applying approved actions, regenerate the touched `MEMORY.md` indexes
   and re-verify 1:1 index ↔ directory.

## Phase 6: Consolidation (promote recurring facts)

Goal: a fact learned in ≥2 projects belongs in the global config, not in N
local memories — **promotion only with user approval**.

1. Across all stores (including `self-healing.md` rule files), collect facts
   and compare: same convention, same gotcha, same preference appearing in
   memories of **at least 2 different projects**, or marked `[GLOBAL]` in a
   project self-healing.md.
2. For each recurring fact, decide the correct home:
   - Conditional on a language/tool/path → a **path-scoped global rule**
     `~/.claude/rules/<topic>.md` (source of truth:
     `~/Projects/dotfiles/dotfiles/dot-claude/rules/`, stowed) with a
     `paths:` frontmatter glob. Draft the exact rule content.
   - Truly universal (true in every project, every session) → a one-line
     addition to the global CLAUDE.md — **only if it stays within the ≤60
     content-line budget** (`grep -vcE '^\s*$|^#|^<!--' <file>`); if the
     budget would overflow, propose which existing line moves out instead.
   - Already covered by the global config → propose deleting the redundant
     local memories only.
3. **Report**: append proposals to `/tmp/self-healing-consolidation.md`:
   `fact | seen in (stores) | proposed home | draft content | local memories to delete`.
4. **MANDATORY REVIEW GATE**: same contract as Phase 5 — AskUserQuestion,
   apply only what is approved, refusal changes nothing. A promotion is
   applied atomically: write the rule/line AND delete the now-redundant local
   memories (with archive) AND update their MEMORY.md indexes; never leave
   both copies alive silently.
5. Verify each new rule triggers: its `paths:` glob must match at least one
   real file on disk (test with Glob) before the local memories are removed.

## Final Summary

Report per pipeline that ran:
- learn: sessions/projects scanned, issues classified, rules written (list), unresolved handled
- hygiene: findings by type, actions approved vs refused, actions applied
- consolidate: recurring facts found, promotions approved vs refused, rules created

Done.