refactor

Refactor code in the EASI codebase — from single-file code health improvements to multi-file architectural changes.

Philosophy: Always pursue optimal code health (10.0). Refactoring is not optional — every file should reach 10.0 unless the complexity is inherent to the domain model or architectural pattern.

Usage: /refactor <file-or-directory> or /refactor --scope=architecture

Arguments:

• •file(s): Files to analyze and refactor (single-file mode)
• •directory or package: Directory to analyze for structural patterns (multi-file mode)
• •--scope=architecture: Cross-context architectural analysis (architecture mode)
• •No argument: prompt the user

Before You Start

Remind the user: commit or stash any uncommitted work before refactoring. Refactoring should always start from a clean working tree so changes can be reviewed and reverted cleanly.

Steps

1. Identify target and mode

Parse $ARGUMENTS to determine the refactoring mode:

2. Analyze

Run analysis appropriate to the mode. Use codescene-refactoring.md as references throughout.

Single-file mode

1. •CodeScene code health: Run mcp__codescene__code_health_score and mcp__codescene__code_health_review on the file.
2. •Read the file to understand the full context.
3. •Domain analysis: Check for:
   • •Logic in the wrong layer (business logic in projectors/handlers, infrastructure in domain)
   • •Primitive obsession (string/int where a value object should exist)
   • •Aggregate doing too much (mixed responsibilities)
   • •Missing or misplaced validation
   • •Anemic domain models and complex read models

Multi-file mode

1. •Glob for all source files in the directory.
2. •CodeScene code health on each file — all files below 10.0 must be refactored.
3. •Structural analysis: Check for:
   • •Layer violations (domain importing infrastructure, handler containing business logic)
   • •Duplicated patterns across files that indicate a missing abstraction
   • •Inconsistent naming or organization vs project conventions
   • •Anemic domain models and complex read models
   • •Read model / projector alignment (does each projector serve exactly one read model?)

Architecture mode

1. •Cross-context coupling: Grep for imports between bounded contexts that bypass published language packages.
2. •SQL join analysis: Look for SQL queries that join tables owned by different contexts.
3. •Published language gaps: Check if events and shared types are properly exposed via publishedlanguage packages.
4. •ACL compliance: Verify anti-corruption layers exist where contexts communicate.
5. •Cache projector coverage: Check if cross-context data needs are served by local cache projectors rather than direct queries.

3. Classify findings

Classify each finding into a priority:

Goal: All files must reach 10.0 Code Health. Only skip findings that are inherent to the domain model or architectural pattern (see codescene-refactoring.md for examples). For everything else, iterate until resolved.

4. Execute refactoring

Follow these rules:

General:

• •Preserve all existing behavior — refactoring only, no functional changes
• •Respect project code style (no added comments, no over-engineering)

CodeScene-driven:

• •Re-check with mcp__codescene__code_health_score after changes
• •Iterate until all files reach 10.0 or until only inherent domain/architectural complexity remains

Domain/Architectural:

• •When moving code between files, ensure all references are updated
• •When creating new files (migrations, projectors), follow existing naming conventions
• •When modifying events or published language, check all subscribers

"DRY = Knowledge, Not Code":

• •Only extract shared abstractions when the duplicated code represents the same business concept
• •Structurally similar code that serves different purposes should remain separate

6. Verify

• •Backend changes: Run go build ./... and go test ./... (or scoped to affected packages)
• •Frontend changes: Run npm run build and npm test -- --run
• •Both: Run both verification suites
• •If verification fails, fix the issue before continuing

7. Report

## Refactoring Complete: <target>

### Changes Applied
| # | File | Change | Before | After |
|---|------|--------|--------|-------|
| 1 | path | description | score/state | score/state |

### Code Health Summary (if applicable)
Before: <original-score(s)>
After:  <final-score(s)>

### Remaining Items (only if inherent to architecture)
- <any findings classified as Skip with detailed justification>

### Checklist
- [ ] All changes are behavior-preserving
- [ ] Build passes
- [ ] Tests pass
- [ ] No new cross-context coupling introduced

Handling Inherent Complexity

Stop and discuss with the user if:

• •The refactoring would require changing public API contracts (breaking change)

Rules

• •Never exclude test files from analysis unless explicitly asked