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/ .claude/rules/ .claude/skills/ | sort -u | grep .

# Proposals that might be stale? (project uses backlog/ — no active/ dir by design)
ls docs/proposals/backlog/

# Orphan proposals (structural check — fails CI on any unlinked proposal)
pnpm ops guard:proposal-links

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

Section 0 runs FIRST because a memory promoted into a Tzurot rule, doc, or skill changes what those sections then audit.

0. Auto-Memory Audit (run FIRST)

The shared auto-memory store (~/Documents/claude-memory, shared by every Claude session on this machine) is audited by harness:doc-audit § Step 2, not here — nothing in this skill deletes a memory file. When a memory's destination is a Tzurot rule, skill, or doc, write that destination here; the memory's own deletion is proposed to the owner through harness:doc-audit's gate.

Stamp it when done: pnpm ops cadence:mark memory-prune, then commit backlog/cadence-ledger.json to develop.

1. docs/README.md Index

• 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

Note: this project uses BACKLOG.md (root load manifest) + backlog/ (HOT now.md/active-epic.md + COLD cold/) for active work tracking, not docs/proposals/active/ — that directory does not exist by design. If you see references to it in any doc, they're stale and should be removed.

2. Rules Files (.claude/rules/)

File	Check
00-critical.md	Security rules still reflect current patterns? Post-mortem table current?
01-architecture.md	Service boundaries match dependency-cruiser rules? Anti-patterns table current?
02-code-standards.md	ESLint limits match eslint.config.js? Testing patterns current?
03-database.md	Protected indexes list current? (The cache TTL table lives in durability-tiers.md — § Existing cache implementations.)
04-discord.md	Shared utilities table lists all browse/dashboard helpers?
05-tooling.md	All pnpm ops commands listed? pnpm quality description accurate?
06-backlog.md	BACKLOG.md HOT/COLD table matches the actual backlog/ layout; granularity ladder intact? 06-backlog staleness rules intact?
07-documentation.md	Placement table covers all docs/reference/ subdirs? Lifecycle rules current?
09-interaction-style.md	Interaction guidance still reflects current feedback (no premature-stopping, etc.)?
10-working-posture.md	Each posture still names a trigger → behavior? Cross-references to rules/skills resolve?

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

Skills whose procedure is coupled to something enforced elsewhere need a deeper check than the generic list above — the coupling drifts silently:

Skill	Extra check
/tzurot-review-response	Edit-shape whitelist current? Round-cap + fixup-commit procedure matches the CI fixup-check job?

3b. Economy Pass — always-loaded surfaces (rules + CURRENT.md + skills)

Sections 2 and 3 ask is this still accurate? Nothing above asks is this earning its context cost? — so the always-loaded corpus only ever grows. Rank it, then cut from the top:

pnpm ops lines:check --breakdown   # every rules file + CURRENT.md + skill body, worst-first by bytes

Work the ranking in order and stop after the top 3. Bytes, not lines, is the order that matters: density varies several-fold across these files (the command prints each one's B/line), so a line-sorted list puts a table-heavy file above a prose-heavy one that costs more. Depth beats breadth here — three files read closely beats ten skimmed, and the ranking is stable enough that the next audit picks up where this one stopped.

The cut test — four questions per passage

A passage stays only if it survives all four. Any single "no" is a cut, and "it's true and useful" is not an answer to any of them:

1. Constraint or narrative? Does it state what to do, or recount how we found out? Incident stories, adoption dates, council-derivation notes, and "this happened twice" counts are the record of a decision, not the decision — the operationalized outcome IS the record, and git preserves the story.
2. Would a reader act differently without it? If removing the passage changes no behavior, it is costing tokens to be agreed with.
3. Is it said in more than one layer? The same thing in a rule AND a skill AND a doc is one canonical statement plus two copies that drift. Keep it at the layer that loads when it is needed (07-documentation.md), link from the others.
4. Has a gate since made it structural? A measurement, a caution, or a checklist superseded by a guard:* / ratchet / hook is enforced now — the prose is a second, weaker copy that can silently disagree with the gate.

Cut text goes nowhere. Not to a doc, not to an archive file, not to a comment — git holds it. Moving it down a layer is only right when the content is genuinely reference someone will look up on purpose; otherwise a move is a cut that didn't happen.

Who decides

This pass defaults to cutting, and the owner sees the diff. The agent proposing rule additions should not be the sole judge of what is excess, and the direction of that bias is measured, not hypothetical: the July trim bought headroom and the additions since have been spending it. So — propose the cuts as a normal review-gated PR (.claude/rules/*.md and SKILL.md both require one), one PR per pass, with each cut's question number as its justification. When a passage is genuinely contested, cut it and say so in the PR body; the owner restoring one line is cheaper than the corpus keeping ten.

Record the result

• Re-run pnpm ops lines:check --breakdown and put the before/after byte numbers in the PR body — a trim with no number is indistinguishable from a reshuffle.
• pnpm ops lines:update-baseline --surface <name> to ratchet the trimmed surface DOWN. Scope it: the unscoped write also ratchets a grown surface UP in the same commit, which is how a previous post-trim refresh got skipped entirely and the trim went unrecorded.
• Stamp the pass: pnpm ops cadence:mark economy-pass, then commit backlog/cadence-ledger.json to develop.

4. Reference Docs by Subdirectory

Subdirectory	Key checks
architecture/	ADRs reference current service names? Memory/context docs match implementation?
caching/	Pub/sub guide matches actual cache invalidation code?
database/	Prisma drift issues still relevant?
deployment/	Railway operations match current deploy process?
features/	Feature docs describe current behavior?
guides/	Development setup works? Testing guide current?
operations/	Runbooks reference correct commands/services?
standards/	Patterns still used? No deprecated approaches?
templates/	Templates produce valid output?
testing/	Test procedures reference current tools?
tooling/	OPS CLI reference matches pnpm ops --help?
Root files	STATIC_ANALYSIS.md matches CI config? CLI references current?

5. Proposals Lifecycle

• All proposals/active/ items are actually being worked on (check backlog/now.md Current Focus)
• No completed features still have active proposals (should be deleted)
• Backlog proposals still relevant (not implemented, not abandoned)
• pnpm ops guard:proposal-links is green (no orphan proposals — every docs/proposals/backlog/*.md has an inbound link from backlog/, docs/, CURRENT.md, or BACKLOG.md). This is structurally enforced in CI; running it during the doc audit catches a local drift before CI does.

6. Research Notes

Format check (a well-formatted doc can still be obsolete — do the relevance check below too):

• 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
• docs/research/README.md index lists exactly the files present (no phantom rows, no missing files, descriptions not stale)

Relevance / lifecycle check (guards against doc sprawl — format-clean ≠ still-needed). For EACH research doc, decide KEEP / TRIM / DELETE. A research doc is meant to persist as the "why we chose X" rationale record, so the bar for deletion is: its unique rationale is captured nowhere it's needed. Delete/trim when:

• Stale point-in-time snapshot — the doc froze a moment ("free models as of Jan 2026", "current API pricing") that no longer holds and now misleads. → DELETE.
• Superseded / absorbed — its "Actionable Items" pointer is dead (the backlog item shipped, was absorbed, or renamed), AND its rationale is now captured in shipped code + a docs/reference/ doc. → DELETE.
• Bloated with redundant passes — multiple dated passes where later ones restate earlier prose (as opposed to adding distinct decision layers / empirical data). → TRIM to the load-bearing findings.
• Still a live write-target or seeds unshipped backlog — a backlog follow-up says "document findings here", or it holds impl detail/rationale for open themes the terse backlog rows lack. → KEEP.

How to run it: for each file, grep the repo for its filename (find inbound references), grep backlog/ + docs/proposals/ for whether its subject shipped/was-absorbed/is-still-open, and check docs/reference/ for a doc that already captures the same rationale. Verify before deleting — never orphan a rationale that isn't recorded elsewhere. Deletions are git rm (git history is the backstop); confirm with the maintainer if unsure.

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

• docs/steam-deck/ setup guides still accurate for current SteamOS version
• docs/steam-deck/ paths and commands work for the current dev environment

10. Root README.md

• pnpm ops guard:readme is green (project structure tree, Quick Start Node/pnpm versions, fenced pnpm scripts, slash-command list, and documentation links are all derivable and gated there — don't re-check these by hand)
• Architecture diagram matches actual services and external APIs
• External APIs section lists all current providers (OpenRouter, ElevenLabs, etc.)
• 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:

What	Compare
Architecture rules (01-architecture.md)	.dependency-cruiser.cjs forbidden rules
Quality command description	Root package.json quality script
CI steps	.github/workflows/ci.yml job steps
Pre-push checks	.husky/pre-push numbered steps
Package.json shortcuts	OPS_CLI_REFERENCE.md shortcuts table
Documentation placement list (07)	Actual docs/reference/ subdirectories
Cache table (durability-tiers.md)	Actual cache classes in codebase

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/now.md (📥 Untriaged) or the right backlog/cold/ file
4. Commit documentation fixes: docs: audit and refresh documentation
5. Stamp the full run: pnpm ops cadence:mark doc-audit, then commit backlog/cadence-ledger.json to develop (§ 0 and § 3b stamp their own passes)

References

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