Workflow: Refactoring at Scale

Overview

This workflow covers large-scale codebase refactoring using Cursor's AI capabilities, including planning, incremental changes, and verification.

When to Use: Major refactors, architecture changes, dependency upgrades, pattern migrations

Prerequisites

Codebase indexed (SOP-009)
Tests available (or plan to add)
Git version control
Familiarity with Plan mode

Workflow Diagram

Phase	Action	Tool
1. Assess Scope	Understand current state	Ask mode
2. Create Plan	Design approach	Plan mode
3. Ensure Tests	Add tests before changing code	Agent
4. Execute	Refactor in small, testable chunks	Agent
5. Verify	Run tests, update docs, remove old code	Agent

Phase 1: Assess Scope

Use Ask mode to understand the current state:

I want to refactor our authentication system from session-based
to JWT-based authentication.

Analyze the codebase and tell me:
1. Which files currently handle authentication?
2. How many places use session-based auth?
3. What would be impacted by this change?
4. What are the risks?

Agent explores and reports:

Files Affected: 23

src/middleware/auth.ts (core logic)
src/routes/*.ts (15 files check session)
src/services/SessionService.ts
src/utils/session.ts
tests/auth.test.ts

Dependencies:

express-session (to remove)
redis (session store - may keep for cache)
Need to add: jsonwebtoken, bcrypt

Risks:

Active user sessions will be invalidated
Need token refresh strategy
Mobile app relies on session cookies

Phase 2: Create Plan

Switch to Plan mode:

Create a detailed plan to refactor from session-based to JWT
authentication.

Requirements:
- Zero downtime during migration
- Support both methods during transition
- Complete migration within 2 weeks
- All tests must pass at each step

Agent creates plan:

markdown

# JWT Migration Plan

## Phase 1: Foundation (No Breaking Changes)
1. Add JWT dependencies
2. Create JWTService with token generation/validation
3. Add new /auth/token endpoints alongside existing
4. Write tests for JWT functionality

## Phase 2: Dual Support
5. Modify auth middleware to accept both session and JWT
6. Update 5 least-used routes to prefer JWT
7. Monitor and verify both work

## Phase 3: Migration
8. Update remaining routes to prefer JWT
9. Add deprecation warnings for session endpoints
10. Update mobile app to use JWT

## Phase 4: Cleanup
11. Remove session dependencies
12. Remove deprecated endpoints
13. Update documentation
14. Final verification

Phase 3: Ensure Test Coverage

Before changing code, ensure you can verify it works:

Analyze test coverage for the authentication system.
Which functions are tested? Which are not?
Create tests for any untested critical paths.

Add missing tests:

Create tests for these untested scenarios:
- Session timeout handling
- Concurrent session detection
- Session invalidation on password change

We need these tests to verify the refactor doesn't break anything.

Phase 4: Execute Incrementally

Small, Verifiable Steps

Step 1: Create JWTService

Create @src/services/JWTService.ts
Add token generation and validation methods
Run tests → Commit: "Add JWTService foundation"

Step 2: Add New Endpoints

Add POST /auth/token (login with JWT)
Add POST /auth/refresh
Run tests → Commit: "Add JWT authentication endpoints"

Step 3: Dual Middleware

Modify auth middleware to check JWT first, then session
Run ALL tests → Commit: "Support both JWT and session auth"

Continue for each step in the plan...

Execute Each Step

Execute step 1 of the plan: Create JWTService

Follow the patterns in @src/services/AuthService.ts
Include comprehensive error handling
Add unit tests

After each step:

Review changes
Run tests: "Run all auth-related tests"
If tests pass, commit
If tests fail, fix before continuing

Phase 5: Verify & Clean Up

Run Full Test Suite

Run all tests and report any failures related to authentication.

Update Documentation

Update the API documentation in @docs/api/ to reflect
the new JWT authentication system.

Include:
- How to obtain tokens
- Token refresh flow
- Migration guide for existing clients

Remove Old Code

Now that all tests pass with JWT, remove:
- Session-related middleware
- Session endpoints (with deprecation period over)
- express-session and redis-session dependencies
- SessionService.ts

Create a commit for this cleanup.

Best Practices

Before Starting

Ensure good test coverage
Create a detailed plan
Communicate with team about scope
Set up feature flags if needed

During Refactoring

Make small, atomic commits
Run tests after each change
Use checkpoints to restore if needed
Keep old and new working simultaneously

After Completing

Run full regression tests
Update all documentation
Clean up old code and dependencies
Monitor for issues after deployment

Common Refactoring Patterns

Pattern	Approach
Rename symbol	Use Agent: "Rename X to Y across the codebase"
Extract function	Select code, Cmd+K: "extract into function called X"
Move file	Agent handles import updates automatically
Change signature	Agent updates all call sites
Update dependency	Plan mode for breaking change analysis

Workflow: Refactoring at Scale ​

Overview ​

Prerequisites ​

Workflow Diagram ​

Phase 1: Assess Scope ​

Phase 2: Create Plan ​

Phase 3: Ensure Test Coverage ​

Phase 4: Execute Incrementally ​

Small, Verifiable Steps ​

Execute Each Step ​

Phase 5: Verify & Clean Up ​

Run Full Test Suite ​

Update Documentation ​

Remove Old Code ​

Best Practices ​

Before Starting ​

During Refactoring ​

After Completing ​

Common Refactoring Patterns ​

Related SOPs ​