Learnings

---
name: learnings
description: "Final pre-commit sweep — review the session and code changes for anything worth codifying in CLAUDE.md or README.md."
---

# Learnings

Final pre-commit sweep: did we learn anything in this session that the next person (or agent) working in this repo will regret not having written down?

The bar is **high**. Most sessions produce nothing worth adding. That's fine. Saying "nothing worth adding" is a valid — and often correct — outcome. Do not invent findings to justify the skill.

## Step 1: Gather context

Run these in parallel:
- `git diff` (unstaged) and `git diff --cached` (staged) — what actually changed
- `git status` — new files, deleted files
- `git log --oneline -20` — recent commit style and scope
- Read `CLAUDE.md` if it exists (project root, then `.claude/CLAUDE.md`)
- Read `README.md` if it exists

Also re-read this session's conversation: what did the user correct you on? What did you stumble over? What non-obvious thing did you discover about the codebase?

## Step 2: Apply the bar

A candidate learning is worth codifying **only** if it meets at least one of these:

1. **Non-obvious gotcha** — something that cost real time this session and will cost real time next time. ("The build silently caches X, you have to nuke `.cache/` to actually re-run.")
2. **Convention the code doesn't self-document** — a pattern, naming rule, or structural choice that isn't visible from reading one file. ("Migrations must be written idempotent because they run on every boot.")
3. **User correction that is reusable** — the user pushed back on an approach in a way that applies beyond this task. ("Don't add error boundaries around server components in this repo — they swallow Next.js's own error UI.")
4. **External dependency or env requirement** — something a fresh clone wouldn't work without. ("Requires `STRIPE_WEBHOOK_SECRET` in `.env.local` or checkout tests fail silently.")
5. **Architectural decision with a reason** — a choice that looks arbitrary without the why. ("We hand-roll the queue instead of using Sidekiq because Rails 8 solid_queue handles our volume and removes the Redis dep.")