/codebase-hygiene

name: codebase-hygiene
description: |
  Two-mode skill: (1) find semantic duplicates — functions doing the same thing
  under different names, invisible to copy-paste detectors; (2) deepen shallow
  modules — thin wrappers and pass-through layers that spread complexity.
  Advisory and read-only; changes route through BUILD with full gates.
allowed-tools: Read Grep Glob Bash
user-invocable: false

Codebase Hygiene (Duplicate Detection + Module Deepening)

Advisory and read-heavy. Diagnoses and proposes; does not refactor. Any actual change goes through BUILD with full gates.

Mode: DUPLICATE DETECTION

Semantic duplicates: functions serving the same purpose but implemented independently under different names. Copy-paste detectors catch syntactic duplicates; this finds "same intent, different implementation."

Method

0. **Scope before you scan** — take the user's named target; else `git log --oneline` for hot spots and weight recently-changed code — deepening pays off in proportion to future change. 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 comparison space. 3. **Drop categories with <3 functions** — can't hide a meaningful duplication pattern. 4. **Detect duplicates per category** (capable tier) — read implementations, decide which share intent. **Never use cheap tier for 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 code-reviewer 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: MODULE DEEPENING

Existing code works; the problem is **shape**, not features. LLM-grown codebases accrete shallow modules — thin wrappers, pass-through layers, near-duplicate helpers. Each looks harmless; together they spread complexity across every caller.

**Deep module:** hides a lot of behavior behind a small interface. **Shallow module:** interface is almost as complex as its implementation — callers learn a thing without getting much.

The Deletion Test

For each candidate: **If I deleted this module and inlined its code at every call site, where does the complexity go?**

• Complexity **vanishes** → the module was a pass-through / shallow. It adds indirection without hiding complexity. Deepening candidate (delete it or deepen its interface).
• Complexity **reappears across N call sites** → the module is deep. It earns its existence by hiding complexity that would otherwise be duplicated. Leave it alone.

This verdict agrees with `cc10x:codebase-design` (canonical) and `cc10x:architecture`. Depth is leverage at the interface — not a lines-ratio.

| Smell | Usually | | ------- | --------- | | Thin wrapper (`doX(a){ return lib.doX(a) }`) | Shallow | | Pass-through layer (service maps 1:1 to repo) | Shallow | | Near-duplicate helper (same intent, different name) | Shallow — consolidate first | | Config/leverage module (small interface, branching/retry/state inside) | Deep — keep |

Diagnosis Flow (READ-ONLY)

1. Enumerate exported surface (`name | file:line | signature`) 2. Flag shallow shapes 3. Cross-reference near-duplicates (run duplicate detection mode first — consolidate before deepening) 4. Run deletion test on each survivor 5. Output: candidate list, not a refactor

Present Candidates Before Proposing Interfaces

Badge each candidate: **Strong** (unambiguous), **Worth-exploring** (real cost/risk), **Speculative** (hunch, low confidence).

For each: before/after sketch (current shallow interface vs proposed deeper one) with deletion test result. Then stop and ask which to pursue. Do not design interfaces for candidates the user hasn't chosen.

Two-Adapters Rule for Seam Placement

When designing the deeper interface, a **port** (an injected external dependency seam) needs two concrete **adapters** — e.g. a production transport and a test stand-in. An ordinary caller or a test exercising a public interface is NOT an adapter; the two-adapter rule is about ports, not every seam.

For a non-port seam (the common case for module deepening): the test must be able to reach the interface. If only production code crosses the seam and no test can reach it → the seam is a guess. Put the interface where a test can reach it, or don't introduce it. This aligns with `cc10x:codebase-design` — "one adapter means a hypothetical seam" applies to ports; internal seams need reachability, not a second adapter.

Handoff to BUILD

This skill ends at: chosen candidate + deeper-interface proposal + named seam. It does NOT edit code. The refactor routes through planner → BUILD workflow (builder → reviewer → verifier → doc-sync → memory). The deepening is verified: survivor interface has tests at its seam, every caller is repointed, suite + typecheck pass after merge.

Pr