command-center/agent/managed-skills/magic-number-provenance-audit/SKILL.md

name, description

name	description
magic-number-provenance-audit	Audit every numeric threshold in a change before shipping it: classify provenance (inherited port / declared authority / invented), delete invented arithmetic, and replace budgets with derivations quoted from the repo's own config. Use when adding or reviewing a cap, window, timeout, ratio, or size ladder, or when asked "what's with the magic numbers?".

Magic-number provenance audit

A threshold with no source is a bug with a comment on it. The deliverable is either a derivation from an authority the repo already trusts, or deletion of the arithmetic.

1. Census, do not defend

Grep the changed paths for every numeric literal (exclude the module being rewritten so its own digits don't hide the pattern):

grep -rn "1536\|4000\|700\|6000\|n_ctx\|contextWindow\|maxTokens\|tokens" src/*.ts

Table per number: value | file:line | provenance | verdict. Provenance is exactly one of:

• inherited port — copied from upstream, pinned by a contract test. Keep, but say so in the doc comment.
• declared authority — a field the runtime/fleet config already publishes.
• derived — computed from beats it guards (e.g. lease TTL = 3 heartbeats).
• invented — yours. This is the finding. Say "mine, invented", not "chosen".

Also flag the application of a number, not just its value: a slice like text.slice(0, MAX_INPUT) is a head-only silent drop (loses the tail of a dump); a floor is a different animal from a cap even at the same digit.

2. Find the authority before writing a digit

Rank of acceptable sources, best first:

1. The runtime's own published field. ~/.omp/agent/models.yml model rows carry contextWindow (PER-SLOT for llama.cpp: it divides --ctx-size across slots) and maxTokens. The fleet's own clamp law is quoted in the comments there — reuse its shape: chars = (contextWindow - maxTokens - 4096) * 4 - lawChars (4 = the file's chars/4 token estimator, 4096 = its clamp margin). Then every figure in the derivation is a quotation, not a guess.
2. A shipping style/behaviour law in the repo. e.g. "two or three sentences, one breath each" → the ceiling belongs in the prompt as words the model reads ("at most three sentences; fewer if little happened"), not as sqrt(chars / 1200) in code.
3. A physical constant of the medium (speech rate, packet size), measured against the actual device. Last resort: it is still a number you must defend.

Traps when parsing that config: commented decoy lines (# contextWindow: 200,000 with a comma) must be skipped, so strip only lines whose trimmed form starts with #; the row scanner that returns on the id: line never sees the fields below it — keep scanning to the next - id:/provider key.

3. Encode the fix so the digit cannot come back

• Make the budget a required parameter of the pure module (no default: a module with no default cannot guess); the caller that resolved the endpoint does the derivation.
• A derived budget that comes out non-positive is a refusal (null, zero requests), never a truncation — the caller's cursor/queue must hold and retry.
• When an old cap must survive as a fallback for endpoints that declare nothing, rename it to what it is (INHERITED_FLOOR) and comment: floor, used only when nothing is declared.

4. Tests that pin the law, not the digit

• Size-invariance: assert the instruction/behaviour is identical for a tiny input and a huge one, proving volume no longer drives the removed ladder.
• Honours caller budget: same span folded under an injected small window.
• Refusal, not truncation: zero-window → null, zero model calls.
• DELETE tests that pinned the deleted arithmetic; never re-pin them (house rule).
• Pinning shipped prompt words is legitimate where the repo already does (prompt-contract test precedent); pinning an env/config value is a config assertion and belongs nowhere.

5. Report

Table first, verdict per number, and the net list of digits that remain after the change — each with its quoted source. If any digit survives with no source, that is the finding.