From c60eb878601f54ee5a9d32496c7e2237a49643b0 Mon Sep 17 00:00:00 2001 From: Turtle Date: Fri, 10 Jul 2026 00:20:35 +0800 Subject: [PATCH] make wordcount budget guidance clearer and dedup docs --- .agents/skills/dsh-doc-standards/SKILL.md | 4 +--- docs/AGENTS.md | 12 ++++++++---- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.agents/skills/dsh-doc-standards/SKILL.md b/.agents/skills/dsh-doc-standards/SKILL.md index 7c396ed93c..de7eda4142 100644 --- a/.agents/skills/dsh-doc-standards/SKILL.md +++ b/.agents/skills/dsh-doc-standards/SKILL.md @@ -38,9 +38,7 @@ Compression discipline: every load-bearing rule survives — as one to three lin ## When verify-doc-budgets goes red -1. Relocate: does the new content belong in a linked home (RFC, postmortem, cookbook, README) with a one-line pointer left behind? -2. Condense: can existing prose in the doc pay for the addition — a story compressed to its rule, a duplicate converted to a link? -3. Only then raise the ceiling: edit `scripts/doc-budgets.manifest.json` and justify the raise explicitly in the PR description. After any rewrite that shrinks a budgeted doc, ratchet its ceiling down to the new size plus working headroom (at least 5%) in the same PR. +Apply the ordered relocate-condense-raise policy in [docs/AGENTS.md](../../../docs/AGENTS.md); this skill only supplies the workflow probes above. ## Validation and PR hygiene diff --git a/docs/AGENTS.md b/docs/AGENTS.md index a6e3c7236c..6824c71cc6 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -35,11 +35,15 @@ Placement test: a story about a bug → postmortem. Why we chose X → RFC. How ## Wordcount Budgets -Every PR has a lesson it wants to append, and without pressure nothing ever leaves. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) is the pressure: it stores the allowed word-count ceiling for each budgeted standing doc; `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. +Every PR has a lesson it wants to append, and without pressure nothing leaves. [scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) stores the allowed word-count ceiling for each budgeted standing doc; `pnpm run verify-doc-budgets` fails when a doc exceeds its ceiling or a budgeted file is missing. -- 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 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. +When the gate goes red: + +1. **Relocate** content that belongs in another tier; leave a one-line link if needed. +2. **Condense** content that belongs here but can be shorter. +3. **Raise** the ceiling only when the words truly need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug. + +Ceilings keep working headroom: at least 5% above the current size, ratcheted down after trims. Target budgets: root `AGENTS.md` ≤ 1,500 words; `architecture.md` ≤ 1,800; each subtree `AGENTS.md` ≤ 600, except this file ≤ 1,250; `packages/README.md` ≤ 600. Unbudgeted tiers (package READMEs, RFCs, reference matrices) have no ceiling; review and the slop checklist govern them. ## The slop checklist