| 1 | --- |
| 2 | name: history-hygiene |
| 3 | description: Record final outcomes to history.md, not intermediate requests or reversed decisions |
| 4 | domain: documentation, team-collaboration |
| 5 | confidence: high |
| 6 | source: earned (Kobayashi v0.6.0 incident, team intervention) |
| 7 | --- |
| 8 | |
| 9 | ## Context |
| 10 | |
| 11 | History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. The Kobayashi incident proved this: history said "Brady decided v0.6.0" when Brady had reversed that to v0.8.17. Future spawns read the wrong truth and repeated the mistake. |
| 12 | |
| 13 | ## Patterns |
| 14 | |
| 15 | - **Record the final outcome**, not the initial request. |
| 16 | - **Wait for confirmation** before writing to history — don't log intermediate states. |
| 17 | - **If a decision reverses**, update the entry immediately — don't leave stale data. |
| 18 | - **One read = one truth.** A future agent should never need to cross-reference other files to understand what actually happened. |
| 19 | |
| 20 | ## Examples |
| 21 | |
| 22 | ✓ **Correct:** |
| 23 | - "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by Brady)" |
| 24 | - "Reverted to Node 18 per Brady's explicit request on 2024-01-15" |
| 25 | |
| 26 | ✗ **Incorrect:** |
| 27 | - "Brady directed v0.6.0" (when later reversed) |
| 28 | - Recording what was *requested* instead of what *actually happened* |
| 29 | - Logging entries before outcome is confirmed |
| 30 | |
| 31 | ## Anti-Patterns |
| 32 | |
| 33 | - Writing intermediate or "for now" states to disk |
| 34 | - Attributing decisions without confirming final direction |
| 35 | - Treating history like a draft — history is the source of truth |
| 36 | - Assuming readers will cross-reference or verify; they won't |