If it can be derived, generate it — never hand-maintain a second copy

The rule

Indexes, status boards, summary tables, counts: derive them from the source content, in a script, every time. Never hand-write a second representation of data that already exists somewhere else.

The scar

Incident 1 — the drifting board. A status board summarizing a set of findings was maintained by hand alongside the markdown that actually tracked them. Within days they disagreed: items resolved in the source still showed outstanding on the board, and the board was the copy people actually looked at. The fix wasn't "update the board more carefully" — it was deleting the hand copy and generating it from the source, so drift became structurally impossible. A second hand-edited copy is the same drift problem wearing a new coat.

Incident 2 — the same failure one layer up. Once the board was generated, a second board was produced for a different audience by a separate command. It went stale immediately, for exactly the same reason. Fixed by making one run emit both, failing loudly if either render failed — so a stale copy can't be left sitting where someone will send it onward.

Incident 3 — a prior documentation framework, audited later. An earlier personal project built a genuinely thoughtful docs system with a hand-maintained decision-record index. Audited months afterward: all ten of its links were broken (a relative-path error repeated in every row), and the documented prompt-library listing advertised 4 system prompts, 9 modules, 10 tasks and 4 templates where the actual counts were 3, 6, 2 and 2 — roughly 40% of the index pointed at files that were never written. Section numbering had drifted so that directory 06 contained a document titled "5.", and the README advertised an agent directory that did not exist.

Nothing here was carelessness; it was a good framework with no generator. Every single one of those errors is a class a generated index plus a link check catches on day one, for free, forever.

How to apply

1. Any file that summarizes other files carries a generated-by header and a "do not hand-edit" line — and means it.
2. Validate links as part of generating. A generated index with unchecked relative paths is only a faster way to produce the same broken output.
3. Regenerate as part of the write, not as a periodic chore. If regeneration is a separate task someone has to remember, it's already drifting.
4. When two audiences need two views, generate both from one run. Two commands is two opportunities for one to be forgotten.
5. Fail loudly on partial generation. A half-written index that looks complete is worse than a missing one.
6. Corollary for numbers: before comparing two counts, verify they count the same unit. Two documents once disagreed by ~100 items purely because one counted raw commits and the other counted distinct changes — both correct, neither comparable, and hours went into "finding the discrepancy" that was a unit mismatch.