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

Rule	Do	Don't
No counts in prose	"See the skills catalog for the current list"	"the AI assistant has 109 skills"
Counts in tables OK	Tables with `	Count
Single source of truth	One canonical location per metric	Same count in 5 files
Link, don't copy	"See brain-health-grid for current list"	Duplicate the list inline
Timestamp proximity	Counts near a "Last Updated" date are acceptable	Undated counts

Canonical Sources

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

Metric	Canonical Source	Why
Skill count	.github/skills/ directory count (or generated catalog if present)	Filesystem is truth
Instruction count	.github/instructions/ directory listing	Filesystem is truth
Prompt count	.github/prompts/ directory listing	Filesystem is truth
Agent count	.github/agents/ directory listing	Filesystem is truth
Muscle count	.github/muscles/ directory listing	Filesystem is truth
Command count	package.json contributes.commands (if applicable)	Code is truth
Connection count	Brain QA validation output	Validated at runtime

Acceptable Count Locations

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

File	Purpose	Update Cadence
copilot-instructions.md Memory Stores table	AI working context	Per release
README.md architecture tree	User-facing overview	Per release

All other files should use descriptive references instead of counts.

Document Freshness

Staleness Indicators

Signal	Action
Count doesn't match filesystem	Fix count or replace with reference
"Last Updated" older than 30 days on living doc	Review for accuracy
Version number doesn't match current release	Update or archive
References to removed/renamed files	Fix or remove reference

Living vs Historical Documents

Type	Examples	Count Policy
Living	README, copilot-instructions, ROADMAP, USER-MANUAL	Minimize counts; keep current
Historical	Research papers, competitive analyses, archived docs	Counts are snapshots — leave as-is
Generated	brain-health-grid output	Counts are output of audit — OK

Docs-as-Architecture

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

Code Concept	Docs Equivalent
Broken import	Broken cross-reference link
Stale dependency	Stale count or version number
Orphan module	File not linked from any index
Circular dependency	Two files claiming to be source of truth
Dead code	Archived content still linked from living docs

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

Link Integrity

Rules

Rule	Enforcement
Every markdown link in living docs must resolve	Grep + verify during audit
Every important file in a folder should be linked from its README.md	Orphan check
Moving a file requires updating ALL references in the same commit	Grep for filename in all .md files before moving
Archived docs removed from active indexes	Don't link to archive/ from living docs
Use relative paths within doc trees	./architecture/FILE.md not absolute paths

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