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

• Code compilation
• 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

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

• Use migration entry template

• Fill in all sections

• Be specific about changes and issues

• Include verification checklist results

Step 3: Update MIGRATION_LOG.md

• Update "Last Updated" date

• Update "Total Files Migrated" count

• Update progress table percentages

• Add entry to top of "Migration History"

• 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

• Code compilation
• Import tests
• Runtime tests with sample data
• 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