Rename References

Repository context. Gather first

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

• Working tree status (empty = clean), git status --porcelain | head -20
• Rename pairs (git), unstaged, git diff --name-status -M HEAD | grep '^R' | head -15
• Rename pairs (git), staged, git diff --cached --name-status -M | grep '^R' | head -15
• Current branch, git branch --show-current

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

Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute block as one shell invocation, and a worktree-isolated session refuses a compound command that contains git. The dated record for that composition claim is the source-control plugin's worktree/reference/gather-block.md, "The pre-compute block runs as one shell invocation".

Purpose

Renames are deceptively hard. After renaming a skill, file, or identifier, references survive in 7+ syntactic forms beyond the obvious token. Token-only grep (/old) catches 50–70%; the rest hide in chain prose (→ old →), comma-lists (Test, Old, Retro), numbered table rows (| 7. Old |), frontmatter chain strings (description: "...→ old → retro process."), frontmatter globs ({a,b,old,c}), cross-skill mode references, and content-file paths (context/old.md style).

This skill makes "find every reference" one invocation instead of 4 manual sweep passes. It runs the full pattern library, triages matches into 3 buckets, and surfaces ambiguity (English-verb collisions like confirm/test/review) for user confirmation rather than auto-applying blindly.

Adapting to your environment

This skill is self-contained, the pattern library, triage classifier, and audit modes below need only git and the Grep tool. Where prose names an adjacent capability (a verification workflow, an issue tracker, a codebase-audit routine), treat it as optional: if your environment provides it, invoke it; otherwise proceed without. Consumer-specific conventions (work-notes locations, commit policy, naming rules) come from the consuming repository's own CLAUDE.md and rules. Read them; this skill does not assume them.

Action router

Parse $ARGUMENTS first token to determine action. Subsequent tokens are the rename pair (with to/→/->/into separator) or single token for reverse-mode.

Pattern library is the load-bearing component, the full form registry lives in context/patterns.md; execute sweeps with the Grep tool. Read it before any sweep. Triage logic is in context/triage.md. Audit sub-mode detail (Blast / Half-rename / Orphans) is in context/audit-modes.md.

Override flags (audit modes)

Six flags. Four widen the sweep; two override the rename-mode resolution. Defaults preserve safety (rename-documenting plan docs / frozen historical notes / memory entries excluded). Long-form only, position-agnostic.

Multiple flags compose. Unknown flags raise an error. Detail in audit-modes.md "Override flags" section.

Blocklist action

/docs-hygiene:rename-references blocklist prints the English-verb blocklist literal from context/triage.md. Read-only. No edits, no sweeps. Use to inspect which tokens force the ambiguous-bucket safety path. To extend, edit triage.md directly.

Smart default (no arguments)

Detect rename pairs in this priority order:

1. Explicit args (highest precedence, never overridden)
2. Recent conversation. Scan last 20 turns for prose like "I renamed X to Y", "rename X → Y", "git mv X Y", or assistant edits replacing identifier X with Y across multiple files
3. Git rename detection. git diff --name-status -M HEAD and git diff --cached --name-status -M; R<score> lines map old path → new path
4. Paired D <path> + ?? <similar-path> in git status --porcelain (heuristic. Levenshtein-similar basenames within same dir)

If multiple candidates surface, present via AskUserQuestion. User picks which pair to audit.

If zero candidates: report "No rename detected in conversation or git state. Provide /docs-hygiene:rename-references <old> to <new> or /docs-hygiene:rename-references audit <old> to invoke explicitly."

Natural-language parser

The argument string after the action keyword can be:

Multi-word old/new is fine. Separator is the only delimiter. Quote characters ("foo bar") optional. Old/new taken verbatim. Leading slashes preserved (/confirm stays /confirm, not confirm).

Workflow phases (apply mode)

1. Detect. Gather rename pair (args / conversation / git per Smart default)
2. Survey. Run all patterns from context/patterns.md in parallel against tracked text files; aggregate per-file hit counts. For a skill/identifier rename, FIRST enumerate coupled-sibling renames (dot-form behavior point-IDs, internal mode names, content-file basenames that changed in lockstep) and queue EACH as its own rename pair. They carry no primary token, so the primary sweep never reaches them (see Gotchas "coupled-rename")
3. Triage. Classify each match into 3 buckets per context/triage.md:
   • Certain. Slash-token, path, frontmatter glob (high precision, auto-apply candidate)
   • Chain-context. Preceded/followed by other known skill names; numbered table rows; chain prose with multiple skill tokens
   • Ambiguous. Bare-token matches where token is in English-verb blocklist (confirm/test/review/fix/clean/build/lint/verify/plan/etc.)
4. Confirm. Present buckets via AskUserQuestion:
   • Certain → "auto-apply N matches?". Yes/no
   • Chain-context → "review N matches one-by-one?". Yes/skip-bucket/auto-apply-all
   • Ambiguous → per-match yes/no with surrounding context
5. Apply, Edit each accepted match. Idempotent, running twice is safe.
6. Re-sweep. Re-run Phase 2; exit when the ACTIONABLE count is 0 (the survey after context/patterns.md "Phase 0" span-precedence and "Phase 0b" container-rename mode, MINUS the matches the user confirmed skipping in Phase 4: neither the mode's residue nor a deliberate skip ever counts, or the loop cannot terminate). If non-zero, NEW form not in pattern library. Report to user, add to context/patterns.md, re-iterate.
7. Hand off. Suggest running the consuming repository's verification workflow (build + test + lint) to confirm no semantic regression in the rename target.

Audit mode runs phases 1-3 only and reports, no Edit calls. Preview mode runs 1-4 and reports planned edits, no Edit.

Auto-exclusions

Paths skipped from sweeps automatically:

• Rename-documenting plan/work-notes documents, an active plan file, migration notes, or changelog entry drafted for THIS rename references the rename pair as part of documenting the migration; both names appear by design. Identify these from conversation context and the consuming repository's work-notes conventions (its CLAUDE.md / rules). Skipping prevents self-reference loops.
• Archived/historical work notes. Completed plan documents and frozen records of past work are deliberately preserved as-is; past renames documented there are historical record, not stale references.
• .git/, node_modules/, bin/, obj/, .venv/, dist/, build/
• Claude Code auto-memory files in ~/.claude/projects/*/memory/ describing past renames

Composition

Edge cases

• English-verb collision. Tokens like confirm, test, review, clean, fix, build, lint, plan, run, view, start, stop, merge, split, sort, filter, group, head, body, link, list, work, log, watch, monitor. Triage forces these into ambiguous bucket regardless of regex hit position. User confirms each.
• Self-reference in plan docs, the active plan/work-notes document mentions the rename pair as part of documenting the migration. Auto-excluded; never modify.
• Concurrent sessions. Edit tool's read-before-write guard catches racing edits. If guard fails, report to user and abort.
• Word-boundary trap. confirm inside confirmation MUST NOT match. All bare-token patterns use \b.
• Slash-token specificity. /confirm should match but not /confirmation, /confirm-changes, or path/confirm. Use \B/<old>([^\w-]|$) (non-word-boundary before the slash; a CONSUMED terminator after that excludes a hyphen). A trailing \b is not enough: it treats a hyphen as a boundary, so it matches inside kebab-case sibling commands, and Form 1 is Certain, so that auto-applies. The consumed character is not part of the reference.
• Frontmatter trailing newline. YAML frontmatter description strings can span lines. Patterns must handle multi-line. Use multiline: true on the Grep tool.
• Renames with overlap. test → test e2e is a substring expansion. Apply most-specific match first, mark already-edited regions to prevent double-edit.
• Pattern false negative, if Phase 6 re-sweep reveals a NEW syntactic form, that's a feature gap. Add the pattern to context/patterns.md, re-iterate. Do NOT silently apply.

What this skill does NOT do

• Does not perform AST-level renames. Python class names, C# type names, JS function refactors. Use IDE refactor tools or language-aware refactoring tooling. This skill handles documentation, configuration, and identifier-string renames in text files.
• Does not rename git branches. Use git branch -m. Operates on file content, not git refs.
• Does not handle framework version migrations. Use dedicated migration tooling. Different concern: behavioral upgrade, not text rename.
• Does not auto-fix conversation history or memory entries. Past mentions of the old name in conversation/memory are deliberately preserved as historical record. Future renames are the user's responsibility to invoke this skill for.
• Does not run builds or tests. Hand off to the consuming repository's build/test/verification workflow after the rename completes.
• Does not perform general dead-reference scanning. audit orphans is STRICTLY pair-driven (post-rename hygiene only). For repo-wide dead-link / dead-reference checks unrelated to a specific rename, use a codebase-audit workflow or documentation link checker if your environment provides one. Charter boundary preserves single responsibility.

Gotchas

• A single-pattern grep is never evidence of a clean sweep. Token-only grep reaches Forms 1 and 2 and nothing else; chain prose, comma-lists, numbered rows, and frontmatter forms each need their own pattern, and each surfaces only when that pattern runs. Run the whole library, or invoke /docs-hygiene:rename-references audit.
• Ambiguous bucket is mandatory triage, not optional. English-verb collisions are the highest false-positive vector. If a token is in the blocklist, force into ambiguous regardless of position. Cost of one extra confirmation prompt is far lower than silently mangling prose.
• Re-sweep until the ACTIONABLE count is 0. Don't trust Phase 5 ended cleanly without verification. Phase 6 is the gate. "Actionable" is load-bearing, and it excludes TWO categories the sweep leaves matching forever: the bare-token residue container-rename mode deliberately leaves unrenamed, and any match the user confirmed skipping in Phase 4. Gating on the RAW count means the loop never terminates; gating on residue alone means it never terminates whenever the user declines a match, which container mode makes routine by demoting Forms 4–12 to per-match prompts. Skips are keyed by occurrence span, REMAPPED as Phase 5's edits shift later columns on the same line (a pre-edit span does not survive an edit when <old> and <new> differ in length), and reported separately from residue in the hand-off. One was declined, the other was never proposed.
• Plan-doc exclusion is mandatory. The active plan/work-notes document documents the rename and contains both old and new names by design. Editing it would break the documentation narrative.
• Pattern library evolves. When Phase 6 finds a NEW form, treat as a learning event: extend context/patterns.md, add an eval case. Future renames benefit immediately.
• A file MOVE breaks the moved files' own relative paths. Sweep INSIDE the moved set, not just refs TO it. When git mv changes directory depth, relative refs inside the moved files (source ../../lib.sh, # shellcheck source=../../../../tests/..., relative markdown links) silently break. They carry no renamed token, so every token-keyed pattern returns clean while the moved file itself is broken. After any depth-changing move: grep -nE '\.\./' <moved-files> + re-run the moved code from its new location (tests, --help). Real example: a directory promotion left a # shellcheck source= directive pointing four levels up when the new home was two.
• A rename couples sibling renames — the coupled-rename case. Sweep each as its own pair. Renaming a skill or identifier usually drags coupled siblings that do NOT contain the primary token: dot-form action/mode IDs (verify.runtime-affecting-paths, Form 12), internal mode names (quality mode), content-file basenames (context/quality.md style paths). A phase-scoped, skill-only grep on the primary token (/verify) leaves these EXTERNAL refs, in skill bodies, config files, and other skills' dispatch tables, unverified. A slash-anchored token sweep can return "clean" while <old>.id / <old-mode> / <old>.md-path refs survive elsewhere. Before declaring a rename complete: enumerate the coupled identifiers (Survey phase) and run a sweep per pair.

Integration with workflow

/docs-hygiene:rename-references is invocable mid-workflow whenever a rename happens. Typically during implementation (when the work includes a rename) or as a precursor to final verification, to confirm no stragglers before declaring done.

Skill chaining: