learn

Learn

Extract insights from the current conversation and persist them to the project's knowledge base.

What This Does

Analyzes the conversation context to identify:

• Patterns: Approaches that worked well in this project
• Quirks: Project-specific oddities or non-standard behaviors discovered
• Decisions: Architectural or implementation choices made with their rationale

These insights survive session boundaries and context compaction, building a persistent understanding of the project over time.

Instructions

1. Analyze the conversation looking for:
2. Successful problem-solving approaches that could apply again
3. Unusual behaviors or gotchas discovered about the codebase
4. Decisions made and why (architectural choices, library selections, patterns chosen)

1. Categorize each insight as pattern, quirk, or decision

1. Format and append to the appropriate file in knowledge/learnings/:
2. patterns.md - What works well
3. quirks.md - Unexpected behaviors
4. decisions.md - Choices with rationale

1. Update metadata in each file's frontmatter (entry_count, last_updated)

1. Update state in knowledge/state.json:
2. Set last_extraction to current timestamp
3. Increment extraction_count
4. Reset queries_since_extraction to 0

1. Report what was learned to the user

Entry Format

Pattern Entry

## Pattern: [Short descriptive title]
- **Discovered:** [ISO date]
- **Context:** [What task/problem led to this discovery]
- **Insight:** [What approach works well and why]
- **Confidence:** high|medium|low

Quirk Entry

## Quirk: [Short descriptive title]
- **Discovered:** [ISO date]
- **Location:** [File/module/area where this applies]
- **Behavior:** [What's unusual or unexpected]
- **Workaround:** [How to handle it]
- **Confidence:** high|medium|low

Decision Entry

## Decision: [Short descriptive title]
- **Made:** [ISO date]
- **Context:** [What prompted this decision]
- **Choice:** [What was decided]
- **Rationale:** [Why this choice over alternatives]
- **Confidence:** high|medium|low

Confidence Levels

• high: Clear, verified insight with strong evidence
• medium: Reasonable inference, likely correct
• low: Tentative observation, needs validation

Only high and medium confidence insights influence routing decisions.

Steps

1. Review the conversation for extractable insights
2. For each insight found:
3. Read the target file (patterns.md, quirks.md, or decisions.md)
4. Check for duplicates (skip if similar insight exists)
5. Append new entry in the format above
6. Update frontmatter (increment entry_count, set last_updated)
7. Read and update knowledge/state.json
8. Report summary to user:

``` Knowledge Extraction Complete ───────────────────────────── Extracted: [Pattern] "Title of pattern learned" [Quirk] "Title of quirk discovered" [Decision] "Title of decision recorded"

Knowledge base now contains:

• X patterns
• Y quirks
• Z decisions

```

Example Extraction

From a conversation where we debugged an auth issue:

Quirk extracted:

## Quirk: Auth tokens require base64 padding
- **Discovered:** 2026-01-08
- **Location:** src/auth/tokenService.ts
- **Behavior:** JWT tokens in this codebase use non-standard base64 without padding, causing standard decoders to fail
- **Workaround:** Use the custom `decodeToken()` helper instead of atob()
- **Confidence:** high

Notes

• This command extracts insights from the CURRENT conversation
• For continuous extraction, use /learn-on instead
• Insights should be project-specific, not generic programming knowledge
• Avoid extracting obvious or trivial information
• When in doubt about confidence, use "medium"