Tzurot Doc Audit

Documentation Audit Procedure

Invoke with /tzurot-doc-audit to audit documentation freshness across the project.

Run this periodically (e.g., after adding new tools, after major refactors) to ensure docs stay accurate.

Standards live in .claude/rules/07-documentation.md. This skill is the verification procedure.

Quick Scan

Fast triage before a full audit:

# What docs exist?
find docs/ -name '*.md' | sort

# Recent changes (last 30 days)?
git log --since="30 days ago" --name-only --pretty=format: -- docs/ | sort -u | grep .

# Proposals that might be stale?
ls docs/proposals/active/

# Skills lastUpdated dates
grep -r 'lastUpdated' .claude/skills/*/SKILL.md

Audit Checklist

Work through each section. For each item, verify accuracy and fix inline or note for follow-up.

1. docs/README.md Index

• Files listed under "Active proposals" match actual docs/proposals/active/ contents
• Files listed under "Backlog proposals" are a representative subset of docs/proposals/backlog/
• Quick Links point to files that exist
• Reference subdirectory table matches actual subdirectories
• Root-level documentation section references correct filenames

2. Rules Files (.claude/rules/)

How to verify 05-tooling.md:

pnpm ops --help          # Compare available commands vs documented ones
pnpm quality --help      # Verify quality script description

3. Skill Files (.claude/skills/)

For each skill:

• lastUpdated date is recent (within 30 days of last relevant code change)
• Procedures still work as written
• Referenced files/paths still exist
• Commands produce expected output

ls .claude/skills/*/SKILL.md

4. Reference Docs by Subdirectory

5. Proposals Lifecycle

• All proposals/active/ items are actually being worked on (check BACKLOG.md)
• No completed features still have active proposals (should be deleted)
• Backlog proposals still relevant (not implemented, not abandoned)

6. Research Notes

• Files in docs/research/ are TL;DR format (2-5KB, not raw transcripts)
• No raw AI chat dumps (distill or delete)
• Research links to actionable items in BACKLOG.md or proposals

7. Migration Docs

• Active migrations in docs/migration/ are still in progress
• Completed migrations deleted (feature documented in reference instead)
• Migration steps still reference correct tools/schemas

8. Incidents

• docs/incidents/PROJECT_POSTMORTEMS.md entries match CLAUDE.md post-mortem table
• Recent incidents are documented
• Lessons learned are captured in relevant rules

9. Other Docs

10. Root README.md

• Project structure lists all services in services/ and all packages in packages/
• Architecture diagram matches actual services and external APIs
• Slash commands list matches actual commands in services/bot-client/src/commands/
• External APIs section lists all current providers (OpenRouter, ElevenLabs, etc.)
• Quick Start prerequisites are current (Node version, tools)
• Documentation links point to files that exist
• Planned features section is accurate (none secretly implemented)
• Feature list reflects current capabilities (voice, TTS, etc.)

11. Root CLAUDE.md

• All rules listed in Key Rules section (check ls .claude/rules/)
• Rules descriptions match actual rule file contents
• pnpm quality description matches root package.json script
• Post-mortem table includes recent incidents
• Project structure is accurate

12. Broken Internal References

Verify docs don't reference files that have been renamed or removed:

# Check for references to deprecated root tracking files
grep -r 'CURRENT_WORK\|ROADMAP' docs/ .claude/ --include='*.md' -l

# Canonical names: CURRENT.md, BACKLOG.md
# Any hits for CURRENT_WORK.md or ROADMAP.md are stale and must be updated

• No references to CURRENT_WORK.md (renamed to CURRENT.md)
• No references to ROADMAP.md (renamed to BACKLOG.md)
• Spot-check that linked .md files in docs actually exist

13. Cross-Reference Checks

These catch drift between docs and code:

After Audit

1. Fix issues found inline during the audit
2. Update lastUpdated on any modified skill files
3. Note any larger doc rewrites needed in BACKLOG.md Inbox
4. Commit documentation fixes: docs: audit and refresh documentation

References

• Documentation standards: .claude/rules/07-documentation.md
• Documentation philosophy: docs/reference/DOCUMENTATION_PHILOSOPHY.md
• Session docs skill: .claude/skills/tzurot-docs/SKILL.md

Converted and distributed by TomeVault — claim your Tome and manage your conversions.