Extract a key insight from a completed task and write a short teaching lesson. Use after finishing a non-trivial bug fix, feature, refactor, or investigation.
After completing non-trivial work (bug fix, feature, refactor, or investigation), extract one key insight — something you had to know or figure out — and teach it as a short, digestible lesson.
Write a lesson when the conversation involved:
Skip it for purely mechanical changes (typo fixes, renaming, trivial config tweaks).
Keep it short — aim for under 30 lines. Use this structure:
# <Lesson Title>
**Why it matters:** One sentence on when this knowledge applies.
## The concept
Two to four sentences explaining the core idea clearly.
## In this codebase
A concrete code snippet or reference to the specific file/function where this appeared.
## Key takeaway
One crisp sentence the reader should remember.
Get the current short commit hash:
git rev-parse --short HEAD
Save to:
docs/lessons/<lesson-category>/<lesson-topic>/<lesson-name>-<short-hash>.md
lesson-category — high-level grouping (e.g. typescript, react, scoring, parsing, architecture)lesson-topic — more specific subject within the category (e.g. generics, hooks, wgi-eras, competitionsuite)lesson-name — kebab-case name for the specific lesson (e.g. cross-era-domain-normalization)short-hash — first 7 characters of the current git commit hashReuse existing category and topic directories where they fit. Create new ones only when no existing grouping applies.
After writing the lesson, briefly surface the key takeaway inline in the conversation so it is visible without opening the file.