Doc Hygiene

Documentation 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.

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