Nw Legacy Refactoring DddSAFE

AI agents that guide you from idea to working code, with you in control at every step.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: nw-legacy-refactoring-ddd
description: DDD-guided legacy refactoring patterns -- strangler fig, bubble context, ACL migration, 14 tactical/strategic/infrastructure patterns, and incremental monolith-to-microservices methodology
user-invocable: false
disable-model-invocation: true
---

# Legacy Refactoring with DDD

Refactoring legacy systems using Domain-Driven Design as the strategic compass. DDD tells you WHERE and WHY to refactor; traditional techniques (progressive-refactoring, mikado-method) tell you HOW.

Principle: "Start simple, grow big" -- incremental steps tested at each stage.

## Decision Framework: Before Refactoring

Ask three questions before any DDD refactoring:
1. **Business value**: what business outcome does refactoring this area enable?
2. **Risk**: what breaks if we refactor vs. if we do not?
3. **Cost**: time, effort, disruption -- is it justified?

### When NOT to Refactor
- System scheduled for replacement
- Stable system with no new development
- Cost exceeds benefit
- Team lacks DDD experience with no learning budget
- Domain is genuinely simple (CRUD-dominated)

### Cynefin-Refactoring Mapping

| Cynefin Domain | Refactoring Approach |
|---------------|---------------------|
| Clear | Apply established patterns directly; standard refactoring catalogs |
| Complicated | Analyze with experts, then apply patterns; multiple valid solutions |
| Complex | Probe with safe-to-fail experiments; EventStorming to discover patterns |
| Chaotic | Act first to stabilize, then refactor; emergency patches acceptable |
| Confusion | Gather information before deciding; avoid premature refactoring |

## Migration Methodology (4 Phases)

### Phase 1: Understand and Stabilize
1. Run EventStorming to map current system (Big Picture)
2. Assess complexity using Cynefin framework
3. Write characterization tests for critical paths (Feathers technique)
4. Identify bounded contexts in existing codebase via language divergence

### Phase 2: Modularize the Monolith
1. Introduce module structure aligned with bounded contexts
2. Use mediator pattern for initial decoupling between modules
3. Apply fitness functions to measure progress (coupling, cohesion, dependency direction)
4. Refactor database schemas toward context alignment

### Phase 3: Introduce Events and CQRS
1. Replace mediator with event-driven communication
2. Implement CQRS for contexts benefiting from read/write separation
3. Split databases per bounded context using expand/contract pattern
4. Use event-based data synchronization for cross-context data needs

### Phase 4: Extract Services (if justified)
1. Evaluate microservices readiness (6 signals below)
2. Start with most independent bounded context
3. Use strangler fig pattern -- incrementally extract while legacy still runs
4. Apply appropriate saga pattern for distributed transactions

### Microservices Readiness Signals
1. Clear domain boundaries already established
2. Scaling pressure on specific areas (not uniform)
3. Independent development needs across teams
4. Operational maturity (CI/CD, monitoring, automated testing in place)
5. Technical expertise in distributed systems
6. Business justification (not trend-following)

## Strategic Refactoring Patterns

### Strangler Fig
Build new DDD-modeled functionality alongside legacy. Route requests to new code as features complete. Legacy gradually shrinks until fully replaced. Changes are incremental, monitored, low risk of unexpected breakage.

**Mikado integration**: use Mikado exploration to discover dependencies between legacy components before extracting. Each Mikado leaf becomes an atomic refactoring step.

### Bubble Context
Create a small bounded context (the "bubble") where DDD principles apply. The bubble communicates with legacy through an Anti-Corruption Layer. Progressively expand the bubble to encompass more legacy functionality.

**Steps**:
1. Identify the most valuable bounded context (core domain) for initial DDD investment
2. Create an ACL between the new context and legacy
3. Apply tactical DDD within the bubble (aggregates, value objects, domain events)
4. Gradually expand, moving more logic behind the ACL
5. Retire legacy components as new context absorbs their functionality

### Evolve Context Map
Integration patterns change as refactoring progresses. Map current relationships, identify mismatches, propose new patterns. Typical evolution: Conformist -> Customer-Supplier with ACL -> Partnership.

### Split Bounded Context
When a context grows too large or serves conflicting purposes:
1. Domain decomposition to break responsibilities into subdomains
2. Context mapping to plan the split and redefine integration patterns
3. Isolate related aggregates
4. Introduce domain events for communication
5. Gradually refactor dependent code

Validation: bounded context splits are driven by business evolution, not technical convenience. Validate with domain experts.

### Merge Bounded Contexts
When separation causes more friction than value:
1. Identify redundancies (overlapping models, duplicate logic, tight coupling)
2. Establish unified ubiquitous language
3. Consolidate aggregates and deprecate redundant events
4. Revisit context map

## Tactical Refactoring Patterns

These patterns apply tactical DDD concepts (aggregates, value objects, domain events, domain services, CQRS) to refactoring. For foundational definitions and design rules, load `domain-driven-design` from `solution-architect/`.

| Pattern | What It Fixes | Key Step |
|---------|--------------|----------|
| Replace primitives with VOs | Primitive obsession | Create self-validating type, replace in aggregate, update mapping |
| Enrich anemic model | Logic in services, data in entities | Move business rules from service "if" statements into owning entity |
| Introduce domain events | Direct coupling between aggregates | Replace method calls with immutable past-tense events + handlers |
| Extract domain service | Cross-aggregate operations in 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.