Keeping a project pitfall file

The library's measured pitfalls now sit inside the topic they belong to (for example Pitfalls: UI screens & modals under UI). This page is the one general rule for your own project: how to record a pitfall the day you pay for it, so the next agent does not pay again. The binding rule is EVERY-PITFALL-IS-SAVED on Recording a content pipeline; this page is the practical setup.

Rules

• PITFALL-FILE-EXISTS — every project has one pitfall index, found by the thing being touched, never by date. Use docs/pipelines/PITFALLS.md, grouped by area (UI, netcode, build, data and so on), or the area's own pipeline file when it has one. Check: the file exists and every heading is an area, not a date.
• PITFALL-LINE-SHAPE — one entry is one to four lines: scope, symptom, cause, fix or check, the gate that catches it, and the commit that proved it. Scope is [general] (true for any Unity project) or [project] (true only here). Check: every entry has all six parts; an entry with no gate names the gate to add.
• PITFALL-IN-THE-FIX-COMMIT — the line is written in the same commit as the fix. Check: a fix commit that changes behaviour also changes the pitfall file, or its message says why no pitfall applies.
• PITFALL-PROMOTE-GENERAL — a [general] entry is proposed for the library and the project line then points at the library rule id. Check: every [general] line carries either a rule id or "promotion proposed".
• PITFALL-NOT-IN-MEMORY — an agent's private memory or chat log is not where a pitfall lives. It may point to the file; it never replaces it. Check: each handoff states pitfalls saved: N or none found.

Template

## UI
- [project] Pause menu stays open after scene reload -> menu root is not reset on load ->
  reset in the scene-loaded handler. Gate: play-mode test "pause survives reload". Commit: the hash of the fix commit.

Replace the example with your own entries; keep the shape.