Learn

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

Usage

/learn          # Quick extraction from recent conversation
/learn --deep   # Thorough analysis with forked context (uses Explore agent)

--deep Mode

When --deep is specified, the extraction runs in a forked context using the Explore agent:

• •More thorough codebase analysis to find related patterns
• •Cross-references with existing knowledge
• •Validates discoveries against actual code
• •Keeps analysis chatter out of your main conversation

Use --deep when you've had a significant debugging session or made architectural decisions you want fully documented.

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:

   • •Successful problem-solving approaches that could apply again
   • •Unusual behaviors or gotchas discovered about the codebase
   • •Decisions made and why (architectural choices, library selections, patterns chosen)
2. •

   Categorize each insight as pattern, quirk, or decision

3. •

   Format and append to the appropriate file in knowledge/learnings/:

   • •patterns.md - What works well
   • •quirks.md - Unexpected behaviors
   • •decisions.md - Choices with rationale
4. •

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

5. •

   Update state in knowledge/state.json:

   • •Set last_extraction to current timestamp
   • •Increment extraction_count
   • •Reset queries_since_extraction to 0
6. •

   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:
   • •Read the target file (patterns.md, quirks.md, or decisions.md)
   • •Check for duplicates (skip if similar insight exists)
   • •Append new entry in the format above
   • •Update frontmatter (increment entry_count, set last_updated)
3. •Read and update knowledge/state.json
4. •Report summary to user:
   code

   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"