| name | porting-workflow |
| description | Master skill for the 5-phase library porting workflow. Use when user wants to port a library from one language to another (pandas → Rust, NumPy → Rust, Redis → Rust, etc.) with full feature parity. This skill provides the overall workflow pattern while porting-extract and porting-implement provide phase-specific guidance. |
Porting Workflow - Master Skill
A comprehensive pattern for porting libraries between languages while maintaining full behavioral parity with the original.
When to Use This Skill
- User wants to port a library (pandas, numpy, redis, scipy, etc.) to another language
- User wants to reimplement a library with full feature parity
- User mentions "port library", "migrate to Rust", "clean-room reimplementation"
- User wants to understand or execute the 5-phase porting methodology
The 5 Phases
Phase 1: Bootstrap + Planning (1-2 weeks)
- Define scope (what's IN, what's OUT)
- Choose target language (Rust recommended)
- Set up project structure (monorepo vs multi-crate)
- Freeze compatibility contract
Phase 2: Extract (2-4 weeks) - CRITICAL
Extract behavioral essence through oracle testing:
- Write oracle script to run original library
- Run operations with known inputs → capture outputs as fixtures
- Create 1000+ conformance packet fixtures (JSON)
- Document edge cases (NaN, null, dtype coercion)
- See
porting-extract skill for details
Phase 3: Architecture (2-3 weeks)
- Design crate boundaries
- Define strict/hardened mode behavior
- Design storage layout (columnar vs row-based)
- Design index alignment system
Phase 4: Implement (8-16 weeks)
- Feature-by-feature implementation
- Run conformance after EVERY feature
- Never let parity drift accumulate
- See
porting-implement skill for details
Phase 5: QA + Optimize (2-4 weeks)
- 100% conformance pass rate required
- Profile → Optimize → Prove isomorphism → Accept
- Optimization ONLY after parity proven
Key Documents
| Document | Purpose |
|---|
| PORTING_METHODOLOGY.md | Clean-room principle, 4-step process |
| PHASES.md | 5-phase breakdown |
| CONFORMANCE_HARNESS.md | Differential testing framework |
| CONFORMANCE_PLAN.md | Planning conformance |
| SCRIPTS/conformance_gate.sh | CI gate that blocks on parity failure |
Quick Start
cp scripts/oracle_template.py oracle/your_lib_oracle.py
python3 scripts/update_conformance_template.py --operation series_add --mode strict
./SCRIPTS/conformance_gate.sh
Core Principles
- Clean-Room: Never copy source code. Extract behavioral essence only.
- Extract Spec First: Run oracle → capture output → create fixture → implement to match
- Prove Parity Before Optimize: All packets pass before optimization
- Zero Unsafe:
#![forbid(unsafe_code)] on every crate
Commit Pattern
feat(<crate>): add <feature> parity (<ticket-id>)
Examples:
feat(my-crate): add series_add parity (TICKET-001)
feat(my-crate): add read_csv lineterminator parity (TICKET-002)
Quality Gates
Run after EVERY change:
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --workspace
./SCRIPTS/conformance_gate.sh
