legacy-migration

What this skill does

# Legacy Code Migration for Breenix

Systematically migrate features from legacy kernel and remove old code when parity is reached.

## Purpose

Breenix is transitioning from a legacy kernel (src.legacy/) to a modern implementation (kernel/). This skill provides patterns for safely migrating features, verifying parity, and removing legacy code.

## When to Use

- **Feature migration**: Porting legacy features to new kernel
- **Parity verification**: Confirming new implementation matches legacy behavior
- **Legacy removal**: Safely removing old code after feature completion
- **Documentation updates**: Keeping FEATURE_COMPARISON.md current
- **Risk assessment**: Evaluating what can be safely removed

## Legacy Migration Principle (from CLAUDE.md)

```
When new implementation reaches parity:
1. Remove code from src.legacy/
2. Update FEATURE_COMPARISON.md
3. Include removal in same commit as feature completion
```

**Key Point**: Don't accumulate dead code. Remove legacy as soon as parity is reached.

## Migration Workflow

### Phase 1: Identify Feature for Migration

**Review FEATURE_COMPARISON.md:**

```bash
# See what's in legacy but not new
cat docs/planning/legacy-migration/FEATURE_COMPARISON.md | grep "❌"

# See what's partially implemented
cat docs/planning/legacy-migration/FEATURE_COMPARISON.md | grep "🚧"
```

**Common patterns:**
- ✅ Fully implemented (safe to remove if in both)
- 🚧 Partially implemented (needs work)
- ❌ Not implemented (needs migration or decision)
- 🔄 Different approach (verify equivalence)

### Phase 2: Analyze Legacy Implementation

**Locate the legacy code:**

```bash
# Find legacy implementation
find src.legacy -name "*feature_name*"

# Search for specific functionality
grep -r "feature_function" src.legacy/
```

**Understand the implementation:**
1. What does it do? (API, behavior, edge cases)
2. Why does it exist? (requirements it satisfies)
3. How does it work? (algorithm, data structures)
4. What depends on it? (other modules, tests)

**Extract key characteristics:**
- Public API surface
- Critical behavior
- Edge case handling
- Error conditions
- Test coverage

### Phase 3: Implement in New Kernel

**Follow Breenix standards:**

```rust
// 1. Add to appropriate module in kernel/src/
// 2. Use modern Rust patterns
// 3. Add #[cfg(feature = "testing")] for test code
// 4. Write comprehensive tests
// 5. Document with clear comments
```

**Quality checklist:**
- [ ] Matches legacy API (if public)
- [ ] Handles all edge cases
- [ ] Error handling implemented
- [ ] Tests written and passing
- [ ] Documentation complete
- [ ] No compiler warnings
- [ ] Clippy clean

### Phase 4: Verify Parity

**Functional equivalence:**

```bash
# Run tests for the feature
cargo test feature_name

# Check behavior matches legacy
# (Compare outputs, test edge cases)

# Run full test suite
cargo test
```

**API compatibility:**
- If API is public: Must match exactly
- If internal: Can improve design
- Document any intentional differences

**Behavioral parity checklist:**
- [ ] Same inputs produce same outputs
- [ ] Edge cases handled identically
- [ ] Error conditions match
- [ ] Performance acceptable
- [ ] Integration with other subsystems works

### Phase 5: Update Documentation

**Update FEATURE_COMPARISON.md:**

```markdown
### Feature Category
| Feature | Legacy | New | Notes |
|---------|--------|-----|-------|
| Feature X | ~~✅ Full~~ (removed) | ✅ | Migrated in PR #123, legacy removed |
```

**Patterns:**
- Change legacy column to `~~✅ Full~~ (removed)`
- Update new column to ✅
- Add note about migration PR
- Include date if significant

**Document any differences:**

```markdown
## Implementation Differences

### Feature X
- **Legacy**: Used approach A
- **New**: Uses approach B (reason)
- **Rationale**: Cleaner design, better performance, etc.
```

### Phase 6: Remove Legacy Code

**In the SAME commit as feature completion:**

```bash
# Remove the legacy files
git rm src.legacy/path/to/feature.rs

# Or if removing entire module
git rm -r src.legacy/module/

# Stage FEATURE_COMPARISON.md changes
git add docs/planning/legacy-migration/FEATURE_COMPARISON.md

# Commit together
git commit -m "Complete Feature X implementation and remove legacy

- Implement Feature X in kernel/src/module/feature.rs
- Full parity with legacy implementation
- Remove legacy code from src.legacy/
- Update FEATURE_COMPARISON.md

Tested with: cargo test feature_x
"
```

**Critical**: Legacy removal MUST be in the same commit to maintain atomicity.

## Legacy Code Categories

### 1. Direct Migration

**What**: Feature can be ported directly with minimal changes

**Example**: VGA text mode removed after framebuffer complete

**Process**:
1. Understand legacy implementation
2. Port to new codebase
3. Test thoroughly
4. Remove legacy
5. Update docs

### 2. Reimplementation

**What**: New approach taken, but achieves same goals

**Example**: Timer system (different RTC implementation)

**Process**:
1. Identify requirements from legacy
2. Design new approach
3. Implement with modern patterns
4. Verify equivalent behavior
5. Remove legacy
6. Document differences

### 3. Obsolete Features

**What**: Feature no longer needed or superseded

**Example**: VGA text after framebuffer works

**Process**:
1. Verify feature truly obsolete
2. Check no dependencies
3. Remove from legacy
4. Update FEATURE_COMPARISON.md with rationale

### 4. Deferred Features

**What**: Features not yet needed in new kernel

**Example**: Network stack (not current priority)

**Process**:
1. Document decision to defer
2. Mark as ❌ in FEATURE_COMPARISON.md
3. Leave in legacy as reference
4. Add to future roadmap

## Common Migration Patterns

### Pattern: Device Driver

```rust
// Legacy: src.legacy/drivers/device_x.rs
// New: kernel/src/drivers/device_x.rs

// 1. Port driver structure
pub struct DeviceX {
    // ... fields
}

// 2. Port initialization
impl DeviceX {
    pub fn new() -> Self { ... }
}

// 3. Port public API
impl DeviceX {
    pub fn operation(&mut self) { ... }
}

// 4. Add tests
#[cfg(test)]
mod tests {
    #[test]
    fn test_device_x() { ... }
}
```

### Pattern: System Call

```rust
// Legacy: src.legacy/syscall/handler.rs (mostly commented out)
// New: kernel/src/syscall/handler.rs (full implementation)

// 1. Define syscall number
pub const SYS_FEATURE: u64 = N;

// 2. Add to dispatcher
pub fn syscall_handler(num: u64, args: ...) {
    match num {
        SYS_FEATURE => sys_feature(args),
        // ...
    }
}

// 3. Implement handler
fn sys_feature(args: ...) -> u64 {
    // Implementation
}

// 4. Test from userspace
// userspace/programs/feature_test.rs
```

### Pattern: Infrastructure

```rust
// Legacy: Multiple files implementing async
// New: Consolidated in kernel/src/task/

// 1. Analyze legacy architecture
// 2. Design improved structure
// 3. Implement with better patterns
// 4. Migrate tests
// 5. Document improvements
```

## Risk Assessment

Before removing legacy code, assess:

### High Risk (Don't Remove Yet)
- Features not yet implemented in new kernel
- Complex subsystems (network, filesystem)
- Code with unique algorithms or logic
- Reference implementations for future work

### Medium Risk (Remove with Caution)
- Features with partial new implementation
- Code with subtle edge cases
- Infrastructure with many dependencies

### Low Risk (Safe to Remove)
- Features fully implemented and tested
- Obsolete approaches (VGA text mode)
- Dead code (never called)
- Superseded implementations

## Integration with Development

### During Feature Development

```bash
# 1. Check if legacy has this feature
grep -r "feature_name" src.legacy/

# 2. If found, analyze it
less src.legacy/path/to/feature.rs

# 3. Implement in new kernel
# ... development work ...

# 4. Test thoroughly
cargo test feature_name

# 5. Remove legacy in same commit
git rm src.legacy/path/to/feature.rs

# 6. Update FEATURE_COMPARISON.md
# ... edit ...

# 7. Commit together
git commit -m "