{
  "version": "act 1.0.17",
  "slug": "architectural-refactoring",
  "name": "architectural-refactoring",
  "description": "Execute structural decompositions based on an architectural analysis report. Use when breaking circular dependencies, splitting god classes, reducing coupling between modules, extracting interfaces at seam boundaries, or executing any large-scale structural change identified in an architectural analysis. Requires the architectural-analysis skill to have been run first.",
  "url": "https://act101.ai/docs/skills/architectural-refactoring",
  "body_md": "# Architectural Refactoring with act\n\nExecute structural decompositions based on an architectural analysis report.\n\n## Prerequisites\n\nThe `architectural-analysis` report must exist at `docs/architectural-analysis-report.md`.\nIf it doesn't exist, run the `architectural-analysis` skill first.\n\n## Rules\n\n1. **Start from the report** \u2014 Read the analysis report first. Every refactoring decision should trace back to a finding in the report.\n\n2. **Find seams, don't invent them** \u2014 Use `act analyze seams` to identify natural boundaries. Refactor along these boundaries, not against them.\n\n3. **Evaluate before cutting** \u2014 Before extracting a module, use `act analyze surface --files <files>` to measure the API surface. If the surface is too wide, the extraction will create more coupling, not less.\n\n4. **Break cycles first** \u2014 Circular dependencies are the highest priority. Use `act analyze cycles` to find them, then break the simplest edge in each cycle.\n\n5. **Extract interfaces at seams** \u2014 At each seam boundary, extract an interface that both sides depend on. Use `act query interface <file>` to understand the current API, then `act refactor extract-interface` to create it.\n\n6. **Stable foundations first** \u2014 Start with the most stable modules (lowest instability in `act analyze coupling`). Make them independent before touching unstable modules.\n\n7. **Measure coupling reduction** \u2014 After each refactoring step, re-run `act analyze coupling` and `act analyze cycles` to verify that coupling decreased and cycles were broken.\n\n8. **Use dead code analysis for cleanup** \u2014 Before and after each major refactoring, run `act analyze dead-code` to identify symbols that are no longer needed.\n\n9. **Document the architecture** \u2014 After each major change, update the analysis report by re-running `architectural-analysis`.\n\n10. **Incremental, verifiable steps** \u2014 Each refactoring step should be small enough to verify independently. Commit after each step. Never make multiple structural changes at once.\n\n## Workflow\n\n1. Read the analysis report\n2. Prioritize findings: cycles > god classes > high coupling > dead code\n3. For each finding:\n   a. Verify it's still present (`act analyze cycles` / `act analyze coupling`)\n   b. Plan the refactoring (identify seams, measure surface)\n   c. Execute the refactoring using `act refactor` operations\n   d. Verify the fix (re-run analysis, check tests)\n   e. Commit\n\n## Delegation\n\n- Use `refactoring` skill for individual operations (rename, extract, move)\n- Use `code-generation` skill for scaffolding new modules\n- Use `code-navigation` skill to understand code before modifying it\n\n## Token-Saving Hints\n\n- Use `act analyze cycles` with `--max-length 3` to focus on the tightest cycles first\n- Use `act analyze coupling --threshold 0.7` to focus on the most unstable modules\n- Use `act query skeleton` instead of reading full files\n- Re-run only the specific analysis that your change affects, not the full suite"
}