Learnings

/learnings

End-of-session compound learning capture. Mirrors the docs/solutions ritual that Boris Cherny popularised at Every — every non-trivial session writes 0–3 entries that the next session can find by grep.

When to Run

• At the end of any session that involved real debugging, design decisions, or surprises (i.e., basically every session).
• Not on typo / one-line / cosmetic sessions. Skip then.
• Not on routine "rebase + push" maintenance unless something broke.

The Iron Law

ONLY write a learning when something was SURPRISING or NON-OBVIOUS.
NEVER duplicate a learning that already exists in docs/solutions/.
NEVER write a "what I did" diary — that's the PR description's job.
A learning answers "what would have saved me 30 minutes today?"

If nothing in the session meets that bar, the right answer is to write zero entries. Empty output is allowed and expected.

Process

Step 1: Scan the session

Walk the conversation. Pull out anything that fits one of:

• Bug archaeology — root cause was non-obvious; future-me would benefit from the writeup. (e.g., "p.r vs part.r refactor leftover was throwing ReferenceError because the loop variable was renamed in only half the file.")
• Workflow gotcha — a tool/process behaviour that wasted time and is recoverable from. (e.g., "Vite dev server tunnels straight to cloudflared — committing fixes the deploy, no separate build step.")
• Architectural decision with a rationale — picked X over Y, the reason isn't in the code. (e.g., "FABRIK over CCD because chains are short and we need preserved bone lengths exactly.")
• Cross-repo or contract subtlety — something that touches GA + ix / Demerzel / tars and the linkage isn't documented elsewhere.
• API quirk — third-party service or library with surprising behaviour. (e.g., "GraphQL metadata returns numbers not strings despite TS type saying Record<string,string>.")
• Performance / scaling surprise — a path that's slower or faster than expected, with the why.