josherau Extract Approach — the reasoning recorder
Every hard solve contains two products: the fix, and the approach that found the fix. The fix ships; the approach evaporates when the session ends. This skill saves the approach — the more valuable half — as a permanent note any future model reads before touching similar work.
Why this exists: frontier models get repriced and retired. An answer helps once; a written-down approach upgrades every answer after it, at any model tier. The recipe requires top-tier judgment to author but only ordinary intelligence to follow.
Setup (one-time)
Pick a learnings directory in your knowledge base (e.g. {KNOWLEDGE_BASE}/learnings/) and keep a ## Learnings index — one line per lesson — in a file your sessions always load (CLAUDE.md is the natural place). Everything below assumes those two locations exist; adjust paths to your setup.
Trigger test (all three must hold)
- It was actually hard. At least one of: multiple failed attempts before the solve; a non-obvious insight was the turning point; a judgment call between 2+ viable approaches; a quality bar or heuristic was invented on the spot.
- It will recur. The problem shape (not the exact problem) will plausibly show up again in the user's work.
- The approach is transferable. You can state a recipe someone else could follow without this session's context.
If any fail, don't write a note — noise kills the learnings system faster than gaps do. Routine bug fixes, config edits, and lookups never qualify.
Timing: capture immediately at solve time, while the dead ends are still in context — never batched to session end. Logging mistakes the moment they happen is the same discipline; batching loses the details that matter.
What to capture
Write ONE file to {KNOWLEDGE_BASE}/learnings/{kebab-case-slug}.md. The format is: one-line summary, then Problem shape, Why it mattered, How to apply:
{One-line summary: the transferable heuristic, stated so it stands alone in an index.}
**Problem shape:** {What class of problem this was — described abstractly enough that a future session pattern-matches it BEFORE knowing the solution. 1-2 sentences.}
**Why it mattered:** {What was at stake, what failed first and WHY each dead end failed — the dead ends are half the value; they prune a future model's search tree. Include the turning-point insight and what made it non-obvious.}
**How to apply:** {The recipe. Numbered steps a mid-tier model could follow cold: what to check first, what signal discriminates between causes, what order to try things, what to never do. If a quality bar was invented, state it as pass/fail criteria.}
Rules:
- Recipe over narrative. "Check X; if Y, the cause is Z" beats a story about the debugging session.
- Dead ends are mandatory. An approach note without what didn't work is a success story, not a map.
- State the discriminating signal — the observation that separated the winning hypothesis from the losers. That's usually the part only a strong model notices, and exactly what must be written down.
- No session-specific residue. A reader with zero conversation context must be able to follow it.
Index it (not optional)
Add one line to the ## Learnings index in the file your sessions always load, matching the existing style:
- [{slug}](learnings/{slug}.md) — {one-line summary, compressed}
The index is what every future session actually loads; an unindexed note is invisible.
Dedup check first
Before writing, grep the learnings directory for the topic. If an existing lesson covers the same problem shape, update that file (sharpen the recipe, add the new dead end) instead of creating a near-duplicate. Delete lessons this solve proved wrong, and remove their index lines.
Scope notes
- Corrections and gotchas ("X doesn't work, do Y") still go through your normal learnings flow — this skill is specifically for multi-step reasoning approaches worth replaying.
- If the solve produced a reusable standard rather than a technique, put the checkable pass/fail criteria in a standards file and write a short learning that points at it.
- Routing vs adjacent skills: a whole-session retro skill reviews process; this skill is narrower — one hard solve → one recipe note, at solve time. They don't substitute for each other.
- Enforcement is by CLAUDE.md instruction (same class as review-panel) — there is no hook forcing it. Put the trigger text in your global CLAUDE.md; if it stops firing in practice, that's a compliance drift worth its own learning, not a config bug.