71 lines
4.1 KiB
Markdown
71 lines
4.1 KiB
Markdown
---
|
||
name: docs-point-of-use-destruction
|
||
description: "Documentation exists for point of use, not archival. Use before any dedupe/compact/verify-docs job, and whenever a census or \"only copy\" argument is being used to KEEP documentation: apply the purpose test and destroy obsolete measurements. Supersedes the preservation conclusions of vault-one-fact-one-owner-dedupe §3/§12."
|
||
---
|
||
|
||
# Documentation exists for point of use
|
||
|
||
**Supersedes** `vault-one-fact-one-owner-dedupe` §3 ("port before cut") and §12
|
||
("expect docs flat") wherever those conclude a page must be *kept*. Sole custody of a
|
||
useless fact is still useless.
|
||
|
||
## The test, before you write and again before you keep
|
||
|
||
- Would the reader, doing a real task tomorrow, **act differently** because of this
|
||
line? No → delete it.
|
||
- Is it a measured rate (t/s, tok/s, ms, MiB-of-pool, acceptance %, a bench ladder) for
|
||
a model / runtime / layout that is **not running now and not being compared now**?
|
||
Destroy it. Not "file it in an Eras row", not "preserve it for history". AI moves
|
||
faster than the vault: the number is wrong before anyone reads it, and a wrong number
|
||
in a runbook gets believed.
|
||
- Keep the **law** the measurement taught; drop the measurement. Qualitative causal
|
||
stories survive; numbers do not.
|
||
- What survives: live config and its exact numbers, procedures, failure signatures,
|
||
security posture, interface contracts, rollback pointers.
|
||
- **Losing information is an acceptable, usually correct outcome.** Frank said so
|
||
explicitly on 2026-10-19 after rejecting a PR that had preserved 53 ledgers.
|
||
|
||
## Traps that lead agents to preserve junk
|
||
|
||
- **A census cannot decide what to keep.** `port-census.py`-style tools answer "where
|
||
does this fact live", never "does anyone need it". "14–63 sole-record lines per page"
|
||
was read as *irreplaceable* when the fact was *obsolete*. Ask usefulness, not custody.
|
||
- **A census that includes the file under test proves the page is held by itself.**
|
||
Exclude it, print the corpus size, assert absence; treat `0 unheld` on a long page as
|
||
a tool bug until proven otherwise.
|
||
- **"One fact, one owner" is a placement rule, not a preservation rule.** It says where
|
||
a surviving fact lives; it never says the fact must survive.
|
||
- **A change diary (`log.md`) is the largest archive in most vaults** (this one: 2,380
|
||
lines, ~8 % of the vault). Git holds the chronology; a causal law belongs on the page
|
||
that owns the thing it governs. Retire the diary.
|
||
|
||
## Execution that worked (2026-10-19, −13.7k lines)
|
||
|
||
1. Write the kill list as a reviewed artifact, one path per line, grouped by *why it is
|
||
dead* — that list becomes the PR's argument and the trash manifest.
|
||
2. Destroy whole pages first (`scripts/destroy-vault.py <list>`): move to
|
||
`.AGENTTRASH/<date>-destruction/`, then delete every reference from survivors, whole
|
||
line included when the dead link was its only content. Do not compare link targets
|
||
with `pathlib.Path.stem` — it strips real suffixes (`sd.cpp`).
|
||
3. Then strip numbers from what remains (`scripts/axe-measurements.py`): delete ledger
|
||
sections (noun-LEDS the heading, nothing instructional after it), blank any table cell
|
||
reporting a rate, fold Eras older than the current one into a single row pointing at
|
||
git. Never touch a shape number or a Laws/Wire/Rollback section.
|
||
4. Sweep indices (generator must exclude the trash dir, drop rows whose page cell became
|
||
empty), re-lint, re-check links.
|
||
5. Rewrite the governing policy in the same PR, or the next agent re-grows the vault:
|
||
project `AGENTS.md` *Documentation Policy* + the global agent settings.
|
||
|
||
## Report honestly, per area
|
||
|
||
docs / scripts / operator-doc separately, measured against the merge-base. The tools are
|
||
a cost that must be named, not hidden inside a headline "net" number — that is what got
|
||
the previous pass rejected.
|
||
|
||
## Verify the repair tools themselves
|
||
|
||
One repair pass matched "line ends with a comma" and deleted the trailing comma from 660
|
||
wrapped prose lines. Restore by matching lines that are byte-identical to `HEAD` except
|
||
for trailing punctuation (`restore-punctuation.py`), keep the destructive rule out of the
|
||
tool, and record the incident in its docstring.
|