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

# What auto-memory entries exist? (Section 0 covers these — skip if
# this returns "No such file or directory" on a fresh install)
ls ~/.claude/projects/*tzurot*/memory/

# 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 memory entries that migrate to other layers (rules, docs, skills) will affect those sections' audits later.

0. Auto-Memory Audit (run FIRST)

Claude's auto-memory in ~/.claude/projects/tzurot/memory/ accumulates per-session knowledge that may belong in more durable, team-visible layers. Each memory file is catalogued in ~/.claude/projects/tzurot/memory/MEMORY.md (the index Claude reads at session start). Audit all entries before moving on — items that migrate to rules/docs/skills affect those layers' audits in later sections.

# Skip this section if the memory directory doesn't exist (fresh install,
# different machine) — there's nothing to audit. The 2>/dev/null + ||
# fallback turns the bash glob-expansion error into a friendly skip
# signal so a copy-paster sees clean output.
ls ~/.claude/projects/*tzurot*/memory/ 2>/dev/null \
  || echo "(no memory directory found — skip Section 0)"

# If the glob silently expands to nothing (different checkout path),
# find the project directory manually:
ls ~/.claude/projects/ 2>/dev/null | grep -i tzurot \
  || echo "(no tzurot project directory found in ~/.claude/projects/)"

How to classify each memory file

Read each file and pick the matching trigger first — these are the heuristics for choosing a verdict in the table below:

• Memory content already exists verbatim in a rule/doc/skill → Delete (no migration needed; this is the steady-state outcome — once the initial backlog is cleared, most future audits hit this case)
• Memory references a constraint that's now enforced by a rule → Delete (it's redundant)
• Memory describes a multi-step procedure → Migrate to .claude/skills/ (skill candidate)
• Memory captures a one-time investigation finding → Migrate to docs/research/ if distilled to TL;DR, or Delete if used and outdated
• Memory describes "always do X for this project" → Migrate to .claude/rules/ (rule candidate)
• Memory describes "this user prefers X" or time-bound state → Keep in memory (per-user context, not generalizable)

Verdict table

The "verify target covers full intent" step in the three migrate verdicts is load-bearing: a memory entry often has nuance (a specific exception, a concrete failure case) that the destination file doesn't yet cover. If you delete the memory before the destination has the nuance, the nuance is gone. Either extend the destination first, or downgrade the verdict to Keep until the destination is updated.

After processing each file, the order matters — for migrate verdicts especially, do these steps in sequence:

1. Write to the destination layer first (rule, doc, or skill — verifying it captures the full intent of the memory entry)
2. Delete the memory file
3. Update MEMORY.md (the index) to remove deleted entries and revise descriptions for any that changed

Doing them out of order risks orphaning the memory's nuance: if you delete the memory file before the destination has the content, the nuance is gone (the verdict table's bold "Verify the target..." callouts above guard against this).

Auto-memory audit runs as part of the recurring /tzurot-doc-audit cycle — there is no separate backlog item to track. If this section grows expensive enough to warrant its own cadence (e.g., audited weekly, while docs are quarterly), split it out then.

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/)

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:

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.

1. Would a reader act differently without it? If removing the passage

changes no behavior, it is costing tokens to be agreed with.

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

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

4. Reference Docs by Subdirectory

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:

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

References

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