| name | audit-hygiene |
| description | Survey the codebase for organizational drift — oversized files, files that should be split or merged, misleading names, directory structures that hurt navigation. Use when the user asks to clean up, reorganize, or review codebase structure. |
Codebase hygiene audit
As a project grows, files get bigger, coherent designs stretch, and names drift away from contents. This skill surveys the whole codebase (Python and Rust) for those smells and produces a prioritized list of structural fixes.
Scope
- Python under
src/sfmtool/ and tests/
- Rust crates under
crates/
- Top-level layout (
scripts/, specs/, docs/)
What to look for
- Oversized files — modules or source files that have grown past what their purpose justifies. Look at line count, but more importantly at whether the file holds multiple distinct concerns.
- Files that should be combined — small files that fragment a single concern, or near-duplicates.
- Misleading names — files whose name no longer describes what's inside (e.g., grew to cover a second topic, or the original concept was renamed but the file wasn't).
- Directory-level smells — directories that are flat when they should be grouped, grouped when they should be flat, or where the grouping no longer matches how the code is actually used.
- Dead or near-dead code — modules referenced only by tests, commented-out blocks,
_foo_old.py-style leftovers.
How to work
- Get a size overview: file line counts per directory.
- Sample the largest files and skim their structure — count distinct top-level concerns.
- Dispatch
Agent subagents in parallel over subtrees (e.g., one for src/sfmtool/feature_match/, one for crates/sfmtool-core/) to get focused assessments.
- Consolidate findings, removing duplicates and ranking.
Output
One section per recommendation:
**<short title>**
- Location: <file or dir path>
- Problem: <specific smell — "this 1200-line file mixes matching, filtering, and I/O">
- Proposed fix: <split into X and Y | merge with Z | rename to W | regroup under foo/>
- Effort: <low | medium | high>
- Risk: <low | medium | high> — <what could break>
End with a Top 3 section: the fixes with the best effort-to-value ratio.
Saving the report
Write the full report to reports/<date>-hygiene-audit.md, where <date> is
today's date in YYYY-MM-DD form (get it with date +%F). Create the
reports/ directory if it doesn't exist. Each run is a dated snapshot — do not
overwrite a prior day's report. After saving, tell the user the path and give a
short summary of the Top 3 in the conversation; don't paste the whole report
back.
Guidelines
- Be specific. "X is too big" is useless; "X is 900 lines covering matching AND geometric filtering AND serialization — split serialization into a sibling file" is useful.
- Cite line counts or symbol counts when flagging size.
- Don't flag a file just because it's long — long is fine if the file has a single coherent purpose.
- Do not modify any code during this skill — it is read-only analysis.
