learner

name	learner
description	Pattern learner. Activated when the user says "learn from this", "what patterns", "improve skills", "retrospective", "session review", or wants to extract reusable patterns from recent work to improve the project's skills and conventions.
allowed tools	Read, Grep, Glob, Bash, Write

Learner

Analyze completed work and extract patterns to improve existing skills, suggest new ones, and refine project conventions. This is a meta-skill: it makes other skills better.

Rules

1. Read-only analysis first — understand patterns before suggesting changes
2. Evidence-based — every suggestion must reference specific commits, files, or patterns
3. Conservative — suggest changes, don't auto-apply. The human decides what to adopt
4. Quality gate — only suggest patterns that appear 3+ times (not one-offs)
5. Output to docs — write the report to docs/architecture/learner-report-{date}.md

Workflow

Phase 1: Gather data

1. Run git log --oneline -N (N from args, default 20) to see recent commits
2. Run git log --stat -N to see which files changed most
3. Read the diffs of significant commits: git show --stat <sha>
4. Read existing skills in .claude/skills/*/SKILL.md
5. Read existing commands in .claude/commands/*.md
6. Read CLAUDE.md for current conventions

Phase 2: Analyze patterns

Look for:

A. Skill gaps

• Recurring manual steps that no skill covers
• Patterns Claude keeps explaining/doing that could be codified
• Workarounds or repeated code patterns across files

B. Skill improvements

• Skill rules that were violated in practice (maybe they're wrong)
• Skill checklists that are consistently skipped (maybe too strict)
• Skill triggers that didn't fire when they should have (description needs updating)
• Missing examples in skills that would have helped

C. Convention drift

• CLAUDE.md rules that don't match actual practice
• Commit message style drift from Conventional Commits
• File naming patterns that evolved beyond what CLAUDE.md documents

D. Hook gaps

• Errors that hooks should have caught but didn't
• Repetitive manual checks that could be automated
• New file types/patterns not covered by existing hooks

Phase 3: Report

Write a structured report:

# Learner Report — {date}

## Analyzed
- Commits: {N} (from {oldest_sha} to {newest_sha})
- Files changed: {count}
- Period: {date_range}

## Suggested new skills
### 1. [skill-name]
- **Pattern observed**: [what was done manually 3+ times]
- **Evidence**: commits {sha1}, {sha2}, {sha3}
- **Proposed trigger**: "[keywords]"
- **Proposed rules**: [list]

## Suggested skill improvements
### 1. [existing-skill-name]
- **Current rule**: [what the skill says]
- **Observed practice**: [what actually happened]
- **Suggestion**: [specific change]
- **Evidence**: [commits/files]

## Convention updates for CLAUDE.md
- [Specific addition or correction]

## Hook suggestions
- [New hook idea with trigger and behavior]

Phase 4: Present

1. Summarize findings (not the full report — just counts and highlights)
2. Ask which suggestions to adopt
3. If approved, create/modify the relevant skills, CLAUDE.md, or hooks

Phase 5: Conversation mining (optional, --conversations N)

Mine past Claude Code session transcripts for decisions, patterns, and insights that weren't captured in commits or docs.

How it works

1. Find recent session transcripts: ~/.claude/projects/{project-hash}/*.jsonl
2. Read the last N transcripts (default: 5)
3. Extract from each:
   • Decisions made — architectural choices, trade-offs discussed
   • Patterns repeated — same type of question asked across sessions
   • Errors encountered — recurring issues that should be Gotchas
   • Knowledge gaps — things the agent didn't know that a human corrected
   • Workarounds — solutions that worked but should be formalized

What to look for in transcripts

Signal	What it means	Action
Human corrected the agent 3+ times on same topic	Missing convention or Gotcha	Add to CLAUDE.md Gotchas
Same file read in every session	Core context the agent always needs	Add to CLAUDE.md Module Map or context-engineering hierarchy
Agent asked "should I...?" repeatedly	Missing boundary in agent/skill	Add Always Do / Never Do rule
Workaround described but never formalized	Missing skill or runbook	Propose new skill or add to existing
Human shared external link for reference	Source-driven gap	Add to source-driven-development source table

Output

Append a ## Conversation insights section to the learner report:

## Conversation insights (from N sessions)

### Decisions not documented
- [Decision] — found in session {date}, not in any ADR
  - **Suggestion**: create ADR-{N} or add to CLAUDE.md

### Recurring corrections
- [Topic] — human corrected agent {count} times across {sessions} sessions
  - **Suggestion**: add Gotcha or skill rule

### Knowledge gaps
- [Gap] — agent didn't know [X], human provided [reference]
  - **Suggestion**: add to source-driven-development table or CLAUDE.md

Configuration

• Analysis scope: [SPEC] --since "2 weeks ago" or --commits 20
• Conversation scope: --conversations N (default: 5 most recent transcripts)
• Minimum pattern frequency: 3 (to suggest as a skill)
• Output: docs/architecture/learner-report-{date}.md

References

• Inspired by oh-my-claudecode's Learner skill (level 7)
• See .claude/skills/_template-skill/SKILL.md for new skill format
• See CLAUDE.md for current conventions
• Cross-project insight: conversation mining concept from lucasrosati/claude-code-memory-setup