Files

T

Tianyi Cui aa36b3b36b feat(doc-standards): documentation tiers, budgets, and the ceiling gate

Standing docs accrete a paragraph per PR with nothing pushing back; the
root AGENTS.md reached 8,130 words in 50 commits with the same rule
stated two and three times. This encodes the counter-pressure:

- docs/AGENTS.md becomes the documentation standard: the tier taxonomy
  (one home per fact), target word budgets, and the slop checklist.
- verify-doc-budgets joins doc-sync: word ceilings for the six
  accretion-prone standing docs, manifest-driven, frozen at current
  sizes and ratcheted down as each doc is brought to target.
- .agents/skills/dsh-doc-standards: the thin placement/audit/red-gate
  workflow over the standard, mirroring the dsh-translate-docs split.
- RFC (implemented/process) records the decision, alternatives, and
  the first audit cycle's deferred work list.

The gate's first catch was the standard itself (1,057 > 1,000); it
ships condensed to 984 words rather than with a raised ceiling.

2026-07-04 13:53:43 +08:00

4.9 KiB

Raw Blame History

name, description

name	description
dsh-doc-standards	Use when writing, moving, reviewing, or auditing documentation in the deepseek-harness repo — choosing where content belongs, trimming doc slop, responding to a verify-doc-budgets gate failure, or requests like "improve the docs", "audit the docs for slop", "where should this be documented", "this doc is too long".

Applying the DeepSeek Harness Documentation Standard

The contract lives in docs/AGENTS.md — the tier taxonomy, the word budgets, and the slop checklist. This skill is the workflow for applying it: placing content, auditing the corpus, and handling a red budget gate. It is guidance, not a script; keep judgment active and prefer a few well-proven fixes over a mass rewording pass.

Sources of truth (read, don't re-summarize)

docs/AGENTS.md — the taxonomy ("one home per fact"), budgets, slop checklist.
docs/rfc/README.md — when a decision earns an RFC and how to file it; docs/postmortem/README.md — when an incident earns a postmortem.
docs/i18n/README.md — the bilingual pairing contract; editing either side of a pair obligates the counterpart in the same change.
Root AGENTS.md — the standing orders whose budget discipline this skill protects.

Placing content

Run the placement test in the standard's taxonomy table, then check the constraints that make a placement expensive or wrong:

Paired docs (pnpm run verify-translation-pairing --list) cost a zh counterpart update and a --write re-record on every edit — prefer an unpaired home for content that will churn.
Generated catalogs are never hand-edited; if the fact belongs there, change the generator's source.
Before renaming or moving any doc, grep for inbound references: verify-md-links catches Markdown links, verify-doc-refs catches docs/*.md citations in TypeScript comments, but nothing catches heading-anchor fragments — grep #the-heading across the repo yourself (one anchor is hardcoded in scripts/gen-cordis-catalog.ts).
A move is atomic: remove from the old home, add to the new home, and fix every inbound link in the same change.

Auditing the corpus

The audit is a hunt for the standard's slop checklist, cheapest probes first:

Measure: pnpm run verify-doc-budgets --list, then git ls-files '*.md' | grep -v '^vendor/' | xargs wc -w | sort -rn | head -30 to spot unbudgeted outliers.
Hunt narrated history: rg -n -g '!vendor' -t md "no longer|used to|previously|was moved|renamed" — judge each hit; some are legitimate (quoting a contrast against a live alternative), most are drift.
Hunt duplication: take each standing-doc rule, grep one distinctive phrase from it across all Markdown; more than one home means all but one become links.
Hunt catalog restatement: compare README event/tool tables against the generated catalogs and JSDoc; hand copies get replaced by links.
Hunt spec-speak in implemented/ RFCs: migration plans, test checklists, future-tense "should" — an implemented RFC describes what is.
Classify each finding: a mechanical trim lands as a small PR; a restructure or removal that changes what a doc promises gets a proposed RFC first (follow dsh-find-simplifications for the RFC shape).

Compression discipline: every load-bearing rule survives — as one to three lines plus a link to the home that carries its why. Cut stories, duplicates, and status annotations; never silently drop a rule. If a cut rule has no durable home to link, create it (usually an RFC or postmortem) in the same change.

When verify-doc-budgets goes red

Relocate: does the new content belong in a linked home (RFC, postmortem, cookbook, README) with a one-line pointer left behind?
Condense: can existing prose in the doc pay for the addition — a story compressed to its rule, a duplicate converted to a link?
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 modest headroom in the same PR.

Validation and PR hygiene

For docs-only changes run at least pnpm run doc-sync, pnpm run lint, and git diff --check; if a paired doc was touched, update the counterpart (see dsh-translate-docs) and re-record with pnpm run verify-translation-pairing --write. Open a draft PR while the audit is still expanding; in the PR body, list what was trimmed/moved with word deltas, what was deliberately kept long and why, and which checks ran. The first audit cycle's deferred work list lives in the doc-tiers-and-budgets RFC § Deferred work.

4.9 KiB Raw Blame History