| name | spike-migrate |
| description | Use when upgrading SPIKE code to production quality, migrating prototypes, converting experimental code to production-ready implementations, or when user invokes /spike-migrate |
Spike Migration
Systematically upgrade SPIKE prototype code to production quality with full TDD workflow and quality gates.
When to Use
Invoke with /spike-migrate when:
- SPIKE approach validated and working
- Ready for production deployment
- Other features depend on SPIKE code
- SPIKE code stable for 1+ week
- Users requesting the feature in production
Skip this skill when:
- Still exploring alternatives
- Unclear if feature needed
- Major design changes expected
- Performance problems not yet addressed
- SPIKE code is broken or failing tests
Usage
/spike-migrate lib/my_app/user_preferences.ex
/spike-migrate lib/my_app_web/live/preferences_live.ex
/spike-migrate
Expects an optional file path. Without arguments, scans for all SPIKE markers.
Tools Used
This skill typically uses:
- Task - Spawn developer agent for TDD implementation
- Read - Analyze existing SPIKE code
- Write/Edit - Upgrade code to production quality
- Bash - Run language-specific commands (mix, cargo, npm, pytest)
- Glob/Grep - Find SPIKE markers and related files
- TodoWrite - Track migration progress
Workflow
Step 1: Identify SPIKE Code
If file path provided, analyze that file. Otherwise, scan for all SPIKE markers:
grep -r "# SPIKE:" lib/ --files-with-matches
Present inventory:
## SPIKE Code Inventory
Found SPIKE markers in 5 files:
**Core Implementation**:
- lib/my_app/user_preferences.ex (85 lines, 6 functions)
- lib/my_app/accounts.ex (3 SPIKE functions added)
**UI Layer**:
- lib/my_app_web/live/preferences_live.ex (120 lines)
**Tests**:
- test/my_app/user_preferences_test.exs (2 smoke tests)
- test/my_app_web/live/preferences_live_test.exs (1 smoke test)
**From spike-debt.md**:
- Feature: Email Preferences
- Created: 2025-01-16 (7 days ago)
- Status: Validated (approach works)
- Estimated migration: 8 hours
Step 2: Analyze Quality Gaps
For each SPIKE file, analyze what's missing:
## Quality Gap Analysis
### lib/my_app/user_preferences.ex
**Current State** (SPIKE):
- 6 functions implemented
- Basic functionality works
- 2 smoke tests
- 0/6 functions have typespecs
- No input validation
- Only happy path error handling
- No edge case handling
- No module documentation
- No complexity analysis
**Required for Production**:
1. Typespecs (6 functions) - 1 hour
2. Comprehensive tests (13 additional tests) - 4 hours
- Success cases: 3 tests
- Error cases: 7 tests
- Edge cases: 3 tests
- Criticality: 8-10
3. Input validation - 1 hour
4. Error handling for all paths - 2 hours
5. Module documentation - 30 mins
6. Function documentation - 30 mins
**Total effort**: ~9 hours
Step 3: Create Migration Plan
Generate detailed todo list with TodoWrite:
Creating migration plan with TodoWrite...
Migration: Email Preferences SPIKE -> Production
Phase 1: Test Infrastructure
- [pending] Create comprehensive test plan for user_preferences
- [pending] Create integration test plan for preferences_live
Phase 2: Core Module (user_preferences.ex)
- [pending] Add typespecs to all 6 public functions
- [pending] Implement comprehensive tests (13 tests)
- [pending] Add input validation
- [pending] Add error handling for all paths
- [pending] Add module documentation
- [pending] Remove # SPIKE: markers
Phase 3: LiveView (preferences_live.ex)
- [pending] Add error handling and user feedback
- [pending] Implement loading states
- [pending] Create integration tests (5 tests)
- [pending] Add accessibility improvements
- [pending] Remove # SPIKE: markers
Phase 4: Quality Gates
- [pending] Run precommit checks
- [pending] Run full test suite
- [pending] Manual QA of UI
- [pending] Update spike-debt.md (archive as migrated)
Phase 5: Documentation
- [pending] Update project-learnings.md
- [pending] Add usage examples
- [pending] Document patterns used
Step 4: Launch TDD Migration Agent
Launch developer agent (Sonnet) with migration requirements:
Launching developer (Sonnet) for SPIKE migration...
Migration context:
- SPIKE code validated and working
- Converting to production quality
- Files identified with quality gaps
- Test plan created
Migration approach:
1. **Tests First** (TDD)
- Start with comprehensive test suite
- Follow Red -> Green -> Refactor
- Target criticality 8-10 for all tests
2. **Upgrade Implementation**
- Add typespecs to all public functions
- Implement proper error handling
- Add input validation
- Extract complex logic if needed
3. **Documentation**
- Module docs explaining purpose
- Function docs with examples
- Document patterns used
4. **Remove SPIKE Markers**
- Delete all # SPIKE: comments
- Code now production quality
5. **Quality Gates**
- Run /precommit (must pass)
- All tests passing
- Credo strict mode (Elixir) / Clippy (Rust)
- Ready for review
Agent will track progress with TodoWrite.
Step 5: TDD Migration Process
Agent follows strict TDD workflow:
Phase 1: Create Comprehensive Tests
Tests by language:
- Elixir: ExUnit with
@tag criticality: 9
- Rust:
#[test] with doc comments for criticality
- Python: pytest with markers
@pytest.mark.criticality(9)
See the language testing guide for framework-specific patterns.
Phase 2: Add Type Annotations
Type annotations by language:
- Elixir:
@spec function_name(arg_type()) :: return_type()
- Rust:
fn function_name(arg: ArgType) -> ReturnType
- Python:
def function_name(arg: ArgType) -> ReturnType:
See the language-specific patterns skill for type annotation patterns.
Phase 3: Implement Error Handling
Use language-appropriate error handling patterns:
- Elixir: Tagged tuples
{:ok, value} / {:error, reason}
- Rust:
Result<T, E> with ? operator
- Python: Exceptions or Result types
See skills/error-handling/references/{lang}.md for patterns.
Phase 4: Remove SPIKE Markers
Step 6: Quality Validation
Run precommit checks (language-aware):
## Quality Validation
Running /precommit on migrated code...
1. Compilation/Check: No warnings
2. Formatting: All files formatted
3. Lint: Strict mode passed
4. Tests: All tests passing
All quality gates passed!
Step 7: Update Documentation
Agent updates tracking:
## Documentation Updates
Updated `.claude/spike-debt.md`:
- Moved "Email Preferences" from Active to Migrated
- Archived with migration completion date
- Documented effort (actual vs estimated)
Updated `.claude/project-learnings.md`:
- Added pattern: JSONB preference storage
- Added gotcha: Need indexes on JSONB for search
- Added validation pattern for JSONB fields
Step 8: Present Migration Results
Comprehensive summary:
# SPIKE Migration Complete: Email Preferences
## What Was Migrated
**SPIKE code** (created 2025-01-16):
- 5 files, 85 lines core + 120 lines UI
- 2 smoke tests
- Basic functionality working
**Production code** (migrated 2025-01-23):
- 5 files fully upgraded
- 28 comprehensive tests (criticality 8-10)
- Full typespecs (6 functions)
- Complete error handling
- Documentation added
## Quality Improvements
| Metric | SPIKE | Production | Improvement |
|--------|-------|------------|-------------|
| Tests | 2 smoke | 28 comprehensive | +1300% |
| Typespecs | 0/6 (0%) | 6/6 (100%) | +100% |
| Error cases handled | 1/8 | 8/8 | +700% |
| Documentation | 0 lines | 45 lines | Added |
| Criticality rating | N/A | 8-10 | Production-ready |
| Precommit status | Warnings | All pass | Ready |
## Files Upgraded
**Core Logic**:
- lib/my_app/user_preferences.ex
- Added typespecs (6 functions)
- Added comprehensive tests (15 tests)
- Implemented validation
- Full error handling
- Module documentation
- Removed # SPIKE: markers
## Test Coverage
**Success Cases** (3 tests, criticality 9-10):
- Get preferences for existing user
- Update preferences with valid data
- Create default preferences for new user
**Error Cases** (8 tests, criticality 9-10):
- Invalid user ID returns :not_found
- Invalid preference keys rejected
- Database errors handled gracefully
- Concurrent updates handled
**Edge Cases** (5 tests, criticality 7-8):
- Empty preferences map
- Unicode in preference strings
- Null values in optional fields
## Precommit Status
All checks passed:
- Compilation: 0 warnings
- Formatting: All files formatted
- Lint: Strict mode, 0 issues
- Tests: 28/28 passing (100%)
Ready for production deployment!
## Technical Debt Closed
Updated `.claude/spike-debt.md`:
- Moved "Email Preferences" to Migrated section
- Archived with completion metrics
## Next Steps
1. Code review (optional, but recommended)
2. Deploy to staging
3. QA testing
4. Deploy to production
5. Monitor performance
Configuration
Migration Strictness
Based on project needs:
Standard migration (default):
- Comprehensive tests (criticality 8-10)
- Full typespecs
- Complete error handling
- Basic documentation
Enterprise migration:
- Extensive tests (criticality 9-10)
- Property-based tests for complex logic
- Comprehensive documentation
- Performance benchmarks required
- Security review
Rapid migration:
- Core tests only (criticality 9-10)
- Typespecs on public API only
- Essential error handling
- Minimal documentation
Error Handling
No SPIKE Code Found
No SPIKE Code Found
Searched for # SPIKE: markers in:
- lib/my_app/user_preferences.ex
No SPIKE markers detected.
This appears to be production code already.
If this is SPIKE code, ensure it's marked:
# SPIKE: [reason]
Or use /review to assess code quality.
SPIKE Not Ready for Migration
SPIKE Not Ready for Migration
Analysis of lib/my_app/experimental.ex:
Issues blocking migration:
1. Core functionality broken (3/5 tests failing)
2. Performance issues detected (O(n^3) complexity)
3. Design unclear (multiple approaches mixed)
Recommendation:
- Fix failing tests first
- Resolve performance issues (see /benchmark)
- Clarify design approach
Continue experimenting with /spike before migration.
Migration Failed - Tests Not Passing
Migration Failed
Migration incomplete: 5/28 tests still failing
Last status:
- Phase 1: Tests created
- Phase 2: Typespecs added
- Phase 3: Error handling incomplete
* 5 edge cases not handled
* Database error tests failing
Action: Developer fixing error handling...
Note: Migration will not complete until all tests pass.
TDD workflow enforced.
Best Practices
- Validate before migrating: Ensure SPIKE approach works
- Comprehensive tests first: Write all tests before changing code
- Preserve working code: Don't break what works
- Document learnings: Capture insights in project-learnings.md
- Run precommit: Must pass all quality gates
- Update tracking: Archive SPIKE in spike-debt.md
- Benchmark if needed: Validate performance assumptions
Migration Checklist
For each SPIKE file:
Before Migration:
During Migration:
After Migration:
Success Criteria
Migration succeeds when:
- All SPIKE markers removed
- Comprehensive test suite (criticality 8-10)
- All public functions have typespecs
- Complete error handling
- Documentation added
- Precommit checks pass (100%)
- No functionality broken
- spike-debt.md updated
- project-learnings.md updated
- Production-ready code
Related Skills
- spike - Create SPIKE prototypes (prerequisite workflow)
- feature - Full production implementation (alternative to SPIKE workflow)
- precommit - Validate quality gates
- review - Code review of migrated code
- benchmark - Performance validation (via performance-analyzer)
- learn - Document patterns discovered
