name: architecture-cleanup
description: Systematic codebase cleanup and refactoring. Takes analysis findings and executes improvements in parallel-safe batches. Follows TDD approach - tests first, then refactor.
license: MIT
metadata:
author: thesimpleapp
version: "1.0"

Architecture Cleanup

Transform messy codebases into clean, maintainable architecture.

Philosophy

1. UNDERSTAND before changing
2. TEST before refactoring
3. SMALL STEPS that can be reverted
4. PARALLEL SAFE batch execution
5. VERIFY after each change

The Cleanup Workflow

┌─────────────────────────────────────────────────────┐
│                    CLEANUP CYCLE                     │
├─────────────────────────────────────────────────────┤
│  1. INVENTORY  → List all issues from analysis      │
│  2. PRIORITIZE → Sort by impact and dependencies    │
│  3. BATCH      → Group into parallel-safe sets      │
│  4. TEST       → Write/verify tests for each area   │
│  5. REFACTOR   → Execute changes                    │
│  6. VERIFY     → Run tests, review changes          │
│  7. COMMIT     → Small, atomic commits              │
│  8. REPEAT     → Next batch                         │
└─────────────────────────────────────────────────────┘

Phase 1: Inventory

Create cleanup checklist from analysis:

## Cleanup Inventory

### Critical (Do First)
- [ ] Fix security vulnerability in AuthService
- [ ] Remove exposed API keys in config

### High Priority
- [ ] Split UserDashboard.tsx (523 lines → 5 components)
- [ ] Add error handling to API calls
- [ ] Fix N+1 query in user list

### Medium Priority
- [ ] Standardize folder structure
- [ ] Extract shared hooks
- [ ] Update outdated dependencies

### Low Priority
- [ ] Remove console.logs
- [ ] Fix TODO comments
- [ ] Improve naming consistency

Phase 2: Prioritization Matrix

                 HIGH IMPACT
                      │
     ┌────────────────┼────────────────┐
     │                │                │
     │   SCHEDULE     │   DO FIRST     │
     │   (Plan for    │   (Quick wins  │
     │    sprint)     │    + critical) │
     │                │                │
LOW ─┼────────────────┼────────────────┼─ HIGH
EFFORT                │                   EFFORT
     │                │                │
     │   DELEGATE     │   PLAN         │
     │   (Automate    │   (Major       │
     │    or skip)    │    refactors)  │
     │                │                │
     └────────────────┼────────────────┘
                      │
                 LOW IMPACT

Phase 3: Batching for Parallel Execution

Batch Rules

SAFE to parallelize:
✓ Changes in different features/modules
✓ Independent file extractions
✓ Non-overlapping refactors

NOT safe to parallelize:
✗ Changes to shared utilities
✗ Dependency updates
✗ Core architecture changes

Batch Example

## Batch 1 (Parallel Safe)
Agent A: Refactor AuthFeature
Agent B: Refactor UserFeature
Agent C: Refactor SettingsFeature

## Batch 2 (Sequential - touches shared)
- Update shared utilities
- Update shared hooks

## Batch 3 (Parallel Safe)
Agent A: Add tests for AuthFeature
Agent B: Add tests for UserFeature
Agent C: Add tests for SettingsFeature

Phase 4: TDD Approach

For Each Refactor

1. CHARACTERIZATION TEST
   - Write test that captures current behavior
   - Even if behavior is wrong, test it first

2. REFACTOR
   - Make changes
   - Keep tests green

3. IMPROVE
   - Now fix any incorrect behavior
   - Update tests to reflect correct behavior

Example: Splitting a God Component

// BEFORE: Test current behavior
describe('UserDashboard', () => {
  it('renders user info', () => {
    render(<UserDashboard user={mockUser} />);
    expect(screen.getByText(mockUser.name)).toBeInTheDocument();
  });

  it('renders stats section', () => { /* ... */ });
  it('renders activity feed', () => { /* ... */ });
});

// AFTER: Same tests pass, code is split
// - UserInfo component
// - UserStats component
// - ActivityFeed component
// - UserDashboard (composition)

Phase 5: Refactoring Patterns

Extract Component (React)

// BEFORE: 500 line component
function UserDashboard() {
  // 100 lines of header logic
  // 150 lines of stats logic
  // 200 lines of feed logic
  // 50 lines of rendering
}

// AFTER: Composed components
function UserDashboard() {
  return (
    <Layout>
      <UserHeader />
      <UserStats />
      <ActivityFeed />
    </Layout>
  );
}

Extract Widget (Flutter)

// BEFORE: 400 line widget
class UserDashboard extends StatelessWidget {
  // Everything in one build method
}

// AFTER: Composed widgets
class UserDashboard extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        UserHeader(user: user),
        UserStats(stats: stats),
        ActivityFeed(activities: activities),
      ],
    );
  }
}

Repository Pattern Introduction

// BEFORE: Direct API calls in component
function UserProfile() {
  useEffect(() => {
    fetch('/api/user').then(/* ... */);
  }, []);
}

// AFTER: Repository abstraction
// repositories/userRepository.ts
export const userRepository = {
  getUser: async (id: string) => {
    return supabase.from('users').select('*').eq('id', id);
  }
};

// hooks/useUser.ts
export function useUser(id: string) {
  return useQuery(['user', id], () => userRepository.getUser(id));
}

// components/UserProfile.tsx
function UserProfile({ userId }) {
  const { data: user } = useUser(userId);
}

Phase 6: Verification

After each batch:

# Run tests
npm test / flutter test

# Run linting
npm run lint / flutter analyze

# Type check
npm run typecheck / dart analyze

# Build check
npm run build / flutter build

Phase 7: Commit Strategy

Commit Per Refactor

# Each refactor = one commit
git commit -m "refactor(auth): extract LoginForm component"
git commit -m "refactor(auth): add error handling to login"
git commit -m "test(auth): add LoginForm unit tests"

Commit Message Format

<type>(<scope>): <description>

Types: refactor, fix, test, chore, docs
Scope: feature or module name

Cleanup Session Template

## Cleanup Session: [Date]

### Goals
- [ ] Complete Batch 1 refactors
- [ ] Achieve 80% test coverage on auth

### Completed
- [x] Split UserDashboard into 5 components
- [x] Add error handling to API calls

### Blocked
- Config refactor blocked by env variable issue

### Next Session
- Complete Batch 2
- Address blocked items

Integration

After cleanup:
- Run /project-init to update CLAUDE.md
- Run /codebase-analysis to verify improvements
- Use framework skills for new development