deepseek-harness/.agents/skills/dsh-doc-standards/SKILL.md

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. This workflow covers Markdown, JSDoc, and code comments; use judgment rather than treating length alone as a defect.

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, how to file it, and what goes inside one (the header block, per-lifecycle skeleton, and Alternatives-considered mandate, gated by verify-rfc-format); 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:

1. 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.
2. Hunt narrated history: rg -n -g '!vendor' "no longer|used to|previously|was moved|renamed" --glob '*.md' --glob '*.ts' and keep only contrasts against a live alternative.
3. Inspect long comments for reasoning transcripts: control-flow narration, test walkthroughs, proof of obvious branches, review findings, and rejected local alternatives. Preserve only a non-obvious contract or durable rationale; otherwise delete the comment.
4. Hunt duplication by grepping distinctive phrases. Keep one home and replace other copies with links.
5. Replace hand-written catalog or JSDoc restatements with links to generated references.
6. In implemented/ RFCs, remove migration plans, test checklists, and future-tense spec language; keep the decision, rationale, and shipped constraints.
7. If removing prose changes a promised behavior rather than its explanation, use a proposed RFC first (follow dsh-find-simplifications).

Keep every load-bearing rule, preferably as one to three lines plus a link to its rationale. Cut stories, duplicates, status notes, and the path used to derive the rule. Do not create a new explanation merely to relocate disposable reasoning.

When verify-doc-budgets goes red

Apply the ordered relocate-condense-raise policy in docs/AGENTS.md; this skill only supplies the workflow probes above.

Validation and PR hygiene

Run at least pnpm run doc-sync, pnpm run lint, and git diff --check; JSDoc changes may regenerate catalogs. If a paired doc changed, follow dsh-translate-docs and run pnpm run verify-translation-pairing --write. The PR body should give word deltas, explain any deliberately long exception, and list checks.