Doc Standards

Documentation Standard

This skill carries a portable documentation standard and the workflow to apply it: placement and hierarchy, tutorial versus reference classification, writing rules, wordcount budgets, and corpus audits across Markdown, JSDoc, and code comments. It is guidance, not a script; use prose-standard for required coverage and editorial judgment, and never treat length alone as a defect.

What this skill inlines

The standard below is written into this skill so it travels: document structure, the tier taxonomy (one home per fact), writing rules, wordcount budgets, and the slop checklist. The repository's own conventions still govern where they exist and are stricter or more specific — its decision-record rules (when a decision earns a record and what goes inside one), postmortem rules (when an incident earns one), bilingual pairing rules (editing either side of a pair obligates the counterpart in the same change), and documentation gates. Frozen or archived decision records are historical snapshots excluded from editorial maintenance and evolving documentation gates.

Document structure

These rules apply to human-facing documentation; decision records remain outside their scope. A postmortem is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.

Classify every in-scope document as a tutorial or a reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.

Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.

Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.

The tier taxonomy: one home per fact

Each fact has one home: the tier whose job it is; elsewhere, link there.

Tier	Job	Does NOT belong there
Root authoring rules (for example, AGENTS.md, CLAUDE.md, or CONTRIBUTING.md at the repository root)	Standing orders: rules an agent needs in context in every session, one to three lines each, linking their home	Stories, worked examples, situational procedures, anything restated from a linked home
Subtree or package authoring rules	Orders specific to that subtree or package	Repository-wide rules the root file already carries
Architecture map	Ordered map: composition, core modules, seams, extension points; read before changing the core	Type definitions (→ subsystem pages), per-package detail (→ package READMEs), decision rationale (→ decision records), implementation-status annotations
Subsystem or area reference pages	One reference page per subsystem or area: type definitions and semantics	Behavior narration (→ architecture map)
Decision records (ADRs)	Active decision records: the why, what was given up, and required verification; implemented records describe shipped reality in present tense	Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived records are frozen history, never current authority
Postmortems	Incident stories — the only tier where war-story narrative belongs	—
Cookbook / how-to guides	Step-by-step how-tos with numbered verify steps	Design rationale (→ the decision record each guide links)
Product or user documentation	Product-facing guides	Generated reference tables, contributor procedures, decision history
Package README	The per-package contract: config, semantics, limitations, extension points	JSDoc restatement, generated-catalog restatement, other packages' concerns
Development or contributor guide	Contributor setup, daily workflow, and a summary of CI; possibly a bilingual pair under the repository's pairing rules	Runtime or version rationale (→ decision records), check-by-check lists that drift from the actual scripts
Generated reference	Exhaustive sources regenerated from source and freshness-gated; reviewed counterparts follow the pairing workflow	Hand edits to generated sources or regions; counterparts update through pairing only
Skills directory	Reusable workflows and specialized decision standards	Product and runtime contracts (→ docs or source)

Placement: bugs → postmortems; rationale → decision records; procedures → cookbooks; type definitions → subsystem pages; package contracts → READMEs; standing orders → root authoring rules with a rationale link.

Writing rules

• Document current state, not change history. Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, decision records, or postmortems; the latter two may cite merged PRs and issues as evidence.
• Every non-trivial change includes at least one decision record in the same change when the repository's decision-record rules require it. Update the owning record or add one; only mechanical or local edits are exempt.
• One physical line per paragraph: use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
• Pasted declarations must not drift. A pasted type declaration and its original JSDoc, or a body-stripped public declaration, stay in sync with the source; where the repository keeps a type-equivalence check and manifest, register the paste so the check covers it.
• The owning subsystem or area page updates in the same change that reshapes a documented type. The type-equivalence check catches drifted pastes, not never-documented new types; document a type on its declaring unit's page.
• Pairs update together. Editing either side of a paired document obligates the counterpart in the same change: update it minimally in one pass, preserve untouched prose, and re-record the pair (see translate-docs for the extended workflow, which remains user-invoked where the repository's rules say so).
• Comments and JSDoc state complete contracts, not reasoning transcripts. Preserve behavior, failure, timing, ownership, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use prose-standard for details.
• Write directly: name actors and facts. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".

Wordcount budgets

The repository's documentation-budget manifest sets ceilings for standing documents; the budget gate rejects excess or missing files.

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 need the space; justify the manifest diff in the change. A too-low ceiling is a budget bug.

Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room, and raise it when content would otherwise be deleted. Set per-document targets in the manifest (for example, a root authoring file keeps a tight ceiling while deeper references get more room); review governs unbudgeted tiers.

The slop checklist

Hunt these in any document:

• The same rule stated in more than one home. Grep a distinctive phrase; keep one home and link the rest.
• Narrated history or war stories: "previously", "now", "no longer", "used to", "renamed", "was moved", PRs, or commits. State the current fact; link a decision record or postmortem when needed.
• Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repository layout and package manifests carry it.
• Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
• Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
• Rationale repeated beside sibling methods instead of once at the owning capability or helper.
• Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
• Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
• Spec-speak in implemented decision records: "should", migration plans, acceptance checklists. An implemented decision record describes what is.

Review structure before prose

Apply the authoring order above to every human-facing document in scope. Do not apply this structural pass to decision records. Classify a postmortem as a reference scoped to one incident; preserve its required chronological evidence without treating chronology as a teaching sequence.

1. Locate the document in the repository and navigation trees. State its own subject and identify its direct children.
2. Set the permitted level of detail. Keep full detail about the document's subject, summarize direct children by purpose, responsibility, and high-level behavior, and move deeper explanations to their owning descendants with links. Treat test infrastructure as descendant-owned unless it is the document's subject.
3. Classify the document from its intended use, not its path or title. A tutorial must lead through ordered work to an observable outcome; a reference must support lookup within an explicit scope without requiring sequential reading.
4. For a tutorial, privately classify the starting reader and concepts as beginner, intermediate, or advanced. Trace each concept to its prerequisites, reorder premature material, and move optional advanced detail to a later tutorial or reference.
5. Split substantial mixed forms. Put a small secondary form in a clearly labeled section.

Then check constraints that make placement expensive or wrong:

• Paired documents cost a counterpart update and a pair re-record on every edit — prefer an unpaired home for content that will churn. When you edit either side of a pair, update the counterpart in the same change (see translate-docs).
• Generated catalogs are never hand-edited; if the fact belongs there, change the generator's source.
• Before renaming or moving any document, grep for inbound references: the repository's Markdown link check catches link targets AND #fragment anchors onto Markdown files (heading slugs and explicit <a id>), and the doc-reference check catches documentation citations in code comments; anchors cited from code strings still need a manual grep when their output never reaches gate-scanned Markdown.
• A move is atomic: remove from the old home, add to the new home, and fix every inbound link in the same change.

Audit the corpus

After the structural pass, hunt the slop checklist with the cheapest probes first. Verify and fetch the PR's live base, then identify committed and dirty paths — via the repository's scope-report tooling when it exists (a command that reports changed paths against a verified base), otherwise from git status and git diff — before applying semantic judgment. After a retarget or base merge, rerun the report and audit prose introduced by the new base.

1. Measure: list the budget gate's output, then git ls-files '*.md' ':(exclude)vendor/**' | xargs wc -w | sort -rn | head -30 to spot unbudgeted outliers.
2. Hunt reasoning-transcript leakage — narrated history, dead design-session citations, review choreography, control-flow narration, test walkthroughs — with trim-cot-leakage, which defines the taxonomy, recall batteries, and rules for what to keep or delete. Preserve only a non-obvious contract or durable rationale; the same rationale repeated beside sibling methods keeps one home.
3. Hunt duplication by grepping distinctive phrases. Keep one home and replace other copies with links.
4. Replace hand-written catalogs, test or status inventories, and JSDoc restatements with the authoritative tree, script, or generated reference.
5. In implemented decision records, remove migration plans, acceptance-task checklists, and future-tense spec language. Keep concise verification contracts that identify the behaviors and tiers pinning the shipped decision, plus named coverage gaps.
6. If removing prose changes a promised behavior rather than its explanation, use a proposed decision record first (follow find-simplifications).

Exclude frozen or archived decision records from corpus audits and edits. Active prose may repair, redirect, or delete an inbound link, but never follow an archive-wide cleanup into the frozen target.

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 the budget gate goes red

Apply the ordered relocate-condense-raise policy above; this skill only supplies the workflow probes in this document.

Validation and PR hygiene

Run at least the repository's documentation gates, lint, and git diff --check; JSDoc changes may regenerate catalogs. If a paired document changed, update the counterpart and re-record the pair per the writing rules, then run the pairing check. The PR body should give word deltas, explain any deliberately long exception, and list checks.