/autolearn

name: autolearn
description: 'Use when a verified non-trivial fix lands or existing solution docs need refresh. Not for unverified fixes.'

Autolearn

Contract

| Field | Bound contract | |---|---| | Trigger | A non-trivial fix has been verified (observed working, not hoped working), or explicit autolearn or refresh invocation. | | Authority | Reversible local: writes only the operating repo's docs/solutions/ and repo-root CONCEPTS.md; rollback is version control. No remote mutation. | | Side effect | Writes or refreshes docs/solutions/ learning docs and CONCEPTS.md; stages only the surfaces this skill wrote or edited. | | Done | A validated learning or concept entry exists, or an explicit determination that nothing qualifies. |

Inputs

• The verified fix or solved problem, from conversation history or codebase. Must be supplied or derivable from context.
• Optional: `mode:refresh [scope]` to maintain existing docs; `mode:headless` for non-interactive operation.
• Optional: an injected auto-memory block (supplementary context, not primary evidence).

Procedure

0. Route the mode

Strip `mode:` tokens from arguments before treating the remainder as context or scope.

• **Capture** (default): document one solved problem into docs/solutions/.
• Vocabulary capture: a durable, reusable project term surfaces; reconcile CONCEPTS.md.
• Memory handoff: a fact about the user, preferences, or cross-project context surfaces; do not write it into docs/solutions/ or CONCEPTS.md; surface it as a memory-handoff candidate for the memory system to capture.
• Refresh: maintain existing docs/solutions/ and CONCEPTS.md.
• Headless: overlays any mode; skip all questions, never pause, apply safe actions, mark uncertain as stale.

Fire automatically on a trigger phrase ("that worked", "it's fixed", "working now", "problem solved", "verified the fix", "tests pass now", "build succeeds", "that approach failed") or after a verified non-trivial fix. Auto-firing is permission to evaluate, not permission to fabricate.

One run can do all three repo-scoped actions: write a learning doc, reconcile a concept, and flag a memory-handoff candidate.

Done when: the mode is routed and `mode:` tokens are stripped from arguments.

1. Reject-by-default gate

A doc is earned, not assumed. Verify all three preconditions:

1. The problem is solved, not in progress. An abandoned attempt counts as solved once it is finished (branch dead, decision to stop made); its learning is the anti-pattern: what was tried, the specific reason it failed, and the condition under which it would be worth trying again. 2. The solution is verified: observed working, not hoped working. 3. It was non-trivial, not a typo or obvious one-liner.

Then apply the reject-by-default gate (all three filters in order):

1. **Would I forget this?** Skip baseline knowledge anyone in this codebase already carries. 2. **Already covered?** If an existing docs/solutions/ doc covers it, updating that doc beats spawning a second one. A duplicate is drift, not knowledge. 3. **Universal or local?** Scope-qualify the claim. Say when a quirk is repo-specific and when a truth is general. An unqualified claim is a future trap.

The gate governs CONCEPTS.md entries too: a term earns a slot only when its precise local meaning would otherwise be forgotten, it is not already defined there, and it is scope-qualified to this project rather than general programming or domain English.

If nothing clears the gate, say so in one line and exit. A clean "nothing worth capturing here" is a valid, correct result.

Done when: all three preconditions and all three gate filters are evaluated, with a pass or a one-line "nothing qualifies" exit.

2. Capture: research (parallel, read-only)

Scan any injected auto-memory block for entries related to the problem. If it is absent or empty, skip it. If relevant entries exist, carry them as a labeled supplementary context block. Memory is supplementary; when it conflicts with the codebase or conversation, prefer the codebase or conversation. Tag any memory-derived line that lands in the final doc with `(auto memory [claude])`.

Dispatch three subagents in parallel. Each returns text and writes nothing.

1. **Context Analyzer**: from the problem, decide the track (bug vs knowledge), the problem_type, the category directory, and a slug filename (`[sanitized-problem-slug].md`, no date suffix). Return a frontmatter skeleton and which track applies. Do not invent enum values or fields. 2. **Solution Extractor**: extract the substance from the conversation, folding in the auto-memory excerpt as supplementary evidence. Bug track: Problem, Symptoms, What Didn't Work, Solution (with code), Why This Works, Prevention. Knowledge track: Context, Guidance, Why This Matters, When to Apply, Examples. 3. **Related-Docs Finder**: grep docs/solutions/ (`title:`, `tags:`, `module:`, `component:` on extracted keywords; narrow to the candidate subdirectory when known), read only frontmatter of candidates, fully read only strong matches. Score overlap across problem statement, root cause, solution approach, referenced files, prevention rules: High (4-5 dimensions), Moderate (2-3), Low (0-1). Return links and the overlap verdict.

Wait for all three before assembling.

Done when: all three subagents return and their results are assembled for the write step.

3. Capture: assemble and write

1. **Overlap gate**: High (4-5) → update the existing doc, keep its path and frontmatter, add `last_updated: YYYY-MM-DD`. Moderate (2-3) → create normally; note as a refresh/consolidation candidate. Low or none → create normally. Done when: the overlap gate decision is made. 2. Read `assets/solution-template.md`; assemble the doc with the track's section structure. Done when: the doc is assembled with the correct track structure. 3. Frontmatter per the Solution schema section; apply the YAML-safety quoting rule to array items. Done when: frontmatter fol