Documentation Standards

Documentation Standards

Purpose: Defines the non-negotiable standards for code comments, docstrings, and global artifacts.

1. Red Flags (Anti-Rationalization)

STOP if you are thinking:

• "I'll add comments later" -> WRONG. Undocumented code is technical debt from the moment it is written.
• "The code is self-documenting" -> WRONG. Code explains how; comments explain why.
• "Artifacts are optional, I can skip them entirely" -> WRONG. Artifacts are part of delivery quality; .AGENTS.md must follow project memory policy.
• "I'll put the full explanation in the table cell" -> WRONG. A table is a scanning device. Prose inside a cell destroys scanning and makes every row of that table churn on any edit. Cell = label; explanation goes below the table.
• "It's all one topic, so it's one paragraph" -> WRONG. Topic is not structure. A reader needs entry points: paragraphs, lists, headings. A 30-line block has none.
• "Line length doesn't matter, editors soft-wrap" -> WRONG. git diff and review comments are line-granular. A 2000-character line means a one-word fix shows up as a whole-paragraph rewrite, and reviewers stop reading.

2. Docstrings & JSDoc

All classes and functions MUST have documentation.

Python

Use Google-style docstrings.

[!TIP] See assets/templates/python_docstring.py for the format.

JavaScript / TypeScript

Use JSDoc standards.

[!TIP] See assets/templates/jsdoc_template.ts for the format.

3. Comments

• Why vs What: Explain the reason for logic, not the syntax.
• Work Tracking: Use # T O D O: (Python) or // T O D O: (JS/TS) for future work.

4. Path & Reference Standards (CRITICAL)

• Relative Paths Only: When linking to internal files in Artifacts (PLAN.md, TASK.md), ALWAYS use relative paths.
  • ✅ [Ref](src/main.py)
  • ✅ [.agent/skills/core.md](.agent/skills/core.md)
  • ❌ file:///Users/username/project/src/main.py
  • ❌ /Absolute/System/Path

4.1. Positional references are verified LAST

A reference is positional when it points at where something sits rather than what it is called: a line number, a byte offset, an item number in a numbered list, a section ordinal. A reference is nominal when it names the thing: a symbol, a function, a heading, an anchor.

RULE: If one task changes both an artifact and a document that references that artifact positionally, the positional references are checked after the artifact edits are final — never before. A quotation of the pre-edit state MUST carry an explicit revision identifier (commit, tag, version), otherwise it reads as a claim about the current state.

Why this is a rule and not a tip. The failure is silent and self-confirming: the author did verify the references — just before shifting them, so the check passed. The document then asserts "verified" while pointing at a line that has moved and quoting a sentence the same task deleted. Nothing fails; only a later reader or an adversarial review finds it.

Where it bites most: decision records (ADR/RFC) that both settle a question and update the comments which referenced that question as open. That is the ordinary shape of such a task, not an edge case.

Prefer nominal over positional wherever the target has a name. A reference to a symbol survives an inserted line; a reference to line 112 does not.

A coordinate carries its referent.

RULE: In a living corpus an unpinned path:line reference carries a referent — an observation that survives a shift, written as a code span immediately after the reference. Two spellings: a symbol name that appears on the cited line, or an exact substring of it. A reference without one is not examined — never an error, never a warning.

`packages/core/src/adapters/registry.ts:1083`, `if (deadlineHit || Date.now() >= deadline) {`
`packages/core/src/capability-manifest.ts:165` `CapabilityManifest`

Why the rule is not "verify more carefully". §4.1's ordering rule — positional references verified LAST — is unfollowable for the document that needs it most. A PLAN is dense with coordinates and the pipeline requires it to be written FIRST, before the Development phase edits the files it cites. Measured in one consumer repository: 85 of 142 attributable references were written by the Analysis, Architecture and Planning phases, and one cited file grew 950 → 1560 lines after those coordinates were recorded. A referent makes the number recomputable, so the ordering rule stops being a thing to remember.

Why not an error. An unreferenced coordinate is unverifiable, not wrong. Measured across the 17 repositories carrying .agent/skills/: 11 hold no path:line reference at all, and the living corpora hold 324. Grading the absence an error would turn correct documents red in projects that adopted nothing — and a gate that fails correct documents is switched off (§4.2). Adoption is per-project and incremental; the coverage line states how much of a corpus is verified.

Two objects, two words. A referent identifies what a coordinate points at. An anchor (§4.3) addresses a section of a document. They are not interchangeable, and no rule here licenses using one name for the other.

The bound. A referent proves the quoted text is present. It does not prove the sentence about it is true: a document calling a cache-warming comment "the narrowing of matching routes" passes if it quotes that comment. Only reading closes that.

Pinning a deliberate quotation. A pinned reference is a claim about that revision and is exempt from re-checking; an unpinned one claims the current state, which is what makes the check decidable at all. Two forms:

The backticks are what make it language-independent, not the surrounding words: they mark the token as an identifier rather than prose, which no list of prepositions can do across languages. An unmarked hex run is a CSS colour, a build id or a digest far more often than a revision, and an unmarked version is usually the subject of the sentence ("bump to v3.4") — so those pin only after an English cue.

HEAD is matched case-sensitively on purpose. Lower-case "head" is an ordinary English word, and honouring it would exempt every line containing "the head of the list".

A prose pin applies only when the line carries exactly one reference — path:line and § ordinals counted together — because prose cannot say which reference it qualifies. Prefer @<rev>: it is per-reference, unambiguous, and language-neutral.

Concrete verification differs per ecosystem and does not belong in the rule:

4.2. Reference resolver (advisory)

scripts/check_positional_refs.py implements the scriptable row above. It is advisory and diff-scoped, not a gate, for a reason worth keeping: a survey of this repository's archived reviews found 54 of 84 resolvable references pointing into files edited after the citing document was written — and nearly all of them are correct records of the state at the time. A gate scoped that widely would fail on correct documents, which is how gates get switched off.

python3 .agent/skills/documentation-standards/scripts/check_positional_refs.py   # current change
python3 .agent/skills/documentation-standards/scripts/check_positional_refs.py --base main

What the referent layer changes about the advisory verdict above. The 54-of-84 measurement was taken over archived reviews, and it stays as written: those references are correct records of their time, and a repository-wide gate over them still fails correct documents. What the referent adds is a population where the tool has direct evidence instead of suspicion — so the verdict splits by corpus rather than being one rule:

REFERENT_ABSENT is an error rather than a warning on purpose: it is the one verdict the tool cannot settle, so grading it a warning would put the only case needing judgement in the class readers skip. REFERENT_MOVED is an error too — the document asserts a wrong number until repaired — but needs no judgement at all, which is what --fix is for.

Two invocations, not one. The check never writes. --fix is a separate run that rewrites the line number of a REFERENT_MOVED reference and never a referent: the referent is the claim, the number is derived from it. Pair them as format:check / format — the check in CI, the fix in a pre-commit hook, so the commit that shifts the code corrects the coordinates it shifted.

python3 .agent/skills/documentation-standards/scripts/check_positional_refs.py --targets-changed
python3 .agent/skills/documentation-standards/scripts/check_positional_refs.py --targets-changed --fix

--targets-changed selects documents citing a file the change touched. Default diff scope selects documents the change edited, so a commit touching only sources scans nothing — while being exactly the commit that shifts the cited lines.

Only DRIFT_SUSPECT needs judgement: the tool prints the target line back, and the reviewer confirms it still says what the document claims. Pinned references are skipped entirely.

Section ordinals are positional too, and the tool checks the slice it can check honestly: an ordinal whose target is named next to it — a skill name, a repo path, or a markdown link (`developer-guidelines` §1.5). Both numbered headings and numbered list items count as declarations, because references such as 01_orchestrator.md §1.3 address a list item. Ranges (§1–§3) expand; external specs (CommonMark, OWASP) and other repositories are excluded.

[!NOTE] Known limits, stated because a green run must not overclaim.

1. Only changed documents are scanned. A change that edits only source, shifting lines under an untouched older document, is out of scope — the archived-document case above, where a warning would be noise rather than signal.
2. A bare ordinal (see §4.2, TASK §4) is never checked. Its antecedent lives in prose, and guessing one manufactures false failures. In this repository that is roughly three quarters of all ordinals.
3. A target that numbers no headings at all — an ADR whose headings read ## D1 — Decision — makes its inbound ordinals unverifiable, not wrong; they are skipped.

Limits 2 and 3 are not left to this document. Every run that meets a § at all prints how many ordinals it checked (passed and failed separately), how many it skipped with the reason, and how many it never examined — so a green report cannot be read as covering references it never looked at. Pinned path:line references are excluded from the "resolve" count for the same reason.

Prefer the nominal form where a document offers one: [Section 5](#5-claudemd-specification) survives renumbering because the anchor, not the number, carries the meaning.

4.3. Structural anchors — a machine addresses a section by anchor, never by prose

§4.1 sorts references into positional (where a thing sits) and nominal (what it is called), and prefers nominal. That is right and incomplete: a nominal reference can still break, because it names its target in a language. Three rungs, not two:

RULE: A human may address a section at any rung. A machine gate addresses an authored document at the anchor rung. A gate that matches a heading's words, or a table's column names, is asserting that the document is written in a particular language — an assertion nobody made and the gate cannot check.

Why this is a rule and not a tip. Both failure modes are silent in the way that matters. The loud one — the gate exits non-zero on a perfectly good document — pushes the author to write in a language they do not use, or to stop running the step; and a step that can be quietly skipped is distinguishable from a passed one only by someone eventually looking. The quiet one is worse: a non-latin slug that normalizes to "untitled" makes two different documents resolve to one filename, and reports nothing.

This framework had already reached the conclusion once, for one file — known-issues-format inserts at a comment anchor "because headings get renumbered and retitled" — and did not generalize it. By the time it was generalized there were three independent instances of the same defect, only one of which anyone had filed.

Syntax. An HTML comment alone on its line, directly above the section heading or block it names, followed by a blank line:

<!-- contract:rtm -->

## 1. Requirements Traceability Matrix (RTM)

<name> is lowercase ASCII kebab-case. The comment is invisible in every Markdown renderer, so the prose heading stays exactly as the author wrote it — the two audiences stop competing for one string.

Lookup semantics (binding on every gate that reads an anchor):

Compatibility. Anchors are emitted on write, optional on read. Every gate keeps its old matcher as the fallback branch, so documents written before the anchor existed — archived artifacts, which doctrine forbids editing, and every downstream project's corpus — behave byte-identically. An anchor is never required by a gate; requiring one would break the corpus it governs, which is the failure skill-spec-validator already survived once.

Registry. Reserved anchors live in §4.4. No gate may key on an unregistered anchor. The converse is deliberately permitted: an anchor may be registered and emitted before any reader exists, for the required sections of pipeline artifacts (§4.4), so that the next gate is language-independent by construction instead of by remembering this rule.

4.4. Reserved anchor registry

— in Consumer means: emitted by the template, no reader yet, reserved so a future gate has a structural target. Adding a row is how a new anchor is introduced; adding a gate that reads an anchor absent from this table is a defect.

[!NOTE] feedback:discovered-issues keeps its own namespace: it marks an insertion point for a writer, not a contract block for a reader, and it predates this registry. Renaming it would rewrite live ledgers in every consumer project to no benefit.

5. Markdown Structure (CRITICAL)

Applies to every .md artifact: TASK, PLAN, ARCHITECTURE, task files, issues, .AGENTS.md. These rules are formatter-independent — they hold whether or not the project runs Prettier, markdownlint, or nothing at all. A formatter only makes a violation visible sooner; it is not the reason the rule exists.

5.1. Table cells are labels, not prose

A cell holds one short value: an id, a status, a link, or a single clause.

• Hard limit: ≤ 120 characters and one sentence per cell.

• Never put inside a cell: <br/>, a bulleted list, a multi-sentence explanation, a code block, or a nested table.

• Need more? The cell keeps a short marker, and the detail moves to a section below, keyed by the same id:

  | ID   | Requirement             | MVP? |
  | ---- | ----------------------- | ---- |
  | R-29 | Adapter `nansen` (REST) | Yes  |
  
  ### Details by ID
  
  **R-29** — Adapter `nansen` (REST)
  
  - Host `api.nansen.ai` in the adapter's own allowlist (per-adapter SSRF).
  - Auth header is literally `apiKey: <KEY>`, not `Authorization: Bearer`.
  

Why, with a formatter: every table formatter pads each column to its widest cell. One 2000-character cell therefore rewrites every row of that table — a one-cell edit lands in review as a twenty-line diff that hides the actual change.

Why, without a formatter: it is worse. Nothing re-aligns the pipes, so the columns stop lining up entirely and the table is no longer a table in raw form — which is how it is read in git diff, in a terminal, and in any editor without Markdown preview.

Why, in both cases: wide tables scroll horizontally. A reader cannot compare rows they cannot see side by side, which is the only reason to use a table instead of a list.

[!TIP] If a column's content does not fit the limit for most rows, that column should not be a column. Convert the table to a definition list (ID — value + bullets).

5.2. Prose is structured, never a wall

• Paragraph ≤ 5 lines. Longer means a missing break or a missing list.
• ≥ 3 parallel items → a list. If you are writing "first… second… third…", or a sentence carrying three or more comma-separated conditions, it is a list.
• List nesting ≤ 2 levels. Deeper means the section needs sub-headings instead.
• Section > 40 lines → sub-headings. A reader must be able to jump, not scan linearly.
• A list item that grows past ~3 lines becomes its own paragraph under a bold lead-in.

5.3. Line length

• Hard-wrap prose at 100 characters (match the project's printWidth where one exists).
• Do not rely on editor soft-wrap: diffs, review comments and blame are line-granular.
• Exempt: URLs, tables, code blocks — never break those to satisfy the limit.

5.4. Self-check before delivering any .md

# widest line + how many exceed the limit
awk '{n=length($0); if(n>100)c++; if(n>m)m=n} END {print "widest="m, ">100ch="c+0}' FILE.md
# alignment padding as a share of the file — over ~15% means prose is stuck in table cells
python3 -c "import re,sys;s=open(sys.argv[1]).read();p=sum(len(m) for m in re.findall(r'  +',s));print(f'padding {100*p/len(s):.0f}%')" FILE.md

5.5. Register — how the prose reads

Applies to authored prose in whatever language the project writes. This section constrains how a sentence reads, never which language it is written in (ARCHITECTURE §7.3, invariant L2).

Register is decided while writing, not after. Load artifact-formalizer/references/authoring-contract.md before the first sentence of any TASK, ARCHITECTURE, PLAN or task file. It carries the six per-sentence tests and the licensed statement forms. The scanner below measures whether that contract held; it is not the contract.

• 1 — over 35 words is the failure bound, not the target; every corpus mean is 5.8–15.4 words.
• 2 — a word asserting a judgment the reader cannot check: obviously, robust, наивный.
• 3 — the requirement states what must hold; justification goes under **Why.** or into Notes.
• 4 — no maxim or personification standing in for a norm.
• 5 — 🔴 is not a severity. warn, SEV-2, Critical are.
• 6 — established terminology stays verbatim; a metaphor coined for one document does not.

A partial detector is not a pass. Rules 3, 4 and 6 ship with declared recall limits, and the reading pass owns the remainder — a coined metaphor is indistinguishable from a term until you check where else it occurs. --terms docs/ARCHITECTURE.md runs the string half of that check. Read the scanner's DETECTORS and DIAGNOSTICS blocks before its findings: a zero from a dead detector is not a measurement, and a corpus whose longest sentence equals the limit was written for the gate.

Thresholds are measured, not chosen. 35 words sits far above every corpus mean (5.8 oldest, 14.1–15.4 newest) and catches the ~3.7% tail both newest corpora grew. A failing scan is resolved in the prose; moving a threshold to obtain a green scan inverts the rule.

Advisory by construction. The scanner reports and never fails a phase, for the reason §4 gives: a gate that fails on correct documents is how gates get switched off. Its non-advisory exits are a dead detector (2) and a usage error (3) — a broken instrument and a mistyped command, neither a verdict on the document.

This section owns register only. Cell width and cells-as-prose → §5.1 (the scanner surfaces both as cell_width and cell_sentences). Paragraph and list shape → §5.2. Line length → §5.3.

[!TIP] Authoring contract, rewrite guide, per-language marker data and the scanner: artifact-formalizer.

6. Artifacts (.AGENTS.md)

Policy: keep .AGENTS.md for source-code directories under memory tracking. Missing file should not fail execution; bootstrap when needed.

[!TIP] Use the template at assets/templates/agents_md_template.md.

Rationalization Table

7. Execution Policy

7.1. Execution Mode

• Mode: hybrid
• Rationale: the documentation standards themselves are prompt-driven judgement, while positional-reference resolution (§4.2) is mechanical and therefore script-driven.

7.2. Script Contract

• Primary Command: python3 scripts/check_positional_refs.py [--root DIR] [--base REV]
• Inputs: repository root, revision defining the current change, optional --all [DIR ...].
• Outputs: human-readable findings, or a JSON array with --json.
• Failure Semantics: 0 no errors, 1 errors present (or any finding under --strict), 2 usage or environment problem such as a non-repository root.

7.3. Safety Boundaries

• Scope: read-only. The tool opens files and runs read-only git queries; it never writes, edits, or deletes anything in the repository.
• Default Exclusions: documents outside the current change are not scanned unless --all is passed explicitly.
• Destructive Actions: none. There is no fix or rewrite mode, deliberately — deciding whether a reference is stale or a legitimate quotation is the reviewer's judgement, not the tool's.

7.4. Validation Evidence

• Primary Evidence: tests/test_positional_refs.py — 84 tests over throwaway git repositories covering extraction, shorthand ambiguity, each finding class, language-independent pinning and its false-pin guards, ordinal parsing and denylisting, scope honesty, path containment, and every exit code. Gated in framework-gates.yml and named in tests/run_tests.py, so the suite a developer runs locally is not blind to it.
• Secondary Evidence: a diff-scoped run on the change under review, quoted in the review notes.
• Quality Gate: no error-severity findings; every DRIFT_SUSPECT explicitly confirmed.

8. Resources

• assets/templates/: Collections of templates.
• examples/good_documentation.py: Gold standard example.