doc-hygienelisted

# 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 | Rule | Do | Don't | |------|----|-------| | **No counts in prose** | "See the skills catalog for the current list" | "Alex has 109 skills" | | **Counts in tables OK** | Tables with `| Count | Value |` format are scannable and updatable | Counts buried in paragraphs | | **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 | | Command count | `package.json` `contributes.commands` (if applicable) | Code is truth | | Connection count | Brain QA