codebase-hygiene

name	codebase-hygiene
description	Find semantic duplicates (same intent, different implementation) and shallow modules (thin wrappers spreading complexity). Read-only advisory — changes route through BUILD with full gates. Use when auditing code quality, before refactoring, or when a codebase feels bloated.

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.