--- allowed-tools: - Read - Edit - Write - Grep - Glob argument-hint: '[topic] [--dry-run]' description: Extract durable learnings from a session and propose project customizations — agent-instructions file, CONTEXT.md, ADRs, project skills, hooks. Use when the user says "learn", "extract learnings", "what did we learn", "save learnings", "adapt config", "capture domain language", or wants to encode session patterns durably. NOT for documentation edits (use documenting-code) or committing changes (use committing-code). model: sonnet name: learning-patterns user-invocable: true --- # Learn from Session Extract actionable, durable learnings and propose project-specific customizations. Ground every change in actual conversation or tool evidence. Ask one question at a time when confirmation is needed. ## Routing - Use only for durable project learning: reusable instructions, domain language, decisions, commands, skills, hooks. - Documentation edits route to `documenting-code`. - Do not fabricate. If evidence is missing, say extraction is blocked and ask for it. - Secrets, credentials, local paths, transient debugging details, and one-off failures are non-durable unless the user explicitly says otherwise. - Always name the exact target artifact before proposing persistence. ## Workflow If the user passed a topic, scope extraction to that topic. If the user passed `--dry-run`, run Phases 1–7 only. ## Phase 1: Discover Read existing Claude Code customization files: - `CLAUDE.md` or `.claude/CLAUDE.md` — project memory - `.claude/skills/*/SKILL.md` — project skills - `.claude/agents/*.md` — project subagents - `.claude/commands/*.md` — project commands - `.claude/settings.json` — hooks and permissions - `.claude/rules/*.md` — rules (if used) - `CONTEXT.md`, `CONTEXT-MAP.md` — domain language - `docs/adr/*.md` — durable decisions - `.out-of-scope/*.md` — rejected scope with reasoning Record counts for the budget check. ## Phase 2: Extract Scan the conversation for these signal types. Instruction signals → agent-instructions file: - Corrections: "no", "wrong", "actually", "instead" - Direct guidance: "always", "prefer", "use X", "never" - Repeated explanations of the same point - Project quirks: unexpected behavior, edge cases, workarounds - Workflow sequences that consistently worked Domain signals: - Term resolution → `CONTEXT.md` ("call this X", "X means", overloaded jargon) - Ambiguity resolved → `CONTEXT.md` ("not account, customer", "avoid Y") - Hard-to-reverse trade-off → `docs/adr/` (surprising, real alternative) - Scope rejection → `.out-of-scope/` ("we will not support X because") Skill signals → project skills directory. Promote to a skill only when the workflow is repeated or likely to recur, multi-step enough to forget details, tool-heavy or evidence-heavy, and specific enough to trigger reliably. Prefer updating an existing skill over creating a duplicate. Hook signals → settings: - Blocking rule ("never do X", "always block Y") — HIGH confidence - Validation hook ("always run linter after edit") — HIGH - Format requirement ("use prettier on save") — MEDIUM - Approval pattern ("ask before destructive commands") — MEDIUM Only HIGH-confidence items become skills or hooks. MEDIUM items become single-line entries in the agent-instructions file instead. ## Phase 3: Categorize Pick exactly one target per learning: - Reusable workflow or coding instruction → `CLAUDE.md` or `.claude/CLAUDE.md` - Domain term → `CONTEXT.md` - Hard-to-reverse decision with real trade-off → `docs/adr/NNNN-slug.md` - Repeated multi-step workflow → `.claude/skills//SKILL.md` - Blocking, validation, or approval automation → `.claude/settings.json` hooks - Rejected feature with reasoning → `.out-of-scope/.md` If no target is justified, drop the learning. ## Phase 4: Distill Agent-instructions entries — one-line rules, ~80 chars max: - `Use X for Y.` - `Prefer X over Y.` - `When X, run Y.` - `Never X without confirmation.` - ``Run: ```.`` - ``Note: ```.`` CONTEXT.md entry shape: ```markdown **Term**: One-sentence definition. Avoid: overloaded synonym. ``` ADR entry shape (`docs/adr/NNNN-slug.md`): ```markdown # Decision title Context, decision, why — one to three sentences. ``` Write ADRs only when the decision is hard to reverse, surprising without context, and has a real alternative. Out-of-scope entry: capture rejected enhancements with reasoning and any prior requests so the same idea is not re-litigated. Project skill: follow [agentskills.io](https://agentskills.io/specification). Required `name` and `description` frontmatter + markdown body. Description must state what the skill does and concrete trigger phrases. Body under ~150 lines; deep references go in sibling files. Vendor-neutral instructions, no platform-specific tool names. ## Phase 5: Deduplicate Read each existing artifact and look for overlaps. Merge rules: - New adds specificity → update existing with concrete details. - New adds an example → append to existing. - Both have value → combine into one item. - New is subset of existing → skip. - Name collision → merge into existing file. Prefer updating existing over creating new. ## Phase 6: Budget check Recommended limits: - Agent-instructions file: ~200 lines (context efficiency) - `CONTEXT.md`: concise — domain terms only - ADRs: sparse — decisions, not diary - Skills: ~5 user-invocable per project for discoverability - Hooks: ~5 for debugging simplicity Over budget → propose consolidations or stale removals before adding more. ## Phase 7: Present and confirm Show all proposed changes grouped by target file. Use `+` for additions, `~` for updates. Include the rollback command (typically `git checkout`). Ask one question for approval: apply all / select items / edit first / no. For "select items", show one selector per category. ## Phase 8: Apply - Agent-instructions file: edit existing lines or append in the appropriate section. - `CONTEXT.md`, ADRs, out-of-scope: write or edit. - Skills: create directory + `SKILL.md`, plus supporting files when needed. - Hooks: merge into existing settings. ## Phase 9: Verify Re-read every changed file. Check: - Specific, non-duplicative, grounded in session evidence. - Frontmatter and paths valid. - Referenced commands resolvable when practical. - Generated skill follows agentskills.io rules. Report verification results and any skipped checks with reasons. ## Output ```text LEARNED Instructions: +N ~N Domain docs: +N ~N Skills: +N ~N Hooks: +N ~N Applied: - file — change Verification: - check — pass/fail ``` ## Edge cases - Empty session → "No learnings detected. Try after a longer conversation." - All low-confidence items → bundle as instructions in the agent-instructions file. - No customization directories yet → ask before creating them. - `--dry-run` → run Phases 1–7, skip 8, still show what would change.