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

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

Consolidation Protocol

When reorganizing documentation:

1. Plan the target structure — Define subdirectories by audience/purpose
2. Grep before moving — Find ALL references to files being moved
3. Move + update in one operation — Never leave broken references, even briefly
4. Verify post-move — Re-run link integrity check after consolidation
5. Update indexes — All README.md index files must reflect the new structure

Standard Directory Structure

Adapt this pattern to your project. The key is audience-separated folders:

Multi-Audience Awareness

Different documentation serves different readers. Misplacing content wastes everyone's time.

Rule: Before writing, ask "Who reads this?" and place it accordingly.

Multi-Layer Documentation Strategy

Complex topics benefit from layered depth:

Not every topic needs all four layers, but important architecture should have at least summary + detail.

Timing: Ship First, Document After

Skills and patterns written after successful real-world delivery are worth 10x those written from theory. The recommended flow:

1. Build it — Get the feature working
2. Ship it — Validate in real usage
3. Document it — Capture battle-tested knowledge while fresh
4. Never skip step 3 — Undocumented shipped work is invisible work

Exception: Architecture Decision Records (ADRs) should be written BEFORE implementation.

Drift Detection During Meditation

Meditation and dream sessions are natural checkpoints for doc freshness:

Doc Audit Checklist

When reviewing documentation after development work:

1. Search for changed metrics — Did we add/remove skills, instructions, agents, commands?
2. Grep for stale counts — \b{old_count}\b across all .md files
3. Check canonical sources — Do dashboards match filesystem?
4. Verify cross-references — Do links point to files that still exist?
5. Timestamp check — Are "Last Updated" dates current on living docs?
6. Orphan check — Are there files in doc folders not linked from any index?
7. Audience check — Is each doc in the right directory for its audience?

CHANGELOG Best Practices

Preflight Validation

For release scripts or CI, automated count checks can catch drift early:

# Example: Verify skill count in copilot-instructions matches filesystem
$actual = (Get-ChildItem .github/skills -Directory).Count
$documented = [regex]::Match((Get-Content .github/copilot-instructions.md -Raw), '(\d+) skills').Groups[1].Value
if ($actual -ne $documented) { Write-Warning "Skill count drift: $actual actual vs $documented documented" }

Integrate similar checks into your project's QA or pre-publish scripts.