Untangle codebase coupling and dependencies

Untangle Codebase guides a codebase-wide structural refactor around a practical question: should these pieces change together? It inventories places where the structure gives the wrong answer, redesigns shared causes and repeats review until no worthwhile structural fixes remain within the authorized scope. Intended behavior stays the same apart from bugs resolved by the refactor.

The first step separates the core refactor from optional comment and test work. The user chooses whether to remove comments that only restate code and whether to remove or repair tests that do not detect real regressions. The choices are presented with their exact descriptions: Comments - "Remove comments that only restate the code." Tests - "Remove tests that wouldn't catch a real bug, and fix the ones that fail without one." Only selected additions are performed. Existing checks establish a baseline, and unrelated work is preserved.

The inventory groups problems into hidden links, needless links and surplus. Hidden links include duplicated logic or values, implicit shared state, related features scattered across layers and call-order conventions callers must remember. Needless links include callers depending on internals, stable modules importing volatile code, general functions carrying one workflow's vocabulary and shallow interfaces that change whenever their internals do. Surplus includes pass-through wrappers, unused extension points and dead code.

Special cases receive their own inventory because they can reveal requirements the design never incorporated: one-value branches, caller-specific parameters, swallowed exceptions, retries, sleeps and disabled tests. Before changing files, the workflow records each problem in a decision log. It then looks for a redesign that resolves several symptoms together rather than patching each exception independently. Pieces that change together are colocated, unrelated reasons for change are separated, and dependencies point toward what changes less.

A decision log can connect a dialog's 100ms focus delay and a skipRefocus flag to one shared focus-restoration fix. Separate duplicated disabled-state checks, missing shortcut entries and repeated track() calls can point to a shared command abstraction. Each proposed fix sits above the specific problems it resolves.

Implementation follows that log, removing only the exceptions made unnecessary by the redesign and keeping required domain behavior. Selected comment cleanup distinguishes redundant implementation narration from external facts the code cannot express. Workaround comments disappear when their underlying problem disappears. Selected test cleanup happens last because tests provide the regression safety net. Tests tied to internals are rewritten around behavior; implementation mirrors and checks that cannot fail are candidates for removal. Failures are never hidden by deleting tests merely to get green results.

Repeated review searches again for special cases, hidden links, needless links and surplus. Completion considers whether typical changes now land in one place, imports follow sensible dependency direction, required exceptions remain and behavior checks still pass. Skeleton views, module summaries, dependency graphs and Git change history help reason about structure across the repository. The decision log keeps redesign rationale connected to the problems it resolves. Better structure aims to reduce searching, change effort, silent breaks and debugging effort; these are motivations, not measured guarantees.

Use it for an explicitly requested structural refactor across an authorized codebase. A single defect belongs to systematic debugging, while a bounded cleanup is better handled by code-refactoring-refactor-clean. Fewer exceptions is a design heuristic, not a correctness proof, and public contracts must be preserved. Whole-codebase work can exceed one session; remaining issues and unavailable or failing checks need truthful reporting.

Inputs are the authorized repository, scope, existing behavior checks and the user's choices about optional comments and tests. Outputs include a coupling inventory, a decision log mapping redesigns to problems, scoped structural changes and baseline-versus-final regression evidence. The workflow does not independently authorize publishing, pushing, deployment, user-data deletion or private-source uploads.

Git history supplies evidence of how often components change and which ones change together. Optional subagents can summarize modules or perform review passes when the host supports them and delegation is authorized; otherwise the same review passes are performed directly.

The workflow is adapted from caldoai/skills at pinned revision f3cf47774975a7d9fca45730babf4ff7ad765ada with its MIT copyright notice retained. Local adaptations add scope, safety boundaries, examples and limitations.