naming-refactor
starsforks
How to install naming-refactor?
paulrberg/agent-skills/naming-refactor
$npx -y skills add PaulRBerg/agent-skills --skill naming-refactorRefactor naming and repository structure exhaustively while preserving behavior and external contracts.
SKILL.md
| 1 | # Naming Refactor |
| 2 | |
| 3 | Make every name in the current repository communicate one coherent domain model, regardless of refactor cost. |
| 4 | |
| 5 | ## Contract |
| 6 | |
| 7 | - Cover the complete current Git repository. Do not narrow the run to selected files or stop after a candidate cap. |
| 8 | - Preserve features, runtime behavior, side effects, performance-sensitive characteristics, and externally consumed |
| 9 | contracts. Large diffs, path moves, and repository-controlled interface migrations are allowed. |
| 10 | - Treat an exported surface as repository-controlled only when every consumer is in scope and can migrate atomically. |
| 11 | Preserve other API names, CLI flags, environment variables, configuration keys, wire fields, routes, database names, |
| 12 | and import paths unless the user explicitly authorizes a breaking migration. |
| 13 | - Fix a bug discovered during the refactor only when the defect and intended behavior are clear and a regression check |
| 14 | can prove the fix. Keep bug fixes in a distinct change wave and report them separately. |
| 15 | - Preserve pre-existing work. Local edits, file moves, directory restructuring, and non-destructive validation are |
| 16 | authorized. Do not commit, push, publish, or write externally unless the user or repository instructions require it. |
| 17 | - A verified no-op is valid only after exhaustive coverage. Do not rename a clear, conventional name merely to create |
| 18 | churn, but do not retain a weak name to minimize diff size. |
| 19 | |
| 20 | ## Coverage Ledger |
| 21 | |
| 22 | Resolve `scripts/naming-ledger.py` relative to this `SKILL.md` and create its ledger outside the repository: |
| 23 | |
| 24 | ```sh |
| 25 | uv run "<skill-dir>/scripts/naming-ledger.py" init --root <repo> --ledger <scratch.json> |
| 26 | ``` |
| 27 | |
| 28 | The helper maps every tracked and non-ignored untracked path and records pre-existing worktree state. Account for a path |
| 29 | only after inspecting its name, relevant contents, and role: |
| 30 | |
| 31 | ```sh |
| 32 | uv run "<skill-dir>/scripts/naming-ledger.py" mark \ |
| 33 | --ledger <scratch.json> --status <pending|retained|renamed|excluded|blocked> \ |
| 34 | --path <path> [--path <path>...] [--reason <text>] |
| 35 | ``` |
| 36 | |
| 37 | Use `retained` when the current name is justified, `renamed` when the path or its contents joined a verified rename, |
| 38 | `excluded` for generated, vendored, binary, or bulk artifacts validated through their source or invariant, and `blocked` |
| 39 | when behavior or contract safety cannot be established. `excluded` and `blocked` require reasons. |
| 40 | |
| 41 | ```sh |
| 42 | uv run "<skill-dir>/scripts/naming-ledger.py" pending --ledger <scratch.json> [--limit <n>] |
| 43 | uv run "<skill-dir>/scripts/naming-ledger.py" refresh --ledger <scratch.json> |
| 44 | uv run "<skill-dir>/scripts/naming-ledger.py" summary --ledger <scratch.json> |
| 45 | ``` |
| 46 | |
| 47 | Refresh after path moves and before final validation. New paths become pending; removed paths remain in the ledger and |
| 48 | must be accounted as renamed, excluded, or blocked. The run is complete only when the helper reports no pending or |
| 49 | blocked paths. |
| 50 | |
| 51 | ## Ground the Refactor |
| 52 | |
| 53 | 1. Read applicable repository instructions. Record the repository root, starting commit and status, build and check |
| 54 | commands, generated sources, and ownership boundary for pre-existing changes. |
| 55 | 2. Initialize the ledger and establish baseline format, lint, type, test, build, codegen, API-snapshot, or smoke checks |
| 56 | appropriate to the repository. Attribute existing failures before editing. |
| 57 | 3. Identify external contracts, repository-controlled consumers, reflection and serialization surfaces, dynamic imports, |
| 58 | case-insensitive filesystem constraints, and language-aware rename tooling. |
| 59 | 4. Derive canonical domain vocabulary from behavior, types, data flow, documentation, tests, and relevant history. |
| 60 | History resolves unclear intent; it does not override the current design. |
| 61 | |
| 62 | Completion of this phase requires a recorded baseline, explicit contract boundaries, and a ledger covering the entire |
| 63 | repository. |
| 64 | |
| 65 | ## Build the Rename Map |
| 66 | |
| 67 | Inspect every ledger path and build an evidence-backed map before changing each coherent domain slice. Cover |
| 68 | directories, files, packages, modules, namespaces, exports, types, classes, functions, methods, parameters, variables, |
| 69 | booleans, constants, tests, fixtures, documentation, configuration, scripts, and CI. |
| 70 | |
| 71 | Apply these rules together: |
| 72 | |
| 73 | - Give one concept one canonical term; give distinct concepts distinct terms. |
| 74 | - Name by domain role, behavior, ownership, lifecycle, units, and polarity rather than incidental implementation. |
| 75 | - Replace misleading, overloaded, contextless, or generic names such as `data`, `info`, `item`, `manager`, `process`, |
| 76 | `handle`, and `utils` when a specific name is supported by evidence. |
| 77 | - Align directory, filename, primary export, and module responsibility. Move paths when the current structure obscures |
| 78 | ownership or forces names to compensate for poor |
People who liked this also viewed
6 picksType
- hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026
- request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026
- explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026
- ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
