cm-reactor

Reactor — Strategic Codebase Re-direction

When the code works but the direction is wrong, you don't debug — you REACT.

TRIZ-powered protocol for pivoting large codebases without losing stability.

When to Use

ALWAYS when:

• Requirements changed significantly after code was built
• Architecture no longer fits the problem (wrong patterns, wrong abstractions)
• 3+ patches on the same area — symptom of structural mismatch
• Tech debt blocks new feature development
• "We need to rewrite X" — STOP. Use this skill first.
• Migrating from one framework/library/pattern to another
• Post-mortem reveals systemic issues needing strategic change

Skip when:

• Simple bug fix → use cm-debugging
• Routine refactoring (extract method, rename) → use cm-clean-code
• New project from scratch → use cm-project-bootstrap
• Small scope change (< 5 files affected) → just refactor directly

The Iron Law

NO REWRITE WITHOUT REACTOR ANALYSIS FIRST

Rewrites fail 70% of the time. Incremental strategic migration succeeds 90% of the time.

TRIZ Principles Applied

| # | Principle | How Applied | |---|-----------|-------------| | #35 | Parameter Change | Change the fundamental parameter (language, pattern, architecture) — not the symptom | | #28 | Mechanics Substitution | Replace one mechanism with a more effective one (OOP → FP, REST → GraphQL, etc.) | | #13 | The Other Way Around | Instead of adapting new code to old architecture, adapt old architecture to new requirements | | #25 | Self-Service | Design the migration so each component can migrate independently | | #1 | Segmentation | Break monolithic change into independent migration units | | #10 | Prior Action | Prepare the codebase (interfaces, adapters) BEFORE the actual migration |

The 5-Phase Process

Phase 1: ASSESS    → Understand what's wrong and why (not just symptoms)
Phase 2: MAP       → Trace all dependencies and blast radius
Phase 3: DESIGN    → Plan the migration path with strangler fig pattern
Phase 4: EXECUTE   → Migrate incrementally, one unit at a time
Phase 5: VERIFY    → Confirm direction is correct + clean up old code

Phase 1: ASSESS — Identify the Contradiction

Goal: Find the TRIZ contradiction — what do we WANT vs what BLOCKS us?

1. State the current direction:

`` Current: We built [X architecture/pattern/structure] Problem: It doesn't support [Y requirement/scale/use case] ``

1. Identify the contradiction:

``` We WANT: [desired capability] But: [current architecture] prevents it because [technical reason]

TRIZ Contradiction: Improving [parameter A] worsens [parameter B] Example: "Improving modularity worsens performance" "Improving flexibility worsens type safety" ```

1. Define the Ideal Final Result (IFR):

`` The system ITSELF [achieves the goal] WITHOUT [the current blocking factor] WHILE maintaining [what currently works well] ``

1. Scope assessment:

`` Files affected: [count from codeintell or grep] Components affected: [list] Tests affected: [count] External API changes: [yes/no — breaking change?] Estimated effort: [S/M/L/XL] Risk level: [Low/Medium/High/Critical] ``

Phase 2: MAP — Dependency Analysis

Goal: Know exactly what touches what before changing anything.

1. Use Code Intelligence (if available):

``` codegraph_impact("target_symbol", depth=3) → Shows all callers, dependencies, affected files

codegraph_context("target_module") → Shows architecture around the area ```

1. Manual mapping (if codegraph unavailable):

`` grep -rn "import.*{module}" src/ grep -rn "{function_name}" src/ → Build dependency tree manually ``

1. Categorize files by migration priority:

| Category | Description | Action | |----------|-------------|--------| | Core | The files that MUST change for the new direction | Migrate first | | Dependent | Files that import/use Core files | Migrate after Core, use adapters | | Peripheral | Files loosely connected | Migrate last or leave untouched | | Dead | Files no longer needed after migration | Flag for deletion in Phase 5 |

1. Output: Migration Map Document

```markdown ## Migration Map: [Initiative Name]

### Core (must change): [N files]

• file_a.ts → [what changes]
• file_b.ts → [what changes]

### Dependent (affected): [N files]

• file_c.ts → [how affected]

### Peripheral (optional): [N files]

• file_d.ts → [minimal change]

### Dead (remove after): [N files]

• old_module.ts → DELETE after migration complete

```

Phase 3: DESIGN — Strangler Fig Migration

Goal: Design an incremental migration path — NEVER big-bang rewrite.

Strangler Fig Pattern (TRIZ #10 Prior Action):

1. Create NEW structure alongside OLD structure
2. Route NEW traffic/calls to NEW structure
3. Gradually migrate OLD consumers to NEW structure
4. Remove OLD structure when no longer used

Migration design template:

## Migration Path

### Step 1: Create Adapter Layer
- [ ] Create interface/abstraction that both old and new code satisfy
- [ ] All consumers now use the adapter, not direct implementation

### Step 2: Build New Implementation
- [ ] New code behind the adapter — can be tested independently
- [ ] Feature flag or config switch between old/new

### Step 3: Gradual Cut-over
- [ ] Migrate consumers one-by-one to new implementation
- [ ] Each migration is a separate commit/PR
- [ ] Tests pass at EVERY step (never break green)

### Step 4: Clean up (→ triggers cm-clean-code)
- [ ] Remove old implementation
- [ ] Remove adapter layer (if no longer needed)
- [ ] Remove feature flag
- [ ] Update documentation

Rules:

• Never break the build at any step
• Each step MUST be independently deployable
• Tests must pass at every intermediate state
• If any step fails → STOP, don't cascade

Phase 4: EXECUTE — Incremental Migration

Goal: Execute migration plan step by step with quality gates.

Use cm-execution Mode A (Batch) or Mode E (TRIZ-Parallel):

For each migration step:
  1. Write/update tests FIRST (cm-tdd)
  2. Implement the change
  3. Run full test suite
  4. Commit with clear message: "reactor: [step description]"
  5. If tests fail → STOP, diagnose, fix before next step
  
Progress tracking:
  → Update OpenSpec `tasks.md` and `cm-tasks.json` with each completed migration step
  → Update CONTINUITY.md with migration status

Commit convention:

reactor: create adapter layer for auth module
reactor: implement new auth service behind adapter
reactor: migrate login page to new auth
reactor: migrate signup page to new auth
reactor: remove old auth implementation
reactor: cleanup — remove adapter (direct usage now)

Phase 5: VERIFY & CLEAN

Goal: Confirm the new direction works AND trigger cm-clean-code.

1. Direction verification:

`` □ New architecture supports the originally blocked requirement □ Performance is equal or better □ All tests pass □ No regression in existing features □ Documentation updated ``

1. Trigger cm-clean-code:

`` After reactor completes → ALWAYS run cm-clean-code Reason: Migration leaves dead code, unused imports, stale references ``

1. Record in CONTINUITY.md:

`` Decision: Migrated [X] from [old pattern] to [new pattern] Rationale: [why — the TRIZ contradiction we resolved] Scope: module:[affected module] ``

Red Flags — STOP

| Thought | Reality | |---------|---------| | "Let's just rewrite everything" | Big-bang rewrites fail 70%+ of the time | | "It's faster to start from scratch" | You lose all edge-case handling and bug fixes | | "We don't need tests during migration" | Migration without tests = guaranteed regression | | "Let's change the direction AND add featur