From 41e1955acef153363bbe47bba8a27c9be2708703 Mon Sep 17 00:00:00 2001 From: Hypatia May Date: Mon, 6 Jul 2026 16:31:18 +0800 Subject: [PATCH] Clarify condensing in doc budget guidance --- AGENTS.md | 2 +- docs/AGENTS.md | 2 +- scripts/doc-budgets.manifest.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ffe026144e..0fbc56a646 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -115,7 +115,7 @@ Docs are part of every change: code changes update their README and JSDoc in the ## Editing these instructions -`AGENTS.md` is the real file; `CLAUDE.md` is a symlink to it (root, `packages/`, `examples/`). Edit `AGENTS.md`, never the symlink. This file is budget-gated (`verify-doc-budgets`): needed additions may justify a ceiling raise; stale manifest ceilings are bugs. +`AGENTS.md` is the real file; `CLAUDE.md` is a symlink to it (root, `packages/`, `examples/`). Edit `AGENTS.md`, never the symlink. This file is budget-gated (`verify-doc-budgets`): condense first if it is possible without sacrificing clarity; truly needed additions may justify a ceiling raise. ## Vendoring policy diff --git a/docs/AGENTS.md b/docs/AGENTS.md index b1244c7fae..72d879bc69 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -37,7 +37,7 @@ Placement test: a story about a bug → postmortem. Why we chose X → RFC. How Standing docs accrete: every PR has a lesson it wants to append, and without displacement pressure nothing ever leaves. The gate is that pressure. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) lists the accretion-prone standing docs with a word ceiling each; `pnpm run verify-doc-budgets` (part of `doc-sync`, so CI and pre-push run it) fails when a doc exceeds its ceiling, and fails when a budgeted file is missing so a rename cannot orphan its budget. - Ceilings are an enforcement frontier with working headroom: a ceiling sits at least 5% above the doc's current size — routine edits pass, real growth trips the gate — and ratchets down, keeping the margin, as the doc reaches target. Target budgets: root `AGENTS.md` ≤ 1,500 words; `architecture.md` ≤ 1,800; each subtree `AGENTS.md` ≤ 600, except this file (which carries the standard) ≤ 1,250; `packages/README.md` ≤ 600. -- When the gate goes red, first ask whether the added words belong in this tier. If not, relocate or condense per the taxonomy above. If they do, raise the ceiling and justify the manifest diff in the PR; do not compress needed standing guidance to satisfy a stale number. A ceiling set too low is a budget bug, and correcting it is the fix. +- When the gate goes red, first ask whether the added words belong in this tier and whether the existing wording can be condensed. If the words do not belong, relocate per the taxonomy above; if they belong but can be shorter, condense. If they truly need the space, raise the ceiling and justify the manifest diff in the PR. A ceiling set too low is a budget bug, and correcting it is the fix. - Unbudgeted tiers (package READMEs, RFCs, reference matrices) have no ceiling — length is legitimate there when every row is a fact. Review and the slop checklist govern them instead. ## The slop checklist diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index b43f5fa8fc..353a3acd28 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,5 +1,5 @@ { - "AGENTS.md": 1575, + "AGENTS.md": 1660, "docs/AGENTS.md": 1315, "docs/architecture.md": 1630, "docs/cordis-primer.md": 550,