# The GOTCHAS pattern

The projects I run with AI each have a file called `GOTCHAS.md`. It holds the facts about how things
actually behave, the stuff you only learn by getting burned. Each session reads it, top to bottom,
before it starts work. It's probably the single file that saves the most repeat mistakes.

## The rules

1. **One fact per bullet, with the date.** `- 2026-01-15: <the fact>`. The date matters because
   tools change, and a newer fact beats an older one.
2. **Behavior goes here, history goes in the changelog.** "The API returns an empty list, not a 404, when nothing matches" goes
   here. "We spent an hour on the API today" goes in the changelog.
3. **Short.** The rule plus the name of the thing it's about, a sentence or two. If it needs a page,
   the page lives somewhere else and the bullet links to it.
4. **It beats older docs.** When a gotcha disagrees with a README or a wiki page, the gotcha wins,
   because it was learned the hard way and it's dated.
5. **Keep it small enough to read whole.** I cap mine at 16KB. A file a session can't afford to read
   is worse than no file. When it gets too big, split it by area (`GOTCHAS-email.md`,
   `GOTCHAS-deploy.md`) and keep `GOTCHAS.md` as a short index that says which file covers what.
   Move old facts to an archive file. Don't delete them.
6. **Facts that apply to more than one project move up.** If it's true for every project that uses a
   tool, it goes in a shared gotchas file for that tool, not in one project.
7. **Record the answer, not just the question.** When a person answers something, put their answer
   here (or in the pass file) with their words, so nobody asks them twice.

## Template

```markdown
# <project> GOTCHAS

Distilled behavioral facts, one dated bullet each. Read whole at the start of every session.

- YYYY-MM-DD: **<short name of the thing>.** <What it actually does.> <What to do about it.>
- YYYY-MM-DD: **<tool> <quirk>.** <The exact error or behavior you saw.> <The fix or workaround.>

## Known-hard / failed approaches

- YYYY-MM-DD: **<what we tried to do>.** Tried: <approach 1>, <approach 2>. Failed with: <exact error>.
  Ruled out: <what we know it isn't>. Would work if: <what would have to be true>.

## Answers recorded

- <the question>: <the answer, in the person's words> (<who>, <date>)
```

## Example bullets (made up, but the shape is real)

- 2026-02-03: **Search results lag about a minute** after a write. Wait 60 seconds and re-read by id
  before stating a count.
- 2026-02-10: **The scheduler's times are in UTC, the dashboard shows local time.** Convert before
  comparing the two.
- 2026-02-18: **An update that leaves a field out keeps the old value forever.** Send the field
  explicitly when you mean to change it.

The "failed approaches" section is the one people skip, and it's the one that saves the most time.
If you don't write down what didn't work, the next session tries it again.