chess/docs/typescript-migration-risks.md

TypeScript Migration - Risk Management Matrix

Risk Assessment Overview

Project Risk Level: MEDIUM Risk Mitigation Strategy: Incremental migration with checkpoints Rollback Capability: High (module-level, phase-level, complete)

---

Risk Register

ID	Risk	Prob	Impact	Severity	Owner	Mitigation	Status
R1	Type errors break code	M	H	HIGH	Lead Dev	Incremental + tests	Monitor
R2	Tests fail post-migration	M	H	HIGH	QA Lead	Parallel test migration	Monitor
R3	Breaking API changes	L	H	MEDIUM	Architect	Maintain compatibility	Watch
R4	Scope creep (refactoring)	H	M	HIGH	PM	Strict no-refactor rule	Active
R5	DOM type issues (jsdom)	M	M	MEDIUM	Dev Team	Proper @types packages	Monitor
R6	Generic type complexity	M	L	LOW	Senior Dev	Start simple	Watch
R7	Build pipeline issues	L	M	LOW	DevOps	Test early in Phase 0	Monitor
R8	Developer learning curve	M	M	MEDIUM	Tech Lead	Training + pairing	Active
R9	IDE performance issues	L	L	LOW	Dev Team	Configure tsconfig	Watch
R10	Third-party type defs	L	M	LOW	Dev Team	Verify all @types exist	Watch
R11	Merge conflicts	M	M	MEDIUM	Team	Feature freeze during migration	Active
R12	Performance degradation	L	H	MEDIUM	Tech Lead	Benchmark early	Monitor
R13	Incomplete rollback	L	H	MEDIUM	Lead Dev	Document rollback steps	Prevent
R14	Timeline overrun	M	M	MEDIUM	PM	50% contingency buffer	Active
R15	Team burnout	M	M	MEDIUM	PM	Balanced timeline	Active

Legend:

• Probability: L=Low, M=Medium, H=High
• Impact: L=Low, M=Medium, H=High
• Severity: LOW (P×I <4), MEDIUM (P×I 4-6), HIGH (P×I >6)

---

High-Priority Risks (Detailed Plans)

R1: Type Errors Break Existing Code

Probability: Medium (40%) Impact: High (Critical functionality breaks) Severity: HIGH

Symptoms

• Compilation errors after type addition
• Runtime errors in previously working code
• Type assertions failing unexpectedly
• Null/undefined errors appearing

Root Causes

• Loose JavaScript patterns exposed by strict types
• Hidden null/undefined values
• Incorrect type assumptions
• Missing null checks

Prevention Strategy

// 1. Add types incrementally
class Board {
    // Start with basic types
    grid: any[][]; // Temporarily use any

    // Then refine
    grid: (Piece | null)[][]; // Add proper types

    // Finally validate
    getPiece(row: number, col: number): Piece | null {
        // Add runtime checks
        if (!this.isInBounds(row, col)) {
            return null;
        }
        return this.grid[row][col];
    }
}

// 2. Use type guards
function isPiece(obj: any): obj is Piece {
    return obj && typeof obj.type === 'string';
}

// 3. Add null safety
const piece = board.getPiece(row, col);
if (piece) {
    piece.getValidMoves(board); // Safe
}

Detection

• Continuous type checking: npx tsc --noEmit
• Run tests after each module
• Manual smoke testing
• Monitor console for runtime errors

Mitigation

1. Keep .js files temporarily

   # Don't delete .js until .ts validated
   cp Board.js Board.ts
   # Work on Board.ts
   # Test thoroughly
   rm Board.js # Only after validation
   

2. Use temporary workarounds

   // @ts-expect-error - TODO: Fix in Phase 6
   const piece = board.grid[row][col];
   

3. Add null checks

   // Before
   return this.grid[row][col].getValidMoves();
   
   // After
   const piece = this.grid[row][col];
   if (!piece) return [];
   return piece.getValidMoves();
   

Rollback Plan

# 1. Revert to .js version
git checkout HEAD -- js/game/Board.js
rm js/game/Board.ts

# 2. Update imports in dependent files
# Change: import { Board } from './Board.ts'
# To:     import { Board } from './Board.js'

# 3. Verify tests pass
npm test

# 4. Document issue for retry
echo "Board.ts rollback: type issue with grid" >> migration-log.md

Success Criteria

• Zero new runtime errors
• All tests passing
• Type inference working correctly
• No any types in final code

---

R2: Tests Fail After Migration

Probability: Medium (40%) Impact: High (Cannot validate correctness) Severity: HIGH

Symptoms

• Jest failures after module migration
• Type errors in test files
• Mocking issues with TypeScript
• Import errors in tests

Root Causes

• Test expectations don't match new types
• Mock objects lack type definitions
• Import paths need updating
• jsdom type issues

Prevention Strategy

// 1. Migrate tests alongside source
// When migrating Board.js → Board.ts
// Also migrate Board.test.js → Board.test.ts

// 2. Add proper type imports
import { Board } from '../../src/game/Board';
import type { Position } from '../../src/types/chess';

// 3. Type test fixtures
const mockPosition: Position = { row: 0, col: 0 };
const mockBoard: Board = new Board();

// 4. Use type-safe assertions
expect(result).toEqual<Position>({ row: 1, col: 1 });

Detection

• Run tests after each module: npm test -- <module>.test.ts
• Full test suite before checkpoint
• Coverage report: npm run test:coverage
• CI/CD integration (if available)

Mitigation

1. Fix test imports

   // Before
   import { Board } from '../../js/game/Board.js';
   
   // After
   import { Board } from '../../src/game/Board';
   

2. Update test expectations

   // Before
   expect(moves.length).toBe(8);
   
   // After (with types)
   const moves: Position[] = piece.getValidMoves(board);
   expect(moves).toHaveLength(8);
   expect(moves).toEqual(
       expect.arrayContaining([
           expect.objectContaining({ row: expect.any(Number) })
       ])
   );
   

3. Mock with types

   const mockPiece: Piece = {
       color: 'white',
       position: { row: 0, col: 0 },
       type: 'pawn',
       hasMoved: false,
       getValidMoves: jest.fn().mockReturnValue([]),
   } as Piece;
   

Rollback Plan

# 1. Keep test file as .js temporarily
mv Board.test.ts Board.test.js

# 2. Continue with source migration
# Tests can stay .js until Phase 5

# 3. Or rollback entire module
git checkout HEAD -- js/game/Board.{js,ts}
git checkout HEAD -- tests/unit/game/Board.test.{js,ts}

Success Criteria

• 124/124 tests passing
• No test file type errors
• Coverage maintained (>80%)
• All assertions type-safe

---

R4: Scope Creep (Refactoring During Migration)

Probability: High (60%) Impact: Medium (Timeline delay) Severity: HIGH

Symptoms

• "While we're here, let's improve..."
• Logic changes during type addition
• New features added during migration
• Timeline slipping without clear cause

Root Causes

• Temptation to fix old code
• Discovery of improvement opportunities
• Lack of clear boundaries
• No accountability for changes

Prevention Strategy

# GOLDEN RULE: Migration ONLY, Zero Refactoring

## Allowed ✅
- Adding type annotations
- Adding null checks for type safety
- Fixing type-related bugs exposed
- Updating imports for .ts files

## FORBIDDEN ❌
- Changing algorithms
- Renaming variables/functions
- Restructuring code
- Adding new features
- Performance optimizations
- Code style improvements

## Gray Area → Defer to Phase 6
- Converting loops to .map()
- Adding helper functions
- Extracting constants
- Simplifying conditionals

Detection

# Review each commit for logic changes
git diff HEAD~1 --stat

# Red flags in commit:
# - More than 50% lines changed
# - New files created
# - Function signatures changed (beyond types)

# Use code review checklist
- [ ] Only type annotations added?
- [ ] Logic unchanged?
- [ ] No new functions?
- [ ] No performance changes?

Mitigation

1. Strict code review

   Code Review Checklist:
   - [ ] Only types added (no logic changes)
   - [ ] Tests still pass
   - [ ] No new files (except .ts versions)
   - [ ] Commit message says "feat: migrate" not "refactor:"
   

2. Document improvements for later

   // TODO Phase 6: Refactor this to use .map()
   // Current loop works but could be cleaner
   for (const piece of pieces) {
       // ...
   }
   

3. Time-box exploration

   If improvement seems necessary:
   1. Time-box investigation: 15 minutes
   2. If simple fix (<10 lines): Consider it
   3. If complex: Create issue for Phase 6
   4. Always defer if uncertain
   

Rollback Plan

# If refactoring snuck in:
# 1. Identify pure type changes
git diff HEAD~1 -- js/game/Board.ts > types-only.patch

# 2. Revert commit
git revert HEAD

# 3. Reapply only type changes
git apply types-only.patch

Success Criteria

• Each commit modifies only types
• No logic changes in diff
• Tests have same behavior
• Timeline on track

---

Medium-Priority Risks

R3: Breaking API Changes

Risk: External code depends on current API Mitigation:

• Keep public API signatures identical
• Add new typed methods alongside old ones
• Use adapter pattern if needed
• Document breaking changes

Rollback: Restore old API, add deprecation warnings

---

R5: DOM Type Issues (jsdom)

Risk: TypeScript DOM types incompatible with jsdom Mitigation:

// Install proper types
npm install --save-dev @types/jsdom

// Configure jest
module.exports = {
    testEnvironment: 'jsdom',
};

// Use proper DOM types
const element: HTMLElement | null = document.getElementById('board');
if (!element) throw new Error('Board element not found');

// Add custom types if needed
declare global {
    interface Window {
        chessGame: GameController;
    }
}

Rollback: Remove jsdom types, use any temporarily

---

R8: Developer Learning Curve

Risk: Team unfamiliar with TypeScript Mitigation:

• Provide TypeScript training (2-4 hours)
• Pair programming sessions
• Code review with explanations
• Share TypeScript resources
• Start with simple types, progress to advanced

Training Plan:

Week 0: TypeScript Basics (4 hours)
- Session 1: Types, Interfaces, Classes (2h)
- Session 2: Generics, Unions, Type Guards (2h)

During Migration:
- Pair programming on complex modules
- Code review as learning opportunity
- Share patterns and best practices

Rollback: Extend timeline, add more training

---

R11: Merge Conflicts

Risk: Other development during migration causes conflicts Mitigation:

• Feature freeze during migration (recommended)
• Small, frequent commits
• Clear branch strategy
• Communicate migration schedule

Branch Strategy:

# Option 1: Feature branch
git checkout -b typescript-migration
# Merge to main at checkpoints

# Option 2: Main branch
# Small commits directly to main
# Easier to track, but riskier

# Recommended: Feature branch with checkpoints
Week 1: Merge Phase 0-1
Week 2: Merge Phase 2
# etc.

Rollback: Use conflict resolution tools, or rollback to pre-merge

---

R12: Performance Degradation

Risk: TypeScript compilation or runtime overhead Mitigation:

# Benchmark before migration
npm test -- --coverage
# Note baseline metrics

# Monitor during migration
# Build time
time npm run build

# Test execution time
time npm test

# Runtime performance
# Use browser DevTools Performance tab

Acceptable Thresholds:

• Build time: +50% max
• Test time: +20% max
• Runtime: +5% max (should be 0%)

Rollback: Investigate, optimize config, or revert

---

R14: Timeline Overrun

Risk: Migration takes longer than estimated Mitigation:

• 50% contingency buffer built in
• Weekly velocity tracking
• Time-box each module
• Escalate blockers quickly

Velocity Tracking:

Week 1: Planned 10h, Actual 12h → 20% over
Week 2: Planned 10h, Actual 11h → 10% over
Cumulative: 23h vs 20h planned → 15% over

Action: If >25% over by Week 3, extend timeline

Rollback: Re-estimate, extend timeline, or reduce scope

---

Risk Response Decision Tree

Issue Detected
    ↓
Small issue? (<30min fix)
    ├─ Yes → Fix immediately
    └─ No → Assess severity
                ↓
        Severity Level?
            ├─ Low → Document, continue
            ├─ Medium → Time-box fix (2h)
            │            ├─ Fixed? → Continue
            │            └─ Not fixed? → Escalate
            └─ High → STOP
                        ↓
                  Affects module only?
                      ├─ Yes → Module rollback
                      └─ No → Phase rollback?
                                  ├─ Yes → Phase rollback
                                  └─ No → Complete rollback

---

Rollback Procedures

Level 1: Module Rollback (< 1 hour)

When: Single module has issues Impact: Low - other modules unaffected

Procedure:

# 1. Revert module to .js
git checkout HEAD -- js/path/to/Module.js
rm js/path/to/Module.ts

# 2. Update imports in dependent modules
# Find files importing this module
grep -r "from './Module.ts'" js/

# 3. Change imports back to .js
sed -i '' "s/Module.ts/Module.js/g" js/**/*.ts

# 4. Verify tests
npm test -- Module.test

# 5. Document issue
echo "Module rollback: [reason]" >> rollback-log.md

# 6. Continue with other modules
# Retry problem module later

---

Level 2: Phase Rollback (2-4 hours)

When: Entire phase is problematic Impact: Medium - lose phase progress

Procedure:

# 1. Identify checkpoint tag
git tag --list

# 2. Revert to last checkpoint
git reset --hard checkpoint-phase-N

# 3. Create rollback branch
git checkout -b rollback-phase-N

# 4. Assess what went wrong
# Review commits since checkpoint
git log checkpoint-phase-N..HEAD

# 5. Create new approach
# Update plan based on learnings

# 6. Re-start phase with new strategy

---

Level 3: Complete Rollback (1 day)

When: Fundamental issues, multiple phases failing Impact: High - lose all migration progress

Procedure:

# 1. Revert to pre-migration state
git reset --hard pre-migration-baseline

# 2. Verify game works
npm test
npm run dev
# Manual testing

# 3. Keep TypeScript config for future
# Don't delete tsconfig.json, package.json changes

# 4. Post-mortem analysis
# Document what went wrong
# What would we do differently?

# 5. Re-evaluate project readiness
# Is the codebase ready for TypeScript?
# Does the team need more training?
# Should we adjust the approach?

# 6. Create new migration plan
# Based on lessons learned
# Maybe phased differently
# Maybe with more training first

---

Early Warning System

Weekly Health Check

## Week X Health Check

### Green Flags ✅ (All is well)
- [ ] On schedule (within 10% of estimate)
- [ ] All tests passing
- [ ] No rollbacks this week
- [ ] Team confident
- [ ] Zero critical blockers

### Yellow Flags ⚠️ (Caution)
- [ ] 10-25% over schedule
- [ ] 1-2 module rollbacks
- [ ] Minor blockers (resolved)
- [ ] Team has questions
- [ ] Some test failures (fixed)

### Red Flags 🚨 (Action required)
- [ ] >25% over schedule
- [ ] >3 module rollbacks
- [ ] Unresolved critical blockers
- [ ] Team morale low
- [ ] Multiple phase rollbacks
- [ ] Test pass rate <90%

### Action Required
If ANY red flag:
1. Pause migration
2. Team meeting
3. Assess root cause
4. Decide: Continue, adjust, or rollback

---

Risk Mitigation Checklist

Phase 0: Foundation

• TypeScript version compatible (5.3+)
• All @types packages installed
• tsconfig.json validated
• Jest configured correctly
• Baseline benchmarks recorded

Phase 1: Core Types

• No any types used
• Strict mode enabled
• All util tests passing
• Type inference working
• Team comfortable with types

Phase 2: Models

• Board class compiles
• Piece hierarchy correct
• All piece tests passing
• No runtime errors
• Performance unchanged

Phase 3: Engine

• Game logic typed
• Move validation works
• Special moves correct
• Check/checkmate functional
• Tests 100% passing

Phase 4: UI

• DOM types working
• Event handlers typed
• Full game playable
• No console errors
• Manual testing passed

Phase 5: Integration

• All source files .ts
• All test files .ts
• 124/124 tests passing
• Build successful
• Ready for production

---

Post-Incident Review Template

If any rollback occurs:

## Rollback Post-Mortem: [Module/Phase]

**Date:** YYYY-MM-DD
**Level:** Module / Phase / Complete
**Duration:** Xh to resolve

### What Happened
[Description of the issue]

### Root Cause
[Why did this happen?]

### Timeline
- HH:MM: Issue detected
- HH:MM: Investigation started
- HH:MM: Decision to rollback
- HH:MM: Rollback completed
- HH:MM: Resolution

### Impact
- Tests affected: X
- Time lost: Xh
- Modules affected: X

### What Went Well
- [Things that helped]

### What Went Wrong
- [Things that hindered]

### Action Items
- [ ] Prevent recurrence: [action]
- [ ] Update documentation: [what]
- [ ] Team training: [topic]
- [ ] Plan adjustment: [change]

### Lessons Learned
1. [Lesson 1]
2. [Lesson 2]

**Prepared by:** [Name]
**Reviewed by:** [Team]

---

Risk Communication Plan

Daily

• Update progress tracking
• Document blockers
• Share quick wins

Weekly

• Checkpoint meeting
• Health check review
• Velocity assessment
• Adjust plan if needed

On Issue

• Immediate notification
• Assessment within 1 hour
• Decision within 4 hours
• Communication to stakeholders

Stakeholder Communication

Subject: TypeScript Migration - Week X Update

Status: On Track / At Risk / Delayed

Progress:
- Phase: X
- Files: X/18 (X%)
- Tests: X/124 (X%)

Highlights:
- [Achievement 1]
- [Achievement 2]

Challenges:
- [Challenge 1] - Mitigation: [action]

Next Week:
- [Plan]

Confidence: High / Medium / Low

---

Keep this document accessible throughout the migration!

Version 1.0 | Last Updated: 2025-11-23