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:

markdown

### 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

markdown

# VRP Toolkit - Migration Log

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

2. Migration Progress Summary

markdown

## 📊 Migration Progress Summary

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

3. Migration History (newest first)

markdown

## 📜 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:

markdown

#### 📋 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:

markdown

#### 🔧 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:

markdown

#### ⚠️ 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

markdown

### 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