---
title: "Keeping a project pitfall file"
slug: /workflows/pitfall-file/
markdown: /workflows/pitfall-file.md
section: pitfalls
tier: 1
summary: "Where a project writes down each trap it hits, in what shape, and when a project lesson becomes a library rule."
sources: ['content-pipeline.md EVERY-PITFALL-IS-SAVED']
canonical: https://unityworkflowlibrary.dev/workflows/pitfall-file/
read_first: /read-first.md
---

> Read first, on every prompt: [non-destructive rules](/read-first.md).

# Keeping a project pitfall file

> Where a project writes down each trap it hits, in what shape, and when a project lesson becomes a library rule.

The library's measured pitfalls now sit inside the topic they belong to (for example [Pitfalls: UI screens & modals](/workflows/pitfalls-ui/) 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](/workflows/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

```text
## 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.