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

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

Content truncated.