Deep Refactor

Phase 0: Scope Identification

Before touching code, identify the scope of the refactoring.

1. If `.claude/parallel-zones.md` exists — find which zone owns the target files
2. If cross-zone: split into per-zone sub-tasks, execute sequentially
3. Record scope in your plan

Phase 1: Discovery (GitNexus Audit)

Map the full scope before changing anything.

Step 1: Find all symbols in scope
  gitnexus_query({query: "<target area description>"})
  → Note execution flows, symbol counts, cluster cohesion

Step 2: For each candidate symbol, check blast radius
  gitnexus_impact({target: "symbolName", direction: "upstream"})
  → Record: direct callers (d=1), indirect deps (d=2), risk level

Step 3: Cross-check with grep
  Grep for `from.*<module>` and `import.*<symbol>` to catch dynamic refs
  GitNexus misses string-based imports, re-exports, and dynamic requires

Step 4: Capture baseline metrics
  - File count in scope
  - Total LOC (wc -l)
  - Symbol count from GitNexus
  - Number of cross-module dependencies

Output: A ranked list of refactoring targets with risk levels and consumer counts.

Phase 2: Plan

Write the refactoring plan as 3 sequential passes. Each pass has a specific focus — do NOT mix concerns across passes.

Pass 1 — Structure (move / extract / delete)

Change where code lives without changing what it does.

- Delete dead code (0 consumers confirmed by GitNexus + grep)
- Extract shared logic into dedicated modules
- Colocate code with its single consumer
- Move files to correct directories
- Update all import paths

Verification after Pass 1:

# Run your project's type checker
# Run gitnexus_detect_changes({scope: "all"})

Pass 2 — Interfaces (signatures / types / contracts)

Simplify how modules talk to each other.

- Reduce exported surface area (unexport internals)
- Simplify function signatures (fewer params, better types)
- Replace loose types with stricter ones
- Consolidate duplicate type definitions
- Rename for clarity (use gitnexus_rename, never find-and-replace)

Verification after Pass 2:

# Same type-check + lint as Pass 1
# Plus: run tests for all affected execution flows
# gitnexus_detect_changes({scope: "all"})

Pass 3 — Internals (logic simplification)

Improve code inside functions without changing their signatures.

- Simplify conditional logic
- Remove unnecessary abstractions
- Replace verbose patterns with idiomatic alternatives
- Reduce nesting depth
- Improve error messages

Verification after Pass 3:

# Full test suite for the scope
# Final detect_changes to confirm scope
# gitnexus_detect_changes({scope: "all"})

Phase 3: Execute (Double Iteration)

Every pass is executed twice. The first iteration does the heavy lifting; the second iteration reviews what the first produced and catches anything that was missed, could be cleaner, or introduced new opportunities.

For each pass (1, 2, 3):
  Iteration A — Primary changes
    1. Execute the pass
    2. Verify (type-check + lint + tests)
    3. Commit: `refactor: pass N.a — <description>`

  Iteration B — Review & polish
    1. Re-read every file touched in iteration A
    2. Look for: missed opportunities, inconsistencies introduced by A,
       further simplifications now possible, naming that could be better
    3. Apply fixes
    4. Verify (type-check + lint + tests)
    5. Commit: `refactor: pass N.b — <description>`

  Proceed directly to next pass — no user approval gate between passes.

After ALL passes complete → report full metrics to user for review.

No feedback gates between passes. The skill runs all 3 passes (6 iterations) autonomously. The only user checkpoint is at the end (Phase 4 metrics report).

Why Two Iterations

• Iteration A focuses on the planned changes — it's goal-directed
• Iteration B focuses on the result of those changes — it's quality-directed
• First-pass refactoring always leaves residue: imports that could be tighter, names that made sense before the move but not after, patterns that only become visible once the structure is cleaner

Execution Rules

• One pass at a time. Never mix structural changes with interface changes.
• Two iterations per pass. Never skip iteration B — it's where quality comes from.
• Commit per iteration. Each iteration (A and B) gets its own commit, independently revertible.
• Stop on failure. If tests break, fix before continuing — never skip to next pass.
• Re-audit between passes. Run gitnexus_detect_changes() to confirm scope hasn't drifted.

Phase 4: Metrics & Report

After all passes complete, produce a before/after comparison:

| Metric                    | Before | After | Delta |
|---------------------------|--------|-------|-------|
| Files in scope            |        |       |       |
| Lines of code             |        |       |       |
| Exported symbols          |        |       |       |
| Cross-module dependencies |        |       |       |
| Dead code files           |        |       |   0   |
| GitNexus risk assessment  |        |       |       |

Safety Checks

Integration with Other Skills

• Before planning: Use this skill's Phase 0-1 for discovery
• For parallel work: Reference .claude/parallel-zones.md to run multiple deep-refactors in separate worktrees on independent zones