Migration Logger

Log detailed migration history to MIGRATION_LOG.md.

Core Responsibility

Log to MIGRATION_LOG.md ONLY - This skill:

• ✅ Updates: MIGRATION_LOG.md
• ❌ Does NOT modify: CLAUDE.md, TASK_BOARD.md, or other files

Clear separation:

• update-migration-log → Logs migration details to MIGRATION_LOG.md
• update-task-board → Updates TASK_BOARD.md based on logs
• CLAUDE.md → Entry point, rarely modified

When to Use

Use this skill after:

• Completing a file migration
• Recording migration issues and solutions
• User asks to "log migration" or "update migration log"

Do NOT use for:

• Updating task status (use update-task-board)
• Updating CLAUDE.md (handled separately)
• General task completion (use update-task-board)

Migration Entry Template

Use this template for all migration entries:

### YYYY-MM-DD - [Original File] → [New Location]

**Status:** ✅ Completed / 🚧 In Progress / ⚠️ Issues
**Time Spent:** [e.g., 45 minutes]
**Complexity:** Low / Medium / High

**Source:** `[path/to/original/file.py]`
**Destination:** `[path/to/new/file.py]`

#### 📋 Migration Summary
- **Original Purpose:** [Brief description]
- **Target Architecture Layer:** [Problem/Algorithm/Data/Visualization]
- **Key Changes Made:** [2-3 sentence overview]

#### 🔧 Key Changes
- **Extracted hardcoded values:** [What was parameterized]
- **Decoupled from paper logic:** [How generalized]
- **Added/improved:** [Docstrings, type hints, etc.]

#### ⚠️ Issues & Solutions
**Issue 1:** [Description]
- **Solution:** [Fix implemented]
- **Impact:** [Effect on migration]

#### ✅ Verification
- [x] Code compilation
- [x] Import tests
- [ ] Runtime tests (if environment available)

#### 📝 Notes
- [Any important observations]

MIGRATION_LOG.md Structure

Required Sections

1. Header

# VRP Toolkit - Migration Log

**Last Updated:** YYYY-MM-DD
**Total Files Migrated:** X/9

2. Migration Progress Summary

## 📊 Migration Progress Summary

| Category | Completed | Total | Progress |
|----------|-----------|-------|----------|
| Core Files | X | 9 | XX% |

3. Migration History (newest first)

## 📜 Migration History

### YYYY-MM-DD - file.py → new/location.py
[Entry details...]

Workflow

Step 1: Prepare Entry

Gather information about the migration:

• Original file location
• New file location
• Changes made
• Issues encountered
• Time spent
• Complexity level

Step 2: Write Entry

1. Use migration entry template
2. Fill in all sections
3. Be specific about changes and issues
4. Include verification checklist results

Step 3: Update MIGRATION_LOG.md

1. Update "Last Updated" date
2. Update "Total Files Migrated" count
3. Update progress table percentages
4. Add entry to top of "Migration History"
5. Keep entries in reverse chronological order (newest first)

Step 4: Save

No further action needed - other skills will read this log.

Entry Guidelines

Summary Section

Be concise but informative:

• Original purpose: 1 sentence
• Target layer: One of Problem/Algorithm/Data/Visualization
• Key changes: 2-3 sentences covering main refactoring

Example:

#### 📋 Migration Summary
- **Original Purpose:** Instance class for PDPTW with battery constraints
- **Target Architecture Layer:** Problem
- **Key Changes Made:** Extracted hardcoded depot location and vehicle capacity into parameters. Separated solution validation from instance definition. Added type hints and comprehensive docstrings.

Key Changes Section

List specific technical changes:

• Parameters extracted from hardcoded values
• Decoupling from paper-specific logic
• Documentation improvements
• API changes

Example:

#### 🔧 Key Changes
- **Extracted hardcoded values:** Depot location (0,0), vehicle capacity (15), max battery (100)
- **Decoupled from paper logic:** Removed SISR-specific validation, generalized time window checks
- **Added/improved:** Full docstrings for all public methods, type hints for function signatures

Issues & Solutions Section

Document problems encountered:

• Import errors
• Circular dependencies
• API incompatibilities
• Logic errors

For each issue:

• Clear description
• Solution implemented
• Impact on migration

Example:

#### ⚠️ Issues & Solutions
**Issue 1:** Circular import between Instance and Solution classes
- **Solution:** Moved Solution to separate module, used TYPE_CHECKING for type hints
- **Impact:** Required restructuring module organization

**Issue 2:** Hardcoded file paths in data loading
- **Solution:** Added config parameter for data directory path
- **Impact:** Minor - added one parameter to constructor

Verification Section

Checklist items:

• Code compilation (no syntax errors)
• Import tests (can import without errors)
• Runtime tests (if applicable)
• Tutorial compatibility (if applicable)

Mark items complete only when verified.

Integration with Other Skills

Read by:

• update-task-board - Uses entries to update TASK_BOARD.md
• build-session-context - Shows recent migrations
• manage-skills - Reads for project history

Does NOT interact with:

• CLAUDE.md (not this skill's job)
• TASK_BOARD.md (update-task-board handles)

Example Entry

### 2026-01-01 - instance.py → vrp_toolkit/problems/pdptw.py

**Status:** ✅ Completed
**Time Spent:** 2 hours
**Complexity:** High

**Source:** `SDR_stochastic/new version/instance.py`
**Destination:** `vrp-toolkit/vrp_toolkit/problems/pdptw.py`

#### 📋 Migration Summary
- **Original Purpose:** PDPTW instance class with battery constraints for SDR paper
- **Target Architecture Layer:** Problem
- **Key Changes Made:** Extracted all hardcoded values (depot, capacity, battery) into parameters. Separated instance definition from solving logic. Added comprehensive type hints and docstrings following Google style.

#### 🔧 Key Changes
- **Extracted hardcoded values:** Depot (0,0), vehicle capacity 15, max battery 100, charging rate 2.0
- **Decoupled from paper logic:** Removed SISR-specific validation, separated battery simulation from instance
- **Added/improved:** Complete docstrings, type hints, parameter validation in constructor

#### ⚠️ Issues & Solutions
**Issue 1:** Circular dependency with Solution class
- **Solution:** Moved Solution to separate module, used forward references
- **Impact:** Created cleaner module structure

**Issue 2:** Time window validation assumed specific format
- **Solution:** Generalized validation to accept any numeric time windows
- **Impact:** None - more flexible API

#### ✅ Verification
- [x] Code compilation
- [x] Import tests
- [x] Runtime tests with sample data
- [x] Tutorial compatibility verified

#### 📝 Notes
- Battery constraint logic may need future generalization for other problems
- Consider adding battery capacity as instance parameter vs vehicle parameter

Maintenance Notes

Keep MIGRATION_LOG.md:

• Chronologically ordered (newest first)
• Detailed but focused
• Consistent formatting
• Evidence of progress

Update frequency:

• After each migration completes
• When significant issues are resolved
• When migration approach changes

File References

• Manages: .claude/MIGRATION_LOG.md
• Does NOT modify: .claude/CLAUDE.md, .claude/TASK_BOARD.md