Codebase Hygiene

Codebase Hygiene

Advisory and read-only. Diagnoses and proposes; does not refactor. Any actual change goes through /loop or /build with full gates.

Mode 1: Semantic duplicate detection

Copy-paste detectors catch syntactic duplicates. This finds semantic duplicates — functions serving the same purpose but implemented independently under different names.

Method

1. Extract catalog — grep/glob for exported functions. Record name | file:line | signature.
2. Categorize by domain (cheap tier) — validation, formatting, path manipulation, HTTP shaping, date handling. Mechanical bucketing to shrink the comparison space.
3. Drop categories with <3 functions — can't hide a meaningful duplication pattern.
4. Detect duplicates per category (capable tier) — READ the implementations, decide which share intent. Never use cheap name-based detection — it anchors on names and rubber-stamps "these look different."
5. Emit findings — group by confidence, highest first. Each finding: what is duplicated, why it matters, the fix, file:line evidence. Route through the review finding contract.

High-risk zones

| Zone | Why it duplicates | | ---- | ----------------- | | utils/, helpers/, lib/ | Catch-all dumping grounds | | Validation code | "Is this a valid email/id/url" rewritten per feature | | Error formatting | Every module invents its own Error → string | | Path manipulation | Join/normalize/relativize reimplemented | | String formatting | Truncate, slugify, titlecase, pad re-rolled | | Date formatting | Parse/format/diff scattered | | API response shaping | Envelope/pagination/error-body copied per endpoint |

Consolidation discipline

Never delete a duplicate until ALL THREE hold:

1. Survivor has tests — pick the implementation with real coverage. If neither has tests, write the test against the chosen survivor first.
2. All callers updated — grep to enumerate callers. Missing one is a silent break.
3. Re-run after consolidation — test suite + build/typecheck pass. Green tests on the survivor license the deletion.

Mode 2: Module deepening

Thin wrappers and pass-through layers spread complexity without adding capability. A module that only forwards calls to another module is a shallow module — it adds a layer to navigate without earning it.

Signals

• A module whose entire body is forwarding calls to one other module.
• "Manager" / "Service" / "Helper" classes that wrap a single dependency and add no logic.
• Functions that take args, immediately pass them unchanged to another function, and return its result.

Fix direction

Deepen: collapse the wrapper into its caller, OR add real responsibility (validation, transformation, policy) that justifies the layer. A module should either hide complexity (deep module) or not exist.

Don't

• Don't refactor from this skill — it's advisory. Propose, then route the change through /loop or /build.
• Don't delete a duplicate without the 3 consolidation gates (tests + callers + re-run).
• Don't trust name-based duplicate detection — read the implementations.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: romiluz13
• Source: romiluz13/auto-pi
• License: MIT

Install and usage instructions live in the source repository linked above.