Cycle / tangle reduction

The problem

The first time you ran the cycle finder on the legacy codebase, it showed 47 groups. You cannot fix 47 things this sprint. Some contain dependency seams you can refactor. Some are precise Intentional or Debt decisions worth recording with a reason. Others pass through a familiar broad area you simply want out of the way while you inspect the rest. You need a plan, and you need a way to know whether next sprint the number went up or down.

Why it matters

A raw cycle count does not tell you whether the team removed a harmful dependency seam, recorded a deliberate exception, or merely changed the grouping shape. A useful reduction pass turns ungoverned cycle evidence into concrete outcomes: refactored seams, precise Intentional or Debt decisions, and a smaller unresolved problem graph. Safe Havens keep familiar broad regions from obscuring the current investigation without becoming repository policy.

Where to start

Begin with the Topology Graph with the Cycles section enabled.

Step by step

1. Isolate the problem graph.

   Start exploring opens Topology with Only cycles, Hide isolated, and the Instability heatmap active. On a large model, temporarily use Roll up deep packages to read the broad cycle shape, then increase the depth before planning a refactor.

2. Step through each group using the navigator.

   Use the lower-left Cyclic Dependency Groups panel or cycle-group navigator to isolate one group at a time. For each group, follow the concrete dependency references that hold the loop together and identify a practical seam to change.

3. Compare broadly, then expand the seam.

   Use Collapse All to compare module roots. Choose Expand completely only on the module whose cycle shape needs package-level inspection.

4. Classify the group.

   For each cycle group, decide what kind of action will help: refactor a concrete dependency seam; record precise Intentional or Debt treatment with a reason; or declutter cycles through a familiar package or source folder whose broad signal obscures the rest.

5. Act on the classification.

   For a design problem, inspect the concrete references holding the group together and choose the dependency seam to refactor. Use Record cycle decision when you want fine-grained Intentional or Debt treatment with a required reason and optional ticket you can find and review later. For a broad familiar area, right-click its package or source folder and choose Allow cycles through this package or source folder; AtlasArc remembers that Safe Haven as workspace decluttering. Commit .atlasarc/governance/cycles.json when other developers and CI should use the same precise decisions.

6. Record what changed.

   At the end of the session, distinguish groups removed by refactoring, precise decisions now governed as Intentional or Debt, broad areas locally decluttered with Safe Havens, and ungoverned groups that still need attention. Track that outcome alongside the remaining problem-group count.

Interpreting results

Ungoverned dependency cycles are the findings this workflow reduces. The remaining problem-group count is useful trajectory evidence, but grouping can change as code is refactored and deliberately retained cycles may be governed rather than removed. Read the trend together with the actual seams broken, the decisions recorded, and any new ungoverned groups. The strongest outcome is not a cosmetically smaller number; it is a smaller unresolved problem graph with reasons for what remains.

Export & share

Generate a Current investigation Architecture Report at the end of the pass to preserve the cycle-only view and its active filters. Cycle Evidence records the current problem groups; enable full individual cycle-group maps when the review needs them, and add Governance audit only when the decision register and rationale belong in the packet.