Doc Hygiene

Doc Hygiene

Prevent documentation drift through structural rules — not manual vigilance.

The Count Problem

Hardcoded counts (e.g., "109 skills", "28 instructions", "6 agents") in prose become stale within days during active development. Every count is a future bug.

Rules

Canonical Sources

The filesystem is always the source of truth. Derive counts from directories, not from prose.

Acceptable Count Locations

Counts are tolerated (not encouraged) in these specific locations because they serve as dashboards:

All other files should use descriptive references instead of counts.

Document Freshness

Staleness Indicators

Living vs Historical Documents

Docs-as-Architecture

Documentation in a cognitive architecture IS architecture. Apply the same engineering rigor to docs that you would to code:

Principle: If a doc change would break another doc's accuracy, it's a breaking change. Treat it as such.

Code Documentation Ladder

Put each claim at the narrowest layer that can own it without duplication. Comments explain why and invariants; broader documents explain use, contracts, history, or decisions.

Rules

Do not narrate what each line does. Explain the constraint a future maintainer might otherwise remove, the consequence of violating it, and the evidence that protects it.

Anti-Patterns

Link Integrity

Rules

Link Integrity Checker

# Find all markdown links and verify they resolve
find . -name "*.md" -exec grep -oP '\[.*?\]\((?!http)[^)]+\)' {} + | while read match; do
  file=$(echo "$match" | sed -E 's/.*\(([^)]+)\).*/\1/')
  dir=$(dirname "$match" | cut -d: -f1)
  target="$dir/$file"
  if [ ! -f "$target" ] && [ ! -d "$target" ]; then
    echo "BROKEN: $match"
  fi
done

// Programmatic link integrity check
import { glob } from 'glob';
import { readFile } from 'fs/promises';
import { dirname, resolve, existsSync } from 'path';

async function checkLinkIntegrity(docsRoot: string): Promise<string[]> {
  const broken: string[] = [];
  const mdFiles = await glob(`${docsRoot}/**/*.md`);

  for (const file of mdFiles) {
    const content = await readFile(file, 'utf-8');
    const linkRegex = /\[.*?\]\((?!http)([^)]+)\)/g;
    let match;

    while ((match = linkRegex.exec(content)) !== null) {
      const linkPath = match[1].split('#')[0]; // Remove anchors
      const absolutePath = resolve(dirname(file), linkPath);

      if (!existsSync(absolutePath)) {
        broken.push(`${file}: ${match[0]} -> ${absolutePath}`);
      }
    }
  }

  return broken;
}

Orphan Detection

A file is orphaned if it exists in a doc folder but is not referenced by any index or parent document. Orphans are either:

• Forgotten knowledge → add to appropriate index
• Stale artifacts → archive or delete

Repo-Wide Purpose Audit

When the question is "does every file in this repo have a purpose?" (not "is this doc folder tidy?"), file-by-file inspection at hundreds of files burns context without changing outcomes. Probe structural signals instead:

The yield is decision buckets, not a per-file list. Surface the buckets and let the user pick — single-pass deletion at this scale is high-blast-radius.

Would Revise If

Revise if the anti-drift rules let stale counts ship to released artifacts twice in a quarter, or if the 'living vs historical' classification produces disputes the rules cannot resolve.

By 2026-11-07, revise the code-documentation ladder if two reviews still find stale mechanism comments, two projects duplicate one claim across three or more layers, or a recurring documentation artifact cannot be classified by the ladder.