| name | elixir-cyclic-dependencies |
| description | Detects and removes cyclic compile-time dependencies in Elixir codebases using mix xref, with minimal code changes. Use when the user explicitly asks to check for cycles, remove cyclic dependencies, or fix xref cycle failures. Requires Elixir 1.19 or higher for accurate results. |
Elixir Cyclic Dependencies
When to Use
Apply this skill only when the user explicitly asks to check or remove cyclic dependencies (e.g. "check for cycles", "remove cyclic dependencies", "fix xref cycles").
Prerequisite: Elixir Version
Cycle detection is correct only on Elixir 1.19 or higher. Before running any cycle checks:
- Verify version:
elixir -v or inside the project run mix run -e 'IO.inspect(System.version())'.
- If the version is below 1.19, stop and inform the user that upgrading to Elixir 1.19+ is required for reliable cycle detection.
Detecting Cycles
Run both commands from the project root. Start with a relaxed threshold, then tighten:
mix xref graph --format cycles --label compile-connected --fail-above 3
mix xref graph --format cycles --label compile --fail-above 3
- compile-connected: cycles in the compile-time dependency graph (modules that compile in a cycle).
- compile: same graph, different label; both should be run.
- --fail-above N: exit code fails when cycle count is above N. Use
3 initially, goal is 0.
To list cycles without failing (for inspection), omit --fail-above or set it high:
mix xref graph --format cycles --label compile-connected
mix xref graph --format cycles --label compile
Goal: reach --fail-above 0 for both commands (no cycles).
Workflow
- Check Elixir version (must be ≥ 1.19).
- Establish baseline: run both xref commands with
--fail-above 3 (or current project setting). Note cycle count and which modules appear in cycles.
- Inspect cycles: run without
--fail-above to see full cycle output; identify the smallest set of edges (module A → module B) that, if removed, break cycles.
- Plan minimal changeset:
- Prefer breaking a single dependency (e.g. move shared code to a new module both can depend on) over large refactors.
- Helper modules are allowed if they yield the smallest change: extract shared logic into a new module that the cycle participants depend on, so the cycle is broken.
- Avoid duplication; follow existing repository guidelines (e.g. AGENTS.md, .cursor rules) and prior patterns in the codebase.
- Implement: make the chosen change, then re-run both xref commands with
--fail-above 0 (or gradually lower from 3 → 0).
- Verify:
mix compile --warnings-as-errors, tests, and any project lint (e.g. mix lint or mix cyclecheck if defined).
Minimal-Change Strategies
| Strategy | When to use |
|---|
| Extract helper module | Two or more modules in a cycle need the same logic; extract it to a new module that has no dependency back on the cycle. |
| Move code down | Move a function from module A to module B so that A no longer depends on B (or vice versa), breaking the cycle. |
| Invert dependency | If A uses B and B uses A, see if one usage can be replaced by a callback, option, or data structure so only one direction remains. |
| Split module | One module has two distinct responsibilities and participates in two cycles; split into two modules to break cycles. |
Choose the option that removes cycles with the least code churn and no new duplication.
Project Integration
If the project has a cyclecheck (or similar) task in mix.exs, use it after changes:
mix cyclecheck
Ensure it runs both xref commands with the target --fail-above 0 once cycles are cleared.
Summary Checklist
