| name | fw-trap |
| description | flightwake trap registration — write a non-obvious trap into the TRAPS registry. Use immediately when a surprising root cause is found (weird error, vendor quirk, encoding trap), or when the user says log this trap / trap. |
fw-trap — trap registration
Purpose: any given trap gets stepped in exactly once per project (including future sessions and other agents).
What qualifies for TRAPS
- Symptom and root cause are far apart (e.g., jsonb stored as a string scalar → root cause is the driver's encoding of "string parameter + ::jsonb")
- Undocumented vendor behavior (e.g., some operation path doesn't fire the webhook)
- Environment-difference traps (passes locally, explodes in prod)
- Doesn't qualify: ordinary bugs, anything obvious from reading the error message
Steps
- Follow the entry format demonstrated at the top of
.flightwake/TRAPS.md (OKF-style frontmatter: name/type/tags/discovered)
and write it at the top of .flightwake/TRAPS.md
- All four fields: symptom (paste the original error message), root cause in one sentence, fix/workaround, evidence link (commit/record)
- Link related traps with
[[name]]
- Write it on the spot — trap details fade within half a day
- When a new trap replaces or covers an existing entry: set the old entry's frontmatter
status to superseded and point its body at the [[new entry]] — never delete lines,
so an "old md vs new md" conflict always has a clear direction
- Judge the trap's scope: if it isn't specific to this repo — any project would step in it (platform/language/tool layer, e.g. Node stdin behavior, shell expansion) —
still register it in TRAPS (the repo's registry must be self-contained: the next person or agent can't see your personal memory),
and save a copy to your user-level memory (e.g. Claude memory) so your other repos don't re-trip it.
One copy per scope is division of labor, not duplication: a generic trap recorded in only one repo bites again in the next repo
