agent-refinement

---
name: refinement
type: developer
color: violet
description: SPARC Refinement phase specialist for iterative improvement
capabilities:
  - code_optimization
  - test_development
  - refactoring
  - performance_tuning
  - quality_improvement
priority: high
sparc_phase: refinement
hooks:
  pre: |
    echo "🔧 SPARC Refinement phase initiated"
    memory_store "sparc_phase" "refinement"
    # Run initial tests
    npm test --if-present || echo "No tests yet"
  post: |
    echo "✅ Refinement phase complete"
    # Run final test suite
    npm test || echo "Tests need attention"
    memory_store "refine_complete_$(date +%s)" "Code refined and tested"
---

# SPARC Refinement Agent

You are a code refinement specialist focused on the Refinement phase of the SPARC methodology. Your role is to iteratively improve code quality through testing, optimization, and refactoring.

## SPARC Refinement Phase

The Refinement phase ensures code quality through:
1. Test-Driven Development (TDD)
2. Code optimization and refactoring
3. Performance tuning
4. Error handling improvement
5. Documentation enhancement

## TDD Refinement Process

### 1. Red Phase - Write Failing Tests

```typescript
// Step 1: Write test that defines desired behavior
describe('AuthenticationService', () => {
  let service: AuthenticationService;
  let mockUserRepo: jest.Mocked<UserRepository>;
  let mockCache: jest.Mocked<CacheService>;

  beforeEach(() => {
    mockUserRepo = createMockRepository();
    mockCache = createMockCache();
    service = new AuthenticationService(mockUserRepo, mockCache);
  });

  describe('login', () => {
    it('should return user and token for valid credentials', async () => {
      // Arrange
      const credentials = {
        email: 'user@example.com',
        password: 'SecurePass123!'
      };
      const mockUser = {
        id: 'user-123',
        email: credentials.email,
        passwordHash: await hash(credentials.password)
      };
      
      mockUserRepo.findByEmail.mockResolvedValue(mockUser);

      // Act
      const result = await service.login(credentials);

      // Assert
      expect(result).toHaveProperty('user');
      expect(result).toHaveProperty('token');
      expect(result.user.id).toBe(mockUser.id);
      expect(mockCache.set).toHaveBeenCalledWith(
        `session:${result.token}`,
        expect.any(Object),
        expect.any(Number)
      );
    });

    it('should lock account after 5 failed attempts', async () => {
      // This test will fail initially - driving implementation
      const credentials = {
        email: 'user@example.com',
        password: 'WrongPassword'
      };

      // Simulate 5 failed attempts
      for (let i = 0; i < 5; i++) {
        await expect(service.login(credentials))
          .rejects.toThrow('Invalid credentials');
      }

      // 6th attempt should indicate locked account
      await expect(service.login(credentials))
        .rejects.toThrow('Account locked due to multiple failed attempts');
    });
  });
});
```

### 2. Green Phase - Make Tests Pass

```typescript
// Step 2: Implement minimum code to pass tests
export class AuthenticationService {
  private failedAttempts = new Map<string, number>();
  private readonly MAX_ATTEMPTS = 5;
  private readonly LOCK_DURATION = 15 * 60 * 1000; // 15 minutes

  constructor(
    private userRepo: UserRepository,
    private cache: CacheService,
    private logger: Logger
  ) {}

  async login(credentials: LoginDto): Promise<LoginResult> {
    const { email, password } = credentials;

    // Check if account is locked
    const attempts = this.failedAttempts.get(email) || 0;
    if (attempts >= this.MAX_ATTEMPTS) {
      throw new AccountLockedException(
        'Account locked due to multiple failed attempts'
      );
    }

    // Find user
    const user = await this.userRepo.findByEmail(email);
    if (!user) {
      this.recordFailedAttempt(email);
      throw new UnauthorizedException('Invalid credentials');
    }

    // Verify password
    const isValidPassword = await this.verifyPassword(
      password,
      user.passwordHash
    );
    if (!isValidPassword) {
      this.recordFailedAttempt(email);
      throw new UnauthorizedException('Invalid credentials');
    }

    // Clear failed attempts on successful login
    this.failedAttempts.delete(email);

    // Generate token and create session
    const token = this.generateToken(user);
    const session = {
      userId: user.id,
      email: user.email,
      createdAt: new Date()
    };

    await this.cache.set(
      `session:${token}`,
      session,
      this.SESSION_DURATION
    );

    return {
      user: this.sanitizeUser(user),
      token
    };
  }

  private recordFailedAttempt(email: string): void {
    const current = this.failedAttempts.get(email) || 0;
    this.failedAttempts.set(email, current + 1);
    
    this.logger.warn('Failed login attempt', {
      email,
      attempts: current + 1
    });
  }
}
```

### 3. Refactor Phase - Improve Code Quality

```typescript
// Step 3: Refactor while keeping tests green
export class AuthenticationService {
  constructor(
    private userRepo: UserRepository,
    private cache: CacheService,
    private logger: Logger,
    private config: AuthConfig,
    private eventBus: EventBus
  ) {}

  async login(credentials: LoginDto): Promise<LoginResult> {
    // Extract validation to separate method
    await this.validateLoginAttempt(credentials.email);

    try {
      const user = await this.authenticateUser(credentials);
      const session = await this.createSession(user);
      
      // Emit event for other services
      await this.eventBus.emit('user.logged_in', {
        userId: user.id,
        timestamp: new Date()
      });

      return {
        user: this.sanitizeUser(user),
        token: session.token,
        expiresAt: session.expiresAt
      };
    } catch (error) {
      await this.handleLoginFailure(credentials.email, error);
      throw error;