porting-workflow

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

# 1. Setup oracle adapter
cp scripts/oracle_template.py oracle/your_lib_oracle.py

# 2. Generate conformance fixtures
python3 scripts/update_conformance_template.py --operation series_add --mode strict

# 3. Run conformance gate
./SCRIPTS/conformance_gate.sh

Core Principles

1. Clean-Room: Never copy source code. Extract behavioral essence only.
2. Extract Spec First: Run oracle → capture output → create fixture → implement to match
3. Prove Parity Before Optimize: All packets pass before optimization
4. 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