claude-vibe-squad: Skill for Claude Code

Dependency Cycle Audit

Find every dependency cycle at the granularity the build or loader actually enforces, rank the cycle clusters by blast radius, and break each with the cheapest cut that removes the coupling instead of hiding it.

When to use

• Before approving an architecture change, module split, or extraction of a shared library.
• When builds rebuild "everything" on small changes, tests cannot run in isolation, or imports fail depending on load order.
• After a refactor that moved code between modules — cycles regrow silently.

Inputs

• The codebase at a fixed revision, and its dependency ground truth: import statements, build-file dependency declarations, package manifests, linker inputs — never a diagram or a doc.
• The enforcement level to audit at: package, module, file, or build target.

Steps

1. Fix the granularity first. A cycle visible at file level may be legal inside one package, while a package-level cycle breaks the build; audit at the level the toolchain enforces, and say which level you chose.
2. Extract the edge list from ground truth. Use an import-graph or build-graph extractor for the ecosystem (a dependency-graph tool category exists for every major toolchain: import-graph analyzers, build-graph query commands, module-dependency linters); where none is at hand, grep the import forms directly. Record the extraction command so the audit is repeatable.
3. Compute strongly-connected components (Tarjan or Kosaraju; any graph library, or a short script over the edge list). Every SCC with more than one node is a cycle cluster. Enumerate all of them — do not stop at the first cycle found; cycles cluster, and the count is the honest baseline.
4. Characterize each cluster: which edges close the cycle, each edge's weight (distinct symbols imported across it), and whether the edge is load-bearing (core call path) or incidental (one type reference, a convenience re-export, a leftover import).
5. Rank clusters by blast radius: fan-in of the cluster's members times the churn of its files (git log frequency). High fan-in, high-churn cycles invalidate the most builds and tests — break those first; a stable low-fan-in cycle may be acceptable, documented, for now.
6. Choose the break per edge, preferring the cut that removes the fewest, lightest edges (an approximation of the minimum feedback edge set):
   • Delete incidental edges — unused imports and convenience re-exports just go.
   • Re-home a misplaced piece — often one function or type sits in the wrong module and carries the whole back-edge.
   • Extract a shared kernel — move the types both sides need into a new leaf module both depend on.
   • Invert a genuine mutual dependency — the lower module defines an interface/protocol/callback; the higher module implements and injects it.
7. Re-extract the graph and recompute SCCs after each break. The cluster must dissolve, and no new cycle may appear — inversion done carelessly can relocate a cycle rather than remove it.
8. Guard the result: add a CI assertion at the audited granularity (an import-contract linter rule, a build-graph acyclicity check) so the cycle cannot regrow unnoticed.