naming-and-structure-cleanup-c8dfac— agent skill

Purpose

Inconsistent naming (camelCase vs snake_case) and messy file structures make codebases hard to navigate. Enforce the dominant local convention with focused, logic-free diffs.

When to Use

• Mixed naming conventions for the same kind of symbol or file
• Closely related files scattered instead of co-located
• Review feedback keeps flagging names/structure rather than logic

Inputs

• The area to clean (directory or module)
• The repo's type-check and test commands

Workflow

1. Observe local conventions. Before renaming, scan the project to determine the dominant convention. If 80% of files use camelCase, enforce camelCase:

   find src -type f | grep -cE "/[a-z]+[A-Z][a-zA-Z]*\."    # camelCase filenames
   find src -type f | grep -cE "/[a-z]+(_[a-z]+)+\."        # snake_case filenames
   grep -rnE "function [a-z]+_[a-z]+\(" src/                # snake_case functions in a camelCase repo

1. Targeted renames. Use the safe-rename command pattern to update variables, classes, or files. Ensure all imports are updated:

   git grep -ln "\bOldName\b" | xargs sed -i "s/\bOldName\b/NewName/g"   # then review the diff
   git mv src/old_location/Component.tsx src/feature/Component.tsx       # git mv preserves history
   git grep -n "old_location"                                            # no stale import paths remain

1. File co-location. Move files so that closely related logic is co-located (e.g., keeping Button.tsx, Button.css, and Button.test.tsx in the same directory).

1. No logic changes. Do not refactor the internal logic of functions while performing naming cleanups. Keep the diff focused purely on structure and names.

1. Verify. Run the project's type checker and test suite after every structural change.

Output

• A rename/move-only diff with all imports updated
• The convention evidence (counts) that justified the chosen direction

Verification

• [ ] Dominant convention measured before renaming, not assumed
• [ ] All imports/references updated — old names re-grepped with zero hits
• [ ] Diff contains zero logic changes
• [ ] Type checker and tests green after every structural change

Failure Modes

• Imposing taste over convention — the repo's dominant style wins, not the cleaner's preference.
• Rename + refactor in one diff — mixing logic changes into a rename makes both unreviewable.
• Substring renames — search/replace without word boundaries renames symbols it shouldn't; re-grep the old name after.