learn（学习）

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)

1. Categorize each insight as pattern, quirk, or decision
2. Format and append to the appropriate file in knowledge/learnings/:

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

1. Update metadata in each file's frontmatter (entry_count, last_updated)
2. Update state in knowledge/state.json:

- Set last_extraction to current timestamp - Increment extraction_count - 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:

- 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)

1. Read and update knowledge/state.json
2. 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"