Learn skill

The capture half of the self-improvement loop (disciplines/self-improvement-loop.md). A lesson that stays in conversation context dies at /clear; this skill is what turns it into something the next session — or the next agent — actually inherits.

When to use

Invoke at the end of a task, or any time one of three signals fires:

• Friction — a tool call had to be retried, the wrong file/table/approach was tried first, multiple attempts were needed before something worked, or an unexpected error required real investigation.
• Feedback — the user corrected an approach, said "the right way is X," or re-explained something that should already have been known. A correction that recurs (same topic, second time) is the strongest signal — it means the first capture missed or was never written.
• Discovery — a non-obvious tool/framework/infra behavior surfaced, a reusable pattern emerged, or a debugging journey ran long enough (multiple false starts, real time sunk) that losing the narrative would cost the next agent the same time back.

Skip when the task went smoothly, produced no correction, and taught nothing that isn't already written down somewhere (git history, the code, the task board, an existing memory or discipline). Memory and knowledge exist for what isn't recorded anywhere else — don't duplicate the repo into them.

Steps

1. State the mistake or discovery plainly. One or two sentences — what happened, what the wrong or surprising outcome was.
2. Trace it to the root cause / underlying fact. For a mistake: not "what fixed it" but "what principle was violated that let it happen" — keep asking why until you reach something transferable. For a discovery: what fact about the system, not just the symptom, would let someone skip the investigation next time.
3. Distill the principle. Write the general rule or fact the next agent should know, phrased so it applies beyond this exact file, task, or project. If you can't state it generally, you haven't reached the principle yet — keep tracing.
4. Route it using the decision tree below. Most lessons have exactly one home; a lesson that is both project-specific and generalizable gets written to both (see "Multi-target" below).
5. Dedup-check before writing. Search the target file/directory for the same topic (grep the key term). If an existing entry covers this, update it in place — sharpen the wording, don't append a near-duplicate. A library that only ever grows duplicates stops being navigable.
6. Write the entry as a principle, not a fix. Use the memory-file anatomy from docs/memory-system.md (frontmatter name / description / type) for memory entries, or the category template for a knowledge/ entry. Include the why (the cost of not following it) and, where relevant, how to apply (the concrete trigger for next time).
7. Link it back. Reference the source ([[other-memory-name]], a task-board item, a discipline file) so loading one surfaces its neighbors instead of leaving an island entry.
8. Retire what it supersedes. If this lesson replaces an older, now-wrong entry, update or delete that entry in the same pass — per docs/memory-system.md, a stale memory is worse than a missing one.

Knowledge-routing decision tree

Ask these in order; stop at the first match:

1. Is it a correction to how you (the agent) should work — a behavioral rule that should
   apply on every future task, not just this project?
   → memory/ (type: feedback) — one fact, one file, frontmatter per docs/memory-system.md.
   → If the SAME correction has now recurred twice, it has earned promotion: also add it
     (or a pointer to it) as a discipline in disciplines/, so it's always-loaded, not just
     indexed. Two disciplines should not say the same thing — if one already exists, sharpen
     it instead of adding a second.

2. Is it specific to one project in the portfolio — a wrong field, a bad command, an API
   quirk, something another agent working that project would hit but a different project's
   agent never would?
   → the project's knowledge pack (`templates/knowledge-pack.md` schape) under its own
     "Key pitfalls" section.
   → Ask: does the underlying mechanism generalize past this one project? If yes, ALSO write
     the generalized version to `knowledge/` (multi-target — see below). Don't let a broadly
     useful fact hide inside one project's pack.

3. Is it cross-project but about the framework/tooling itself — a design decision, a
   business/domain fact, a debugging quirk of the shell/git/CI layer you're operating in?
   → memory/ (type: project for decisions/direction, type: reference for "where a thing
     lives"). Add the routing-index pointer per `docs/memory-system.md` Layer 1.

4. Is it a durable technical fact, pattern, or narrative any agent working this portfolio
   should be able to find — independent of which project or session produced it?
   → knowledge/tech-discoveries/<topic>.md   — non-obvious framework/infra behavior
   → knowledge/patterns/<name>.md            — a recurring design or workflow pattern
   → knowledge/insights/<topic>.md           — a process heuristic or meta-learning
   → knowledge/problem-solving/<name>.md     — a debugging journey with real twists
   → knowledge/incidents/<name>.md           — a production/user-facing incident writeup
   (See `docs/knowledge-system.md` for the exact shape of each category.)

5. Does it reveal that an existing discipline or skill was wrong, missing a case, or would
   have prevented this if it had fired?
   → Fix the discipline/skill directly (`disciplines/skill-design.md` governs skill edits).
     Per `disciplines/curate-dont-accrete.md`: sharpening an existing rule beats adding a new
     one that competes with it for attention.

Cross-agent test (for step 4): if a different agent working a different project in this portfolio would make the same mistake without this fact, it belongs in knowledge/ — writing it only into one project's pack or one session's memory hides it from everyone else who needs it.

Multi-target rule: don't compress a lesson that has both a narrow and a general dimension into a single target. Example — a race condition found in one project's scheduler is a project-pitfall (pack) AND a distributed-systems pattern (knowledge/patterns/). Write both; losing the general half by only recording the narrow one is the more common failure than over-writing.

Entry quality bar

Include: non-obvious behavior a competent agent wouldn't guess from docs; anything that cost real debugging time; a correction likely to recur; a pattern seen in 2+ places that deserves a name.

Exclude: typos, one-off external outages, anything already in the code/README/task board, anything trivially findable in official docs.

Why this exists

The self-improvement loop (disciplines/self-improvement-loop.md) only compounds if the capture step is disciplined — a lesson that isn't traced to a principle, or that's routed to the wrong layer, either gets lost at the next /clear or bloats the always-loaded index instead of the on-demand archive. This skill is the one place that discipline lives, so every capture — regardless of which agent or project triggered it — lands in the same, predictable place.