| name | capture-learning |
| description | Capture a single learning to .learnings/ when something surprising, painful, or validation-worthy happens during Kaggle work. Use proactively whenever an experiment fails for a non-obvious reason, a submission regresses, you hit a tool/API quirk, or a non-obvious approach is confirmed to work. Also use when the user says "remember this", "save this learning", "log this", or describes a mistake they don't want repeated. |
Capturing a Learning
Claude writes a single self-contained learning file to .learnings/. Each file is a durable memory that future sessions will read via the SessionStart hook and the recall-learnings skill.
When to invoke proactively
Any of:
- Submission score regressed and we now know why.
- An experiment failed for a non-obvious reason (class imbalance, leak, time budget, CV/LB mismatch).
- A Kaggle CLI / MCP / env quirk bit us (auth, rate limit, flag syntax, format gotcha).
- A non-obvious approach was confirmed to help (e.g. "group-k-fold by user_id beat random split by 0.02 AUC").
- The user explicitly asks to remember something.
When NOT to invoke
- When the fact is already in the codebase or git history. Those are not learnings — read them directly.
- When the fact is generic textbook ML. Reserve learnings for things specific to our work.
- When it's a fleeting task detail — use a todo, not a learning.
Steps
- Determine scope:
- If it generalizes across competitions →
scope: global.
- If it only applies to the current competition →
scope: <slug> (infer from cwd).
- Pick tags from the stable families (see
.learnings/README.md). Add one to three tags. Prefer reuse over invention.
- Estimate severity and cost:
scar + cost: high when it burned a submission slot or > 8h.scar + cost: medium when it cost 1–8h.pattern when it's a validated-good approach.note when it's a mild gotcha.
- Check for near-duplicates — run
grep -l "<key phrase>" .learnings/L-*.md. If found, decide: update the existing file, mark the older one recurring: true, or supersede it with a new file that references it.
- Generate an ID:
L-$(date +%Y-%m-%d)-NNN where NNN is the next free 3-digit sequence for that date. Use ls .learnings/L-$(date +%Y-%m-%d)-*.md 2>/dev/null | wc -l to pick NNN.
- Write the file using the template in
.learnings/README.md. Keep the body under 20 lines.
- Confirm to the user in one short sentence: "Captured L-… on ."
What makes a good learning
- Specific scar. "Submitted a CSV where ID column was float instead of int; Kaggle rejected the format." Not "watch out for types."
- Actionable rule. "Cast submission ID column with
.astype(int) before writing." Not "be careful."
- How to apply. One or two lines on when and where the rule kicks in.
- Link related learnings if this is a sibling or corrects an earlier one.
Creative directive
Write as if leaving a note for the next Claude session that has never seen this project. They need to act correctly on incomplete information. A good learning is one where reading only the Rule line is enough to avoid the mistake.
