diff --git a/docs/PARAMETER-REGISTRY.md b/docs/PARAMETER-REGISTRY.md index 2b0d8f49c8..257487aba4 100644 --- a/docs/PARAMETER-REGISTRY.md +++ b/docs/PARAMETER-REGISTRY.md @@ -12,6 +12,29 @@ Rules: 2. All three resolve to the same registry row; changing the value changes it everywhere at once. 3. No bare values anywhere in code — a number never appears without its technical name. 4. Values live as registry rows (data), revisable, history logged per change. +5. Every row carries its own **why** — the reason it was set where it's set. + +## Finding new ones — no orphans allowed + +The failure mode: you're coding, you reach for a number, you type it +bare, and six months later nobody knows what it serves. So: + +1. **The linter is the shepherd.** No bare numeric literals in kernel + code (0, 1, and array indices excepted). Any magic number fails the + build with one message: *"register it or name it."* +2. **Registry-first workflow.** Need a new knob? Add the row first — + three names, full sentence, why — then use it. Thirty seconds now, + saves the archaeology later. +3. **Tuning proposes, registry disposes.** When behavior feels wrong + and the fix is "adjust something," that instinct is the discovery + event: propose a row for the thing you want to adjust. If two + different tweaks keep wanting the same knob, that's one parameter + trying to be born. +4. **Periodic sweep.** Grep for repeated suspicious literals; anything + appearing twice outside tests gets named. + +New parameters are discovered by friction. The registry makes sure +friction turns into knowledge instead of folklore. ## Registered parameters