pattern-card

Write a pattern card

The moment debugging ends is when the knowledge is cheapest to capture. A card moves the reason a fix exists out of someone's head and into the repo, so the next session does not "clean up" the guard and reopen the bug.

Steps

1. Read PATTERNS.md: its index, the highest card number, and any card that already covers this area. If an existing card covers the same root cause, extend that card instead of adding one.

2. Draft the card from this session's actual evidence:

   ### PATTERN-<NN>: <one-line name of the failure>
   
   - **Symptom:** what was actually seen - error text, wrong output, crash - not the cause.
     Several symptoms with one cause? List them all; co-occurrence is a clue.
   - **Debug path:** what was checked, in order, including the dead ends.
   - **Root cause:** one or two sentences. Cannot state it that tightly? It is not found yet.
   - **Prevention rule:** a concrete, checkable rule. "Be careful" is not a rule;
     "always pass `**kwargs` to the worker callback" is. (learned <version or date>)
   

3. Add the card number to the index row for the touched area (create the row if needed). A card missing from the index is a card nobody will read.

4. If the prevention rule can be enforced by a hook, test, or linter, propose that too - and say so in the card.

5. Show the card and the index change before saving.

Rules

• Do not copy the prevention rule into the main rules file; link the card number instead.
• Past roughly 25 cards, split into per-area files and keep PATTERNS.md as the index.