What Have We Learned

Full-depth analysis with persistent storage. Skill name is optional — if omitted, auto-detects from conversation. Three sub-modes:

1. Default (/what-have-we-learned [skill-name]): extract, save, and suggest
2. Apply (/what-have-we-learned [skill-name] --apply): extract, save, suggest, and apply approved changes
3. Review (/what-have-we-learned [skill-name] --review): show accumulated learnings

Auto Mode: Inline Post-Skill Analysis

This is the primary mode. It runs automatically after every skill usage.

When to trigger

After a skill completes (the Skill tool returns output), analyze the interaction inline — as part of your current response, not as a separate invocation.

What to look for

Scan the conversation for these signals, in order of importance:

1. User corrections — the user said "no", "not like that", "actually...", or had to rephrase
2. Unexpected failures — the skill errored, produced wrong output, or missed a step
3. Manual additions — the user had to add something the skill should have included
4. Smooth wins — something worked particularly well that the skill doesn't explicitly instruct

Decision: report or stay silent

Stay silent if:

• The skill worked as expected with no corrections
• Any issues were specific to this one case and not generalizable
• The findings are trivial (typos, minor formatting)

Report if:

• The user had to correct or supplement the skill's behavior
• A clear gap in the SKILL.md instructions was exposed
• A pattern emerged that would help in future uses
• Something worked exceptionally well and should be protected

Auto Mode output format

When there ARE findings worth reporting, append this block at the end of your response:

---
**Skill Learning Detected** (`<skill-name>`)

<N> finding(s) from this session:

1. **<type>**: <one-line description>
   Fix: <specific SKILL.md change, 1-2 lines>

2. **<type>**: <one-line description>
   Fix: <specific SKILL.md change, 1-2 lines>

Save and apply? [y/n/skip]

Where <type> is one of: Edge Case | Missing Step | Wrong Default | Good Pattern | Friction | Environment

User responses to auto mode

• "y" or "yes": Save the learnings to <skill-dir>/learnings/ AND apply the suggested SKILL.md changes. Commit with message learning(<skill-name>): <brief description>.
• "n" or "no": Discard — don't save, don't apply. Move on.
• "skip": Save the learnings to <skill-dir>/learnings/ but do NOT apply changes to SKILL.md yet. They'll be available for /what-have-we-learned <skill-name> --review later.
• "save only": Same as "skip" — save but don't apply.

CRITICAL: Never auto-apply

NEVER modify a skill's SKILL.md without explicit user approval. The auto mode ONLY observes and suggests. The user decides what gets applied. This is non-negotiable.

Manual Mode: Full Analysis

When the user explicitly invokes /what-have-we-learned, run the full analysis pipeline.

Phase 0: Resolve Target Skill

Determine which skill to analyze based on what the user provided:

If <skill-name> is given explicitly: Use it directly. Proceed to Phase 1.

If NO skill name is given (/what-have-we-learned with no arguments, or with only flags like --apply or --review):

1. Scan the conversation for Skill tool invocations. Look for any skill that was called via the Skill tool during this session.
2. If exactly one skill was used: use it as the target. Inform the user: Detected skill: <skill-name>.
3. If multiple skills were used: list them and ask the user which one to analyze:

   Multiple skills used in this session:
   1. approach
   2. ship
   3. pr
   
   Which skill would you like to analyze? (number or name, or "all" for all of them)
   

   If the user responds with "all", run the full analysis pipeline sequentially for each skill.
4. If no skills were used in this conversation: inform the user and ask:

   No skills were used in this conversation. Which skill would you like to analyze?
   You can also use --review to check accumulated learnings for any skill.
   

Phase 1: Locate the Skill

1. Find the target skill directory:

   • ~/.claude/skills/<skill-name>/SKILL.md
   • If symlink, resolve to source directory (e.g., ~/Development/Claude/<skill-name>/)
   • If not found, search ~/Development/Claude/ for the skill

2. Read the full SKILL.md to understand what the skill is supposed to do.

3. Check if a learnings/ directory exists. If not, create it.

Phase 2: Analyze the Conversation

Review the current conversation history looking for signals about the skill's performance. Categorize findings into these types:

Learning Categories

1. EDGE_CASE — A scenario the skill didn't handle well

• The user had to correct the skill's output
• The skill produced incorrect or incomplete results for a valid input
• A use case fell outside what the instructions anticipated

2. MISSING_INSTRUCTION — Something the skill should do but doesn't mention

• The user had to manually add something the skill should have included
• A step was needed that wasn't in the skill's workflow
• A tool or resource was needed that isn't listed

3. WRONG_ASSUMPTION — The skill's instructions assume something incorrect

• A default value or behavior doesn't match real-world usage
• An instruction leads to the wrong approach in practice
• A dependency or API works differently than the skill expects

4. EFFECTIVE_PATTERN — Something that worked particularly well

• An approach the skill took that the user confirmed or praised
• A pattern that produced high-quality output
• A workflow step that prevented errors

5. FRICTION_POINT — Something that slowed down or confused the workflow

• The user had to repeat themselves or clarify
• The skill asked unnecessary questions
• Output format didn't match what the user actually needed

6. ENVIRONMENT_INSIGHT — Something about the runtime environment that matters

• Tool availability or version constraints
• Platform-specific behavior (macOS, Linux, etc.)
• Dependency or configuration requirements

Extraction Rules

• Only extract learnings that are generalizable — they should help in future uses, not just this specific instance
• Each learning must be specific and actionable — "the skill should be better" is NOT a learning
• Include the evidence — what exactly happened in the conversation that demonstrates this
• Rate the confidence: HIGH (clear user feedback), MEDIUM (inferred from behavior), LOW (speculation)
• Rate the impact: HIGH (causes failures), MEDIUM (degrades quality), LOW (minor improvement)

Phase 3: Save Learnings

Write learnings to <skill-directory>/learnings/ using this format:

File naming

learnings/<date>-<short-description>.md

Example: learnings/2026-03-20-missing-error-handling.md

File format

---