Gotcha
03-knowledge/gotchasA trap discovered mid-session. Committed in the same session; read before touching again.
What it is
A gotcha is a quirk or trap the agent discovered the hard way — a framework surprise, a race condition, an auth flow gotcha. Captured once, it never costs the team time again. The 03-knowledge/ directory is the methodology's highest-compounding asset.
When to write it
The moment you hit something that 'took 30+ minutes to figure out' or that 'someone else will hit'. Commit it in the same session as the brief that found it — capture is not optional.
What goes in it
- The problem — the symptom, specifically
- The root cause
- The fix
- How to prevent or avoid it next time
How it fits
One of three knowledge artefact types. The Router loads the knowledge index before sessions that touch the relevant area, so the gotcha is read before the code is.
Get the templatestarter/docs/03-knowledge/gotchas/knowledge-gotcha.md