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.
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.
Sweep for references, feeding it the offender pairs:
${CLAUDE_SKILL_DIR}/scripts/sweep.sh --root <repo> --pairs <pairs.tsv>
Each REF row carries the citing file, the line, the form, the tier, the
action, and an excerpt. The actions are edit, report, review, skip,
and regenerate; context/tiers.md owns what each means.
Done when: a SITES row is present and every offender pair appears in at
least one REF row or is reported as having no site at all.
Compose the plan into the resolved home:
${CLAUDE_SKILL_DIR}/scripts/emit-findings.sh --root <repo> \
--inventory <inv.tsv> --sweep <sweep.tsv> --out <resolved>/file-names.md
A zero-offender run over a non-empty root still runs the sweep with an empty
pairs file and the emit, and leaves a findings: 0 plan.
Done when: the script reports the path it wrote and a finding count equal
to the inventory's offender count.
Cite the scripts' rows verbatim. The realign applies the action each site
carries, so a form or a tier you inferred by reading is a guess that edits the
wrong shape. If a site does not correspond to a REF row, say so rather than
inventing one.
Where the artifact goes
Write under the home ../../context/file-name-findings.md "Where it lives"
defines. A plan written anywhere else is one the realign never finds, and that
failure reads exactly like "no audit has been run".
If a plan already exists at the resolved home, the emitter merges into it by
finding id and carries every decision forward. Do not delete it to get a clean
run; a declined finding that reappears as pending is a decision the operator
made being asked again.
Present the result
- The form table for every tier the plan touched, from
context/tiers.md.
- One line per finding, most-cited first: the old and new path, the site count,
the tier breakdown, and whether a generated file is involved.
- Every
review site, individually, with its line and excerpt. These are the
ambiguous bare stems, and no script can settle them.
- The artifact's path, and the next step:
/docs-naming:realign-file-names
with the ids to accept.
Say the count of report sites plainly. A maintainer who expected a frozen tier
to change needs to see that it did not.
Completion criteria
The run is done when the artifact exists at the resolved home, its finding count
equals the inventory's offender count, the tree is byte-identical to how it
started (git status --porcelain unchanged), and every review site has been
surfaced to the operator rather than folded into a total.
What this skill does NOT do
- Rename anything, edit any reference, or run any regenerator. It is read-only
on every file it inspects.
- Re-judge a plan it already wrote. A stale plan is re-audited, not patched.
- Decide whether a
review site names the file. It escalates them.
- Bump a version, write a changelog entry, or commit.
- Sweep a tree the configuration excludes, or a file a tier freezes.
Next
/docs-naming:realign-file-names
Gotchas
- A collision refuses the plan, not just one finding. Two paths differing
only by case cannot coexist on macOS or Windows checkouts. The whole run stops
so nobody applies half of it.
SCANNED 0 is an empty root, not a clean tree. A roots entry that
matches no tracked file inventories nothing and finds nothing. The emitter
exits 3 rather than overwrite an existing plan that holds findings with an
empty one; pass --replace only when the plan is meant to be discarded.
- Existence is asked of the git index, never the filesystem. On a
case-insensitive checkout a filesystem test answers for the wrong spelling,
which would refuse every case-only rename on exactly the platforms the rule
protects.
- A
review site is not a smaller edit. It is a bare stem that is also an
ordinary word. Rewriting one on a text match is how a rename edits a sentence
that had nothing to do with the file.
- A generated record is never text-edited. Its sites are marked
regenerate, because a substitution that looks right leaves a stale derived
value no reader would notice.
- The plan is checkout-local. It lives in the memory tier, keyed by branch,
and a sibling worktree never sees it. A decision that must outlive the branch
goes into the tracked concern file, which the realign offers and never takes.
- Run it from the tree you mean. Every script takes
--root; inside a second
worktree, pass it, or run from that worktree.
1---2name: audit-file-names3description: "Read-only audit of a docs tree's file names against a configured casing rule: proposes a name per offender, classifies every reference to it, refuses case-only collisions, and writes the plan realign-file-names applies. Use when: 'audit file names', 'are our doc filenames consistent', 'plan a docs rename', 'which files break the naming rule', 'find every reference to this doc', 'rename the docs tree', 'lower-kebab the docs folder', 'what would a docs rename touch'. Renames nothing."4argument-hint: "[audit] [root ...]"5user-invocable: true6disable-model-invocation: false7allowed-tools: ["Bash(${CLAUDE_SKILL_DIR}/scripts/inventory.sh:*)", "Bash(${CLAUDE_SKILL_DIR}/scripts/sweep.sh:*)", "Bash(${CLAUDE_SKILL_DIR}/scripts/emit-findings.sh:*)", "Bash(git branch --show-current:*)", "Bash(git rev-parse:*)", "Bash(git check-ignore:*)", "Read", "Write", "Grep"]8shell: bash9metadata:10 source: https://skillmd.com/skills/melodic-software/audit-file-names11 workflow-stage: anytime12 summary: Inventory a doc tree's file names and plan the renames with their references13---1415## Repository context. Gather first1617Collect these with **individual** Bash calls, one command per call, never18combined into a single invocation:1920- Current branch, `git branch --show-current`21- Working tree status (empty = clean), `git status --porcelain | head -20`22- Repository root, `git rev-parse --show-toplevel`2324The pipe is the bound and belongs in the command. A read-time cap bounds25nothing: the Bash tool returns the command's complete output into context before26there is anything to decide about.2728Treat a failure as an unknown value and carry on.2930## Purpose3132A documentation tree drifts one file at a time, and by the time anyone notices,33the cost of fixing it is not the renames. It is finding every citation of every34renamed file, deciding which of them may be rewritten, and not corrupting a35generated record or a released changelog entry on the way through.3637This skill does the finding and the deciding, and writes the result down. It38renames nothing. `/docs-naming:realign-file-names` executes the plan, one39acceptance at a time.4041## Read these before presenting anything4243| Read | For |44|---|---|45| [`context/tiers.md`](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 |46| [`../../context/file-name-findings.md`](../../context/file-name-findings.md) | where the artifact goes, its shape, its stable ids, its status arcs, and the re-audit merge |47| [`../../reference/config.md`](../../reference/config.md) | every configuration key, its default, and which layer may supply it |4849## Facts before judgment5051Three scripts produce the facts. Run them in order and build the plan on what52they emit.53541. **Inventory** the tree:5556 ```bash57 ${CLAUDE_SKILL_DIR}/scripts/inventory.sh --root <repo>58 ```5960 It emits `OFFENDER`, `COLLISION`, `EXEMPT`, and `SCANNED` rows. A `COLLISION`61 row means the plan would put two paths differing only by case into one tree.62 **Stop there.** Report the pair and the reason, and propose nothing: on a63 case-insensitive checkout the second file overwrites the first, so this is a64 corrupted tree rather than a plan to review.65 A `SCANNED 0` row, with its stderr warning, means nothing is tracked under66 the roots. Report that and stop: it is an empty root, not a clean tree.67 *Done when:* a `SCANNED` row with a nonzero count is present and the68 `COLLISION` count is zero, or the run reported an empty root and stopped.69702. **Sweep** for references, feeding it the offender pairs:7172 ```bash73 ${CLAUDE_SKILL_DIR}/scripts/sweep.sh --root <repo> --pairs <pairs.tsv>74 ```7576 Each `REF` row carries the citing file, the line, the form, the tier, the77 action, and an excerpt. The actions are `edit`, `report`, `review`, `skip`,78 and `regenerate`; `context/tiers.md` owns what each means.79 *Done when:* a `SITES` row is present and every offender pair appears in at80 least one `REF` row or is reported as having no site at all.81823. **Compose** the plan into the resolved home:8384 ```bash85 ${CLAUDE_SKILL_DIR}/scripts/emit-findings.sh --root <repo> \86 --inventory <inv.tsv> --sweep <sweep.tsv> --out <resolved>/file-names.md87 ```8889 A zero-offender run over a non-empty root still runs the sweep with an empty90 pairs file and the emit, and leaves a `findings: 0` plan.91 *Done when:* the script reports the path it wrote and a finding count equal92 to the inventory's offender count.9394**Cite the scripts' rows verbatim.** The realign applies the action each site95carries, so a form or a tier you inferred by reading is a guess that edits the96wrong shape. If a site does not correspond to a `REF` row, say so rather than97inventing one.9899## Where the artifact goes100101Write under the home `../../context/file-name-findings.md` "Where it lives"102defines. A plan written anywhere else is one the realign never finds, and that103failure reads exactly like "no audit has been run".104105If a plan already exists at the resolved home, the emitter merges into it by106finding id and carries every decision forward. Do not delete it to get a clean107run; a declined finding that reappears as pending is a decision the operator108made being asked again.109110## Present the result1111121. The form table for every tier the plan touched, from `context/tiers.md`.1132. One line per finding, most-cited first: the old and new path, the site count,114 the tier breakdown, and whether a generated file is involved.1153. Every `review` site, individually, with its line and excerpt. These are the116 ambiguous bare stems, and no script can settle them.1174. The artifact's path, and the next step: `/docs-naming:realign-file-names`118 with the ids to accept.119120Say the count of `report` sites plainly. A maintainer who expected a frozen tier121to change needs to see that it did not.122123## Completion criteria124125The run is done when the artifact exists at the resolved home, its finding count126equals the inventory's offender count, the tree is byte-identical to how it127started (`git status --porcelain` unchanged), and every `review` site has been128surfaced to the operator rather than folded into a total.129130## What this skill does NOT do131132- Rename anything, edit any reference, or run any regenerator. It is read-only133 on every file it inspects.134- Re-judge a plan it already wrote. A stale plan is re-audited, not patched.135- Decide whether a `review` site names the file. It escalates them.136- Bump a version, write a changelog entry, or commit.137- Sweep a tree the configuration excludes, or a file a tier freezes.138139## Next140141`/docs-naming:realign-file-names`142143## Gotchas144145- **A collision refuses the plan, not just one finding.** Two paths differing146 only by case cannot coexist on macOS or Windows checkouts. The whole run stops147 so nobody applies half of it.148- **`SCANNED 0` is an empty root, not a clean tree.** A `roots` entry that149 matches no tracked file inventories nothing and finds nothing. The emitter150 exits 3 rather than overwrite an existing plan that holds findings with an151 empty one; pass `--replace` only when the plan is meant to be discarded.152- **Existence is asked of the git index, never the filesystem.** On a153 case-insensitive checkout a filesystem test answers for the wrong spelling,154 which would refuse every case-only rename on exactly the platforms the rule155 protects.156- **A `review` site is not a smaller `edit`.** It is a bare stem that is also an157 ordinary word. Rewriting one on a text match is how a rename edits a sentence158 that had nothing to do with the file.159- **A generated record is never text-edited.** Its sites are marked160 `regenerate`, because a substitution that looks right leaves a stale derived161 value no reader would notice.162- **The plan is checkout-local.** It lives in the memory tier, keyed by branch,163 and a sibling worktree never sees it. A decision that must outlive the branch164 goes into the tracked concern file, which the realign offers and never takes.165- **Run it from the tree you mean.** Every script takes `--root`; inside a second166 worktree, pass it, or run from that worktree.