---
description: Recursive self-healing framework for skill improvement. Scores executions, detects failures, proposes auto-repairs, tracks maturity progression. Triggered by 'why did [skill] fail', 'improve [skill]', '/self-heal [skill]', or auto when a skill's invocation produces an explicit Josh-correction.
---

# personal-self-healing

Skills get sharper over time when failures are captured and learned from. This skill closes that loop.

## Trigger phrases

- "Why did [skill] fail?"
- "Improve [skill]"
- "[Skill] gave a bad output"
- `/self-heal [skill-name]`
- Auto-triggered when Josh issues a correction (e.g., "no, that's wrong because X") on a skill's output

## Process

### Mode 1 — Single-failure analysis

When triggered with a specific failed skill invocation:

**Step 1 — Capture the failure.**

- Which skill ran?
- What was the input?
- What was the output?
- What did Josh say was wrong?

**Step 2 — Diagnose the root cause.**

Categories:

- **Description didn't fire** — wrong skill loaded, or no skill loaded
- **Description fired wrong** — right skill loaded but for the wrong sub-task
- **Skill logic missed a case** — edge case not handled
- **Skill output format wrong** — content correct but shape wrong
- **Skill voice wrong** — content correct but tone off
- **Skill consumed wrong input** — read the wrong file or used outdated context
- **Underlying model wrong** — should have been Tier 3/4 not Tier 2 (or vice versa)
- **Sub-agent contract violated** — sub-agent returned wrong shape

**Step 3 — Propose fix.**

Specific, narrow change to the skill's SKILL.md:

- Description tweak
- New section addressing the missed case
- Output format spec change
- Tier escalation rule
- New input source

**Step 4 — Surface to Josh.**

```markdown
# Self-heal: [skill name]

**Trigger:** [Josh's correction or '/self-heal' invocation]

## What went wrong

[1 paragraph]

## Root cause category

[from the list above]

## Proposed fix

[diff or narrative description of what would change in SKILL.md]

## Expected impact

[Will this affect other invocations? Edge cases?]

## Recommendation

- [ ] Apply the fix
- [ ] Discuss further
- [ ] Don't fix (false positive)
```

### Mode 2 — Periodic maturity review

When triggered with `/self-heal` (no skill specified), reviews the corrections log:

`~/.personal/skill-corrections.jsonl` — append-only log of every correction Josh has issued.

Schema:

```json
{
  "timestamp": "...",
  "skill": "...",
  "correction_text": "...",
  "diagnosed_category": "...",
  "fix_applied": true,
  "fix_path": "[skill]/SKILL.md@version-N"
}
```

The maturity review:

- Counts corrections per skill
- Identifies skills with recurring same-category corrections (signal of a fundamental gap)
- Identifies skills with zero corrections in 90 days (mature)
- Proposes maturity progression: draft → tested → mature → crystallized

### Skill maturity stages

| Stage | Definition | Behavior |
|---|---|---|
| draft | Just shipped, untested in real use | Expect corrections, log eagerly |
| tested | 5+ uses, <2 corrections | Stable but evolving |
| mature | 20+ uses, <5 corrections in last 90d | Edits require justification |
| crystallized | 50+ uses, <2 corrections in last 180d | Core utility, edit cautiously |

## Discipline

- **Corrections log is sacred.** Every Josh-correction should land in the JSONL. This is the data the skill library learns from.
- **Don't auto-fix without surfacing.** The AI proposes; Josh approves. Self-healing without consent is just drift.
- **Track what was fixed and whether it stuck.** If the same correction appears 3 times after a "fix", the fix didn't work — surface that.

## Privacy

The corrections log may contain Josh's verbatim language about why something was wrong. NEVER include this log in any sub-agent prompt sent to a cloud model — it's internal feedback.