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

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

Content truncated.