---
description: Diagnose and fix a skill that didn't work correctly in the current session
argument-hint: [optional: path to skill file]
---

# /heal-skill — Skill Self-Repair

Analyze the current conversation to find where a skill misbehaved, diagnose the root cause, and propose targeted fixes.

## When to Use

After running a skill that:
- Skipped steps it should have followed
- Followed the description instead of the body (CSO trap)
- Stopped too early or went too far
- Produced wrong output format
- Missed context it should have loaded
- Behaved differently than intended

## Process

### 1. Identify the skill

If `$ARGUMENTS` is provided, read that file. Otherwise, analyze the conversation to detect which skill was running. Look for:
- `/command-name` invocations
- Skill descriptions that appeared in system context
- Workflow patterns that match known skills

Ask the user to confirm: **"It looks like [skill-name] didn't work as expected. Is that right?"**

### 2. Gather evidence

From the conversation, extract:

**What was expected** — what the skill file says should happen (read the actual skill file)

**What actually happened** — trace Claude's actual behavior step by step:
- Which steps were followed?
- Which steps were skipped or altered?
- Where did behavior diverge from the skill's instructions?

**The gap** — specific delta between expected and actual behavior

Present this as a before/after comparison:
```
Expected (from skill):     Actually happened:
1. Ask for intent          1. Asked for intent ✓
2. Configure frontmatter   2. Skipped — jumped to writing ✗
3. Write body              3. Wrote body (partial) ~
4. Quality checklist       4. Skipped entirely ✗
5. Create files            5. Created files ✓
```

### 3. Diagnose root cause

Common failure modes to check:

| Symptom | Likely Cause |
|---------|-------------|
| Steps skipped | Description summarizes workflow (CSO trap) — Claude shortcuts |
| Wrong workflow chosen | Description too vague, triggers on wrong queries |
| Stopped too early | No success criteria defined |
| Output format wrong | No template or example provided |
| Context not loaded | File references too deep or ambiguous |
| Inconsistent behavior | Conflicting instructions between sections |
| Over-executed | No clear stopping point or "wait for user" gate |

Ask: **"Does this diagnosis match what you saw?"**

### 4. Propose fixes

For each root cause, show the specific edit:

```
## Fix 1: CSO Trap in description

File: ~/.claude/skills/my-skill/SKILL.md, line 3

Before:
  description: Dispatches subagent per task with code review between tasks

After:
  description: Use when executing implementation plans with independent tasks

Why: The old description leaked workflow details, causing Claude to
follow the description as a shortcut instead of reading the full skill.
```

Show all proposed fixes as diffs. Include the "why" for each — the user needs to understand the fix, not just apply it.

### 5. Apply with approval

Ask: **Which fixes should I apply?**
- **All fixes** — apply everything
- **Pick and choose** — list fixes by number, let user select
- **None** — just keep the diagnosis, fix manually

After applying fixes, suggest: **"Want to test the skill again to verify the fix?"**

## Principles

- **Evidence first** — always trace actual behavior from the conversation before diagnosing
- **One root cause at a time** — don't propose 10 fixes at once. Find the primary failure, fix it, re-test
- **The skill is the bug** — if Claude didn't follow the skill, the skill's instructions weren't clear enough. Don't blame the model, fix the instructions
- **Show your work** — every fix needs a "why" that the user can evaluate

<!-- Origin: Heal loop concept (self-repair after failed execution) adapted from https://github.com/glittercowboy/taches-cc-resources -->
<!-- Diagnosis patterns from writing-skills CSO trap research and debug-issue skill -->