mhylle/continuous-learning

Continuous Learning

Extract patterns from sessions and save them as structured skill files that future sessions can consult by trigger match. This is the layer above Claude Code's auto-memory: memory captures facts and preferences about you and your projects; continuous-learning captures reusable problem-solving patterns that need more structure than a memory entry can carry.

---

Scope — how this differs from auto-memory

Claude Code has a built-in memory system (~/.claude/projects/.../memory/) that captures user, feedback, project, and reference memories — short, typed entries loaded into every future conversation's context. Use that for:

• Facts about the user's role, preferences, responsibilities.
• Corrections you want applied in all future work ("don't mock the database in integration tests").
• Project-state facts like deadlines, decisions, stakeholders.
• Pointers to external systems.

This skill handles the things auto-memory doesn't:

• Triggerable patterns — full YAML files with an exact error-message trigger, root-cause analysis, and copy-pasteable fix. When that same error shows up six months later, the pattern surfaces.
• Structured templates per pattern type — not just free text. Consistent shape across error resolutions, user corrections, workarounds, debugging techniques, project-specific conventions.
• Reusable skills layer — files land in ~/.claude/skills/learned/, discoverable as portable skills across projects and machines.
• Usage + confidence tracking — a pattern that's worked 5 times carries more weight than one that's worked once.

Rule of thumb: a one-line fact goes in memory. A reproducible fix-recipe or debugging playbook goes here.

---

When to use

Automatic triggers:

• Stop hook — runs when a Claude Code session ends. See references/hook-setup.md.
• Session timeout — same mechanism.

Manual triggers:

• After solving a particularly difficult bug.
• When the user corrects an approach (indicating a learning opportunity).
• After discovering an undocumented workaround.
• When a debugging technique proves especially effective.
• After understanding project-specific conventions.

Signal phrases to watch for:

• "Save what we learned"
• "Remember this for next time"
• "This should be a pattern"
• "Extract learnings from this session"
• "What patterns did we discover?"

---

The five pattern types

Each pattern gets classified into one of five types. Full YAML templates and extraction criteria for each → references/pattern-types.md. Detailed examples → references/examples.md. Brief summary:

1. Error resolution — non-obvious fixes to errors where the root cause matters. Trigger is the exact error message or pattern.
2. User correction — insights when the user redirected your approach. Captures original-vs-corrected-vs-why.
3. Workaround — clever solutions to limitations in tools, frameworks, or environments. Includes "when will this become unnecessary."
4. Debugging technique — systematic approaches for specific problem classes. Includes indicators for "when to reach for this."
5. Project-specific — conventions unique to one codebase (architecture, naming, testing, deployment). Must include concrete examples and rationale.

---

Extraction workflow

Step 1 — Session analysis

Scan the session for these learning signals:

• Error/exception events — error messages, stack traces, failed commands. Note which required multiple attempts.
• User corrections — messages where the user redirected the approach; phrases like "actually", "instead", "don't do that".
• Workarounds — "can't do X, so we'll do Y"; framework/tool limitations encountered.
• Debugging journeys — investigation sequences; hypotheses tested and results.
• Project conventions — corrections about "how we do things here"; architectural patterns discovered.

Step 2 — Threshold evaluation

Apply the extraction threshold to filter noise:

Include if:

• Pattern would save significant time if encountered again.
• Solution wasn't immediately obvious from error/docs.
• Pattern is specific enough to be actionable.
• Context is clear enough for future matching.

Exclude if:

• Solution was the first result in documentation.
• Pattern is too generic to be useful.
• Context is too narrow (one-time unique situation).
• Better patterns already exist for this case.

Configurable threshold — tune via ~/.claude/config/learning.yaml:

extraction:
  threshold: 0.7               # 0.0-1.0, higher = more selective
  min_investigation_steps: 3   # Minimum complexity for extraction
  require_root_cause: true     # Must understand why, not just what
  max_patterns_per_session: 10 # Prevent noise

Step 3 — Structuring

For each pattern that passes threshold:

1. Classify type into one of the five categories.
2. Extract context — framework, version, environment.
3. Formulate trigger — when should this pattern be recalled?
4. Structure solution per the type-specific template (references/pattern-types.md). Pattern-body fields only — the surrounding file wrapper (metadata, usage:, confidence:, tags:) lives in references/storage-format.md.
5. Assign confidence — initial confidence based on validation level (goes in the wrapper's confidence: block, not the pattern body).

Step 4 — Deduplication

Before saving, check for existing similar patterns:

1. Load existing patterns from ~/.claude/skills/learned/
2. For each candidate:
   a. Search for patterns with similar triggers
   b. Search for patterns in same category/context
   c. Calculate similarity score
3. If similarity > 0.8:
   a. Merge — combine insights, increment times_applied
   b. Update — if new pattern is more complete, replace
4. If similarity < 0.8: save as new pattern

Similarity by type: error patterns compare error-message patterns; user corrections compare original/corrected approaches; workarounds compare limitations+solutions; debugging compares problem classes; project-specific compares project+category.

Step 5 — Storage

Write the pattern file and update the index. Full file layout, naming, and schema → references/storage-format.md.

---

Quality criteria

Scoring

Patterns that score ≥ the threshold get saved.

| Indicator | Weight | |---|---| | Non-obvious solution (answer wasn't in first search result) | High | | Time investment (took significant debugging time) | High | | Root-cause depth (understanding goes beyond symptoms) | High | | Recurrence likelihood (likely to encounter again) | High | | Transferability (applies beyond immediate context) | Medium | | Specificity (clear trigger conditions) | Medium | | Actionability (concrete steps, not abstract advice) | Medium |

quality_score = (
  non_obvious * 0.20 +
  time_investment * 0.15 +
  root_cause_depth * 0.20 +
  recurrence * 0.20 +
  transferability * 0.10 +
  specificity * 0.10 +
  actionability * 0.05
)

# Save if quality_score >= threshold (default 0.7)

What NOT to extract

• Documented in official docs (first page of results).
• Common knowledge for the technology stack.
• Insufficient context for future matching.
• Too narrow (unique one-time situation).
• Too broad (generic advice without specifics).
• Lacks root cause understanding.
• Would be outdated quickly (version-specific hacks).
• Duplicates existing patterns without adding value.

---

Best practices

Effective capture:

• Be specific: "React useState stale closure in event handler" > "React bug".
• Include context: framework, version, environment.
• Explain why — root cause beats surface fix.
• Show examples — concrete code beats abstract description.

Avoiding anti-patterns:

• Don't save obvious solutions — the first Google result doesn't need saving.
• Don't over-generalize — keep patterns focused and actionable.
• Don't skip validation — patterns should be tested before high confidence.
• Don't ignore updates — revisit patterns as frameworks evolve.

Pattern hygiene:

• Review patterns periodically (monthly suggested).
• Deprecate patterns for outdated framework versions.
• Merge similar patterns to reduce duplication.
• Increase confidence only after successful reuse.

---

Integration points

With context-saver: when context-saver runs at session end, it can include a "Patterns Discovered This Session" section pointing into ~/.claude/skills/learned/.

With brainstorm: learned patterns can inform brainstorming sessions — surface relevant patterns when discussing technical approaches, reference past workarounds when evaluating options.

With future sessions: at session start, patterns are loaded and available for automatic matching when similar errors occur, explicit recall ("what did we learn about X?"), and pattern suggestions during debugging.

---

References (loaded on demand)

• references/pattern-types.md — Full YAML templates and extraction criteria for all five pattern types
• references/examples.md — Complete worked examples, one per pattern type
• references/storage-format.md — Directory layout, file naming, skill file schema, index file structure, lifecycle
• references/hook-setup.md — Stop hook configuration, options, lifecycle integration, testing