Skill: /self-learn

Portable Self-Learning System

OVERVIEW

A self-learning loop that captures mistakes and wins, promotes recurring patterns to hard rules, runs periodic retrospectives, and provides proactive workflow coaching.

/self-learn              → show status (counts, recent entries, pending promotions)
/self-learn log          → interactive: ask what happened, classify, and log it
/self-learn retro        → run a full retrospective analysis
/self-learn init         → initialize _patterns/ and _knowledge-base/ for a new project
/self-learn tips         → analyze recent patterns and give personalized workflow tips

The system gets smarter with every interaction. Log from day one.

STEP 0: Resolve Command

Parse the argument:

• No argument or status → jump to STATUS
• log → jump to LOG
• retro → jump to RETRO
• init → jump to INIT
• tips → jump to TIPS

INIT — Bootstrap for New Project

Check if the directories and files exist. Create anything missing:

_patterns/
  mistakes.jsonl          # one JSON object per line
  wins.jsonl              # one JSON object per line
  cross-project.md        # patterns that apply across projects/modules
  anti-patterns.md        # approaches that keep failing — stop trying them
_knowledge-base/
  decisions.md            # Architecture Decision Records
  api-docs/               # per-API gotcha files (e.g. steam-connect.md, supabase.md)

For each file, create it only if it doesn't exist. Never overwrite existing data.

Also check for .claude/skills/self-learn/config — if absent, do not create it (it's optional; the user creates it manually to set project_name:).

mistakes.jsonl — create empty (0 bytes). wins.jsonl — create empty (0 bytes).

cross-project.md — create with header:

# Cross-Project Patterns

Patterns proven in 2+ areas/projects. Promoted automatically by /self-learn retro.

---

anti-patterns.md — create with header:

# Anti-Patterns

Approaches that keep failing. When you're about to try one of these, stop and find an alternative.

---

_knowledge-base/decisions.md — create with header:

# Architecture Decision Records

| Date | Decision | Context | Alternatives Considered |
|------|----------|---------|------------------------|

After creating, print:

"Self-learning initialized. Directories and pattern files are ready. Start logging with /self-learn log after any significant task."

LOG — Capture a Mistake or Win

Step 1: Determine type

Ask the user:

"What happened? I'll classify it as a mistake (something went wrong or was corrected) or a win (something worked well, was confirmed, or saved time).

Describe it briefly, or say 'mistake' or 'win' to start from the category."

If the user describes the event, classify it yourself:

• User correction, failed approach, wrong assumption, redo → mistake
• Confirmed approach, clever solution, time saved, bug caught early → win

Confirm the classification before logging:

"I'd classify this as a [mistake/win]. Sound right?"

Step 2: Build the entry

For a mistake, gather these fields (ask for any you can't infer from context):

Project name resolution order: .claude/skills/self-learn/config (key project_name:) → basename of current working directory → ask the user.

{
  "date": "YYYY-MM-DD",
  "project": "<config file → working directory name → ask>",
  "task": "<what was being done>",
  "mistake": "<what went wrong>",
  "resolution": "<how it was fixed>",
  "pattern": "<generalizable lesson — one sentence>",
  "severity": "low|medium|high",
  "category": "<see category list below>",
  "had_verification": true|false,
  "session_hygiene": "<optional: kitchen_sink|correction_spiral|context_overload|null>"
}

Mistake categories (classify every mistake into one):

Session hygiene flags (optional — set when relevant):

Severity guide:

For a win, gather these fields:

{
  "date": "YYYY-MM-DD",
  "project": "<config file → working directory name → ask>",
  "task": "<what was being done>",
  "win": "<what worked well>",
  "pattern": "<reusable lesson — one sentence>",
  "reusable_in": "<where else this applies>",
  "had_verification": true|false,
  "used_plan_mode": true|false,
  "delegation": "subagent|manual|none",
  "decomposed": true|false
}

Field explanations for new fields:

• had_verification — Did the task have tests, linter checks, screenshots, or expected outputs for self-checking? (The #1 best practice from Anthropic: "the single highest-leverage thing you can do")
• used_plan_mode — Was plan mode / explore-first approach used before implementation?
• delegation — Was work delegated to subagents to protect main context?
• decomposed — Was the work broken into phases (search → plan → execute → verify) rather than a monolithic prompt?

Step 3: Append to file

Append the JSON object as a single line to the appropriate file:

• Mistakes → _patterns/mistakes.jsonl
• Wins → _patterns/wins.jsonl

Use the Write tool to append (read existing content, add new line, write back). Never overwrite — always append.

Step 4: Check for promotion triggers

After logging, immediately check:

For mistakes:

1. Read all entries in mistakes.jsonl
2. Extract the pattern field from each
3. Group similar patterns (same API, same type of error, same root cause)
4. If any pattern appears 2+ times → trigger promotion:

"This mistake has occurred [N] times. Promoting to a hard rule in CLAUDE.md:

• [RULE NAME] (promoted YYYY-MM-DD — [N] mistakes): [instruction]. Never [bad approach] — always [correct approach]. Verify by [verification step]."

Then actually add the rule to the project's CLAUDE.md under a ## Self-Learning Hard Rules section (create the section if it doesn't exist). Add it at the end of that section.

For wins:

1. Read the reusable_in field
2. If it mentions 2+ distinct areas or "all projects" → add to _patterns/cross-project.md

Step 5: Confirm

Print the logged entry and any promotions:

"Logged [mistake/win]. [N] total [mistakes/wins] tracked. [Promoted to hard rule in CLAUDE.md. / No promotion triggered.]"

STATUS — Dashboard

Read the pattern files and display a summary:

## Self-Learning Status

### Pattern Store
- Mistakes: [N] logged ([H] high, [M] medium, [L] low)
- Wins: [N] logged
- Cross-project patterns: [N]
- Anti-patterns: [N]
- Hard rules promoted: [N]

### Verification Rate
- Tasks with verification: [N]% (wins: [X]%, mistakes: [Y]%)
- Insight: [correlation observation]

### Mistake Categories
| Category | Count | % |
|----------|-------|---|
| [category] | [N] | [%] |

### Session Hygiene
- Kitchen sink sessions: [N]
- Correction spirals: [N]
- Context overloads: [N]

### Recent (last 5)
| Date | Type | Summary |
|------|------|---------|
| ... | mistake/win | pattern field |

### Pending Promotions
[List any patterns that have occurred 2+ times but haven't been promoted yet]

### Last Retrospective
[Date of last retro, or "Never — run /self-learn retro"]

RETRO — Full Retrospective

Step 1: Gather data

Read all of:

• _patterns/mistakes.jsonl — parse each line as JSON
• _patterns/wins.jsonl — parse each line as JSON
• _patterns/cross-project.md
• _patterns/anti-patterns.md
• The project's CLAUDE.md (for existing hard rules)

If mistakes.jsonl + wins.jsonl have fewer than 3 entries total:

"Not enough data for a meaningful retrospective. Log more interactions first. Current count: [N] mistakes, [M] wins." Stop.

Step 2: Analyze

Group mistakes by category: Count entries per category field. If entries lack the field, infer from description.

Identify recurring patterns:

• Any mistake pattern occurring 2+ times → flag for hard rule promotion
• Any mistake pattern occurring 3+ times → flag as anti-pattern

Verification correlation:

• Calculate win rate for tasks WITH verification vs WITHOUT
• If tasks without verification fail 2x+ more → flag for hard rule

Plan mode correlation:

• Calculate success rate for tasks that used plan mode vs didn't
• If skipping planning correlates with failures → flag for hard rule

Session hygiene analysis:

• Count each session_hygiene flag across all mistakes
• If any flag appears 3+ times → promote to anti-pattern

Delegation analysis:

• Compare success rate of tasks using subagent delegation vs none
• If delegation correlates with fewer context-related failures → flag as win pattern

Decomposition analysis:

• Compare success rate of decomposed tasks (phased) vs monolithic prompts
• If monolithic tasks fail more → promote decomposition as a best practice

Identify cross-project wins:

• Any win with reusable_in mentioning 2+ areas

Check for stale patterns:

• Any hard rule in CLAUDE.md that hasn't been triggered in 30+ days
• Any anti-pattern that might no longer apply (tech/API changed)

Step 3: Generate report

## Retrospective Report — {date}

### Stats
- Period: {earliest entry date} → {latest entry date}
- Mistakes: {N} ({high} high, {medium} medium, {low} low)
- Wins: {N}

### Verification Impact
- Tasks WITH verification: {N}% success rate
- Tasks WITHOUT verification: {N}% success rate
- Verdict: {observation}

### Planning Impact
- Tasks WITH plan mode: {N}% success rate
- Tasks WITHOUT plan mode: {N}% success rate
- Verdict: {observation}

### Top Mistake Categories
| Category | Count | Trend |
|----------|-------|-------|
| {category} | {N} | ↑ ↓ → |

### Session Hygiene Issues
- Kitchen sink sessions: {N} → {recommendation}
- Correction spirals: {N} → {recommendation}
- Context overloads: {N} → {recommendation}

### Recurring Mistakes (Need Hard Rules)
{For each pattern occurring 2+ times:}
- **{pattern}** — occurred {N} times (dates: {list})
  → PROMOTE to CLAUDE.md as hard rule

### Anti-Patterns to Stop
{For each pattern occurring 3+ times:}
- **{pattern}** — tried {N} times, failed every time
  → Add to anti-patterns.md

### Wins Worth Replicating
{For each win with broad applicability:}
- **{pattern}** — applicable to: {reusable_in}

### Cross-Project Opportunities
{Patterns from one area that could solve problems in another}

### Knowledge Base Updates
{New API gotchas, new decisions to document}

### Stale Patterns
{Hard rules or anti-patterns that may no longer apply}

### Action Items
- [ ] {specific update to make}

Step 4: Auto-apply

After generating the report, apply the changes:

1. Promote recurring mistakes to CLAUDE.md (under ## Self-Learning Hard Rules)
2. Add new anti-patterns to _patterns/anti-patterns.md
3. Add cross-project patterns to _patterns/cross-project.md
4. Flag stale patterns for user review (don't auto-remove)

Step 5: Confirm

Print the report and list what was changed:

"Retrospective complete. Applied:

• [N] new hard rules promoted to CLAUDE.md
• [N] new anti-patterns logged
• [N] cross-project patterns updated
• [N] stale patterns flagged for review

Anything surprise you? Anything I should weight differently?"

TIPS — Personalized Workflow Coaching

Analyze the pattern store and give actionable, personalized tips based on the user's actual tracked data. These tips come from official Claude Code best practices, real production patterns, and the user's own history.

Step 1: Read pattern data

Read _patterns/mistakes.jsonl and _patterns/wins.jsonl.

Step 2: Analyze and generate tips

For each category below, check if the user's data suggests the tip is relevant. Only show tips that are backed by the user's own patterns — don't dump generic advice.

Verification tips (if had_verification is false on 50%+ of mistakes):

"Add verification to your workflow. {N}% of your mistakes happened on tasks without verification (tests, linter checks, screenshots). Tasks WITH verification had a {X}% success rate. Try: include run the tests after implementing in your prompts, or add a PostToolUse hook that auto-runs your formatter."

Plan mode tips (if skipped_planning category has 2+ entries):

"Plan before multi-file changes. You've had {N} mistakes from jumping straight to code. Try: press Shift+Tab for plan mode, explore the code first, ask Claude to create a plan, then switch to normal mode to implement."

Context hygiene tips (if context_waste/session_hygiene flags appear):

"Use /clear more aggressively. {N} mistakes were context-related. Run /clear between unrelated tasks. If you've corrected Claude 2+ times on the same issue, /clear and rewrite a better prompt — a clean session with a better prompt almost always outperforms accumulated corrections."

Delegation tips (if context-related mistakes exist but few subagent wins):

"Delegate research to subagents. When Claude reads many files to investigate something, it fills your context. Try: use subagents to investigate X — they explore in a separate context and report back summaries."

Prompt quality tips (if prompt_quality category has entries):

"Be more specific in your prompts. {N} mistakes came from vague instructions. Instead of fix the login bug, try: users report login fails after session timeout. Check the auth flow in src/auth/, especially token refresh. Write a failing test that reproduces the issue, then fix it."

API integration tips (if api_error category has entries):

"Test APIs with minimal payloads first. {N} API mistakes logged. Before building the full integration, send the simplest possible request and confirm the format, field names, and auth work. Document gotchas immediately in _knowledge-base/api-docs/."

Decomposition tips (if mistakes involve large multi-step tasks):

"Break complex work into phases. Instead of one massive prompt like 'refactor this entire module, update tests, and fix docs,' decompose into: search phase → plan phase → execute phase → verify phase. The architecture is designed for decomposition, not monolithic prompts."

Command utilization tips (if pattern data shows underuse of slash commands):

"You're underusing the command surface. Claude Code has ~85 slash commands. Key ones to adopt: /compact (compress context, save tokens), /plan (map work before executing), /review and /security-review (structured code review), /cost (track spending), /resume (pick up where you left off). Most users know 5 commands — learn 15 and your workflow transforms."

Permission tips (if mistakes involve repeated permission interruptions or slow workflows):

"Configure wildcard permissions for recurring workflows. Instead of approving every git command, set Bash(git *) as always-allow. For file edits in your source: Edit(src/*). Set these in .claude/settings.json once and stop babysitting every action."

Operator mindset tips (always show if < 10 total entries — new users):

"Think like an operator, not a chatbot user. The biggest gap between average and top users: top users design a better operating environment (CLAUDE.md, permissions, hooks, MCP, skills) rather than just writing better prompts. Prompting is one lever. Environment design is the multiplier. Invest in your CLAUDE.md, permission rules, and connected tools."

Winning patterns (always show top 3 wins by reusability):

"Your best patterns:

1. {win pattern} — used in {reusable_in}
2. {win pattern} — used in {reusable_in}
3. {win pattern} — used in {reusable_in}"

Step 3: Summary score

Calculate a simple "learning score":

Score = (wins / (wins + mistakes)) * 100

Trend: compare last 7 entries vs previous 7 entries

"Learning score: {N}% ({trend: improving/stable/declining}) {observation about what's driving the trend}"

ALWAYS-ON BEHAVIORS

These behaviors run automatically, not just when /self-learn is invoked. They should be integrated into the project's CLAUDE.md as reminders.

Before Any Task

1. Check _patterns/mistakes.jsonl — have I made a related mistake before?
2. Check _patterns/anti-patterns.md — am I about to try something that keeps failing?
3. Check _patterns/wins.jsonl — is there a proven approach for this?
4. If the task involves an API, check _knowledge-base/api-docs/ for known gotchas
5. If the task touches multiple files, suggest plan mode first

During Any Task

• When unsure about an API's behavior → test with minimal payload first
• When a function/module might not exist → verify before using it
• When you spot a potential issue unrelated to the current task → flag it: "Heads up: I noticed [X]"
• When context is getting long → suggest /clear or subagent delegation

After Any Significant Task

1. Did anything fail that I had to retry? → Offer to log mistake
2. Did I find a clever solution? → Offer to log win
3. Did the user correct me? → Log mistake immediately (don't ask)
4. Did the user confirm a non-obvious approach? → Log win (easy to miss — watch for it)
5. Did the task have verification? → Note for correlation tracking

On Session Start

1. Check recently modified pattern files for context
2. If recent high-severity mistakes exist, mention them:

   "Heads up: recent issue logged — [pattern]. I'll watch for this."

Session Hygiene Monitoring

• If the conversation has mixed 3+ unrelated topics → suggest /clear
• If the same correction has been made 2+ times → suggest /clear and a fresh prompt
• If file reads exceed 20 in one investigation → suggest subagent delegation

RULES

1. Never overwrite pattern files — always append. Data is sacred.
2. Never delete entries — mark as resolved/stale instead.
3. Always confirm classification before logging — "I'd classify this as a [X]. Sound right?"
4. Log confirmations, not just corrections — if you only track mistakes, you become overly cautious and drift from validated approaches.
5. Severity is honest — don't downplay to avoid looking bad. High means high.
6. Promotion is automatic — 2+ occurrences = hard rule. Don't wait for the user to ask.
7. Retrospectives are non-judgmental — they analyze patterns, not blame.
8. Cross-project patterns require evidence — at least 2 distinct contexts confirming the pattern.
9. Anti-patterns are conclusive — 3+ failures of the same approach. Not just "didn't work once."
10. Stale patterns get flagged, not auto-removed — the user decides if they're still relevant.
11. Tips are data-driven — only show tips backed by the user's own pattern data, not generic advice.
12. New fields are optional — category, had_verification, session_hygiene, used_plan_mode, and delegation enrich analysis but should never block logging. If unknown, omit the field.