refactor

Skill: Architectural Refactor & Decomposition

This standard governs the modernization of legacy code and the surgical decomposition of high-complexity monolithic structures.

1. The "Clean Chain" Strategy

When refactoring, the intent is never "lean" or "minimum viable." We refactor to achieve Strict Concern Separation following the chain: Controller (Package-Private) -> Service (Interface) -> [Client | Repository].

Core Standards

• Single Responsibility (SRP): Any service handling Business Logic AND Data Access MUST be split.
• Immutability Mandate: All legacy POJOs or mutable DTOs must be decomposed into Java Records.
• Visibility Discipline: Move all controllers to package-private visibility during the refactoring process.

2. Golden Sample: Monolithic Service Decomposition

This reference demonstrates the surgical transformation of a "Multifaceted Legacy Class" into an enterprise-grade service triad.

🚫 The "Monolithic" Legacy (300+ Lines)

// Legacy: Handles Validation, DB and API Calls in one file
public class LegacyMonitorService {
    @Autowired private Repos repo;
    public void process(Data d) {
        if (d.getVal() == null) { throw new Err(); } // Inline validation
        repo.save(d); // Direct persistence
        // 50 more lines of logic...
    }
}

✅ The Enterprise "Masterpiece" (Decomposed)

Step 1: The Immutable Schema (Record)

public record ReadingRequest(
    @NotNull Instant timestamp,
    @Positive Double magnitude
) {}

Step 2: The Focused Domain Service

@Service
final class AnomalyService implements MonitorUseCase {
    private final TelemetryRepository repository;

    AnomalyService(TelemetryRepository repository) {
        this.repository = repository;
    }

    @Override
    public void process(ReadingRequest request) {
        // Pure domain logic; Persistence delegated to repository
        repository.saveReading(request); 
    }
}

3. Refactoring Workflow (Gradle)

To ensure that refactoring does not introduce regressions, the agent must follow this Gradle-centric loop:

1. Audit: Read the target file and identify SRP violations.
2. Decompose: Create the new Records and Services in their respective domain packages.
3. Validate: Run the static analysis suite.

   ./gradlew checkstyleMain  # Enforce style boundaries
   ./gradlew test            # Verify logic preservation
   

4. Polish: Perform a final Code Review to ensure no "legacy drift" remains.

4. Resource Resolution

• Java Conventions: Consult Java Standard for records/functional logic.
• Build Logic: Consult Build System for Gradle task definitions.
• Quality Gate: Consult QA Standard for Checkstyle thresholds.