Refactor Technical Debt

Step 1: Audit the Code

Before refactoring, quantify the problem. Run /agile-explore-audit to get hard numbers.

/agile-explore-audit scope="code" target="UserService"

Code Audit — UserService.java
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📏 Size
   Lines of code: 500
   Methods: 23
   Dependencies injected: 7

🎯 Single Responsibility (SRP) — VIOLATION
   Detected 8 responsibility clusters:
   1. User CRUD (create, read, update, delete)
   2. Password management (hash, reset, validate)
   3. Email validation (format, uniqueness, domain)
   4. Permission checks (hasRole, canAccess, isAdmin)
   5. Notification dispatch (welcome email, password reset email)
   6. Profile image handling (upload, resize, delete)
   7. Audit logging (logAction, getHistory)
   8. Session management (createSession, invalidate)

📊 Complexity
   Cyclomatic complexity: 24 (threshold: 10)
   Deepest nesting: 5 levels
   Longest method: 67 lines (updateUserProfile)

🔁 Duplication
   3 duplicated blocks detected:
   - Email validation logic (lines 89-102, 234-247, 401-414)

🧪 Test Coverage
   Coverage: 62% (threshold: 80%)
   Uncovered: notification dispatch, session management

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Risk: HIGH — Refactoring recommended before adding features

Step 2: Create Refactoring Stories

Refactoring is real work. It goes into the sprint backlog as stories with estimates.

/agile-story-create

Step 3: Create the Refactoring Branch

Create a feature branch for the refactoring work using /agile-code-branch.

/agile-code-branch

→ Created branch: refactor/REFAC-01-split-user-service from develop

Step 4: Refactor with Tidy First

Run /agile-code-refactor and follow the Tidy First approach: one small structural transformation at a time, each followed by a commit and a green test suite.

/agile-code-refactor target="UserService" approach="tidy-first"

class UserService {
  // ... 23 methods, 8 responsibilities
  void validateEmail(String email) { ... }
  void validatePassword(String pw) { ... }
  void validateUsername(String name) { ... }
  // ... everything else
}

class UserValidator {
  void validateEmail(String email) { ... }
  void validatePassword(String pw) { ... }
  void validateUsername(String name) { ... }
}

class UserService {
  private final UserValidator validator;
  // ... remaining methods
}

/agile-code-ci

Unit Tests ........... ✅ 247/247 passing
Integration Tests .... ✅ 18/18 passing
All tests GREEN ✅

/agile-code-commit

refactor(user): extract UserValidator from UserService

class UserNotificationService {
  void sendWelcomeEmail(User user) { ... }
  void sendPasswordResetEmail(User user, String token) { ... }
  void sendAccountLockedEmail(User user) { ... }
}

class UserService {
  private final UserValidator validator;
  private final UserNotificationService notifications;
  // ... remaining methods
}

/agile-code-ci

Unit Tests ........... ✅ 247/247 passing
Integration Tests .... ✅ 18/18 passing
All tests GREEN ✅

/agile-code-commit

refactor(user): extract UserNotificationService from UserService

class UserPermissionService {
  boolean hasRole(User user, Role role) { ... }
  boolean canAccess(User user, Resource resource) { ... }
  boolean isAdmin(User user) { ... }
}

class UserService {
  private final UserValidator validator;
  private final UserNotificationService notifications;
  private final UserPermissionService permissions;
  // ... now only CRUD + password + profile + audit + session
}

/agile-code-ci

Unit Tests ........... ✅ 247/247 passing
Integration Tests .... ✅ 18/18 passing
All tests GREEN ✅

/agile-code-commit

refactor(user): extract UserPermissionService from UserService

Step 5: CI After EACH Transformation

Step 6: Commit Convention

Every refactoring commit uses the refactor type and describes the structural change. No behavioral changes allowed.

abc1234 refactor(user): extract UserValidator from UserService
def5678 refactor(user): extract UserNotificationService from UserService
ghi9012 refactor(user): extract UserPermissionService from UserService

Step 7: Code Review

Submit the refactoring PR for review.

/agile-code-review

Review — refactor(user): split UserService into focused services
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Reviewer: @lead
Checklist:
  ✅ No behavioral changes (same inputs → same outputs)
  ✅ SOLID principles improved (SRP compliance)
  ✅ All 247 tests pass — no test modifications needed
  ✅ Each commit is atomic and independently revertible
  ✅ Dependency injection wired correctly

Comment: "Clean extraction. UserService is now focused on CRUD.
  Consider extracting session management next sprint."

Verdict: ✅ APPROVED

Step 8: Merge the Refactoring Branch

After approval, merge the refactoring branch back to develop using /agile-code-merge.

/agile-code-merge

Merge — refactor/REFAC-01-split-user-service → develop
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Strategy: --no-ff (preserves branch history)
Result .................. ✅ merged to develop
Cleanup ................. ✅ branch deleted
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Refactoring branch merged and cleaned up

Results: Before vs. After

The Tidy First Principle

What You Practiced

• 🔍 /agile-explore-audit to quantify tech debt with hard numbers
• 📋 /agile-story-create to track refactoring as real sprint work
• 🌿 /agile-code-branch to create a dedicated refactoring branch
• 🔧 /agile-code-refactor with Tidy First approach — one extraction at a time
• ⚙️ /agile-code-ci after EVERY transformation to catch breaks immediately
• 💾 /agile-code-commit with structural-only commits (refactor(scope): description)
• 👀 /agile-code-review verifying no behavioral changes leaked in
• 🔀 /agile-code-merge to merge the approved refactoring back to develop