audit-file-names

Repository context. Gather first

Collect these with individual Bash calls, one command per call, never combined into a single invocation:

• Current branch, git branch --show-current
• Working tree status (empty = clean), git status --porcelain | head -20
• Repository root, git rev-parse --show-toplevel

The pipe is the bound and belongs in the command. A read-time cap bounds nothing: the Bash tool returns the command's complete output into context before there is anything to decide about.

Treat a failure as an unknown value and carry on.

Purpose

A documentation tree drifts one file at a time, and by the time anyone notices, the cost of fixing it is not the renames. It is finding every citation of every renamed file, deciding which of them may be rewritten, and not corrupting a generated record or a released changelog entry on the way through.

This skill does the finding and the deciding, and writes the result down. It renames nothing. /docs-naming:realign-file-names executes the plan, one acceptance at a time.

Read these before presenting anything

Read	For
context/tiers.md	the form table to print before any plan, and why a historical tier keeps its links while a released tier is frozen
../../context/file-name-findings.md	where the artifact goes, its shape, its stable ids, its status arcs, and the re-audit merge
../../reference/config.md	every configuration key, its default, and which layer may supply it

Facts before judgment

Three scripts produce the facts. Run them in order and build the plan on what they emit.

1. Inventory the tree:

   ${CLAUDE_SKILL_DIR}/scripts/inventory.sh --root <repo>
   

   It emits OFFENDER, COLLISION, EXEMPT, and SCANNED rows. A COLLISION row means the plan would put two paths differing only by case into one tree. Stop there. Report the pair and the reason, and propose nothing: on a case-insensitive checkout the second file overwrites the first, so this is a corrupted tree rather than a plan to review. A SCANNED 0 row, with its stderr warning, means nothing is tracked under the roots. Report that and stop: it is an empty root, not a clean tree. Done when: a SCANNED row with a nonzero count is present and the COLLISION count is zero, or the run reported an empty root and stopped.