Audit individual cycle groups

The problem

You ran the cycle finder and got 23 groups. Some contain two packages. One has twelve. You do not need to fix all of them before the sprint ends, but you do need to make a call on each one. Work through the evidence now and you will not have to start from zero the next time these cycles come up.

Why it matters

When every cycle looks like the same red warning, you cannot tell what to break, what is intentional, what belongs in the debt backlog, or which broad known area is simply getting in your way. Work through the groups one at a time and you turn that pile into decisions you can search, revisit, refactor, or share when you are ready.

Where to start

Begin with the Topology Graph with the Cycles section enabled.

Step by step

1. Isolate architectural cycle groups.

   Switch to Topology, enable Only cycles with Hide isolated on, and select Architectural in the detail-level control. This begins with architectural and aggregation groups while hiding nested cycles and Safe Haven context. Press ▶ to focus Cycle 1.

2. Adjust detail only when needed.

   If the focused group still contains too many deep packages, enable Roll up deep packages temporarily to read its broad shape. Increase the depth again before choosing an exact dependency seam or editing code.

3. Assess each group's structure.

   Check how many packages it involves and inspect a concrete dependency example holding the loop together. Compare that evidence with the layers and boundaries you intended. AtlasArc shows the cycle shape and evidence; you decide whether it conflicts with the architecture you want.

4. Choose what to do with the evidence.

   Refactor when the cycle conflicts with your intended architecture. Record a precise Intentional or Debt decision when you want a reason, optional ticket, search, and lifecycle review. Use a Safe Haven when cycles through a broad known package or source-folder area should stay out of your workspace cycle view.

5. Keep local decisions local, or share them when useful.

   A cycle-governance record is useful without a commit. Commit .atlasarc/governance/cycles.json when you want to share and version the decisions or apply them in AtlasArc.io CI. Safe Havens remain remembered workspace decluttering rather than repository policy.

6. Move through the remaining groups.

   Press ▶ to advance until the architectural groups are triaged. Then select Nested & architectural to review the yellow nested clusters. In the Cycle Groups panel, uncheck groups you have completed when you need to reduce visual clutter without changing their evidence or governance.

Interpreting results

Architectural, aggregation, and nested are AtlasArc classifications of the cycle evidence. An ungoverned dependency cycle is the native finding; an Intentional or Debt record is a reasoned response to precise evidence, and a Safe Haven is workspace visibility treatment for a broad known area. Your intended architecture still tells you which boundary matters most and which concrete refactor to tackle first. For a large group, look for the one or two linchpin dependencies that would collapse the loop if removed or inverted.

Export & share

For a single group, use Snapshot as PNG with Only cycles active. For a larger pass, generate a Current investigation Architecture Report; Cycle Evidence captures the current problem groups, full individual cycle-group maps add detail for larger groups, and Governance audit adds the complete decision register when it belongs in the review.