\r \r

Author & Attribution\r

\r Original Author: flynn \r Contact: https://github.com/suifei/lang-migration-skill \r Role: Architect, Developer, Documenter \r Expertise: Software engineering, programming languages, AI workflow design \r Contributions: Designed the multi-phase pipeline, defined YAML schemas, implemented blocking protocol, and wrote comprehensive documentation for the skill.\r \r ---\r \r

Language Migration Skill\r

\r A systematic, multi-session, AI-executable workflow for migrating any open-source project\r from one programming language to another with 1:1 structural fidelity.\r \r

Core Principles\r

\r

1. No file is useless — every file in the source project is analyzed and assigned a migration strategy\r
2. Structural equivalence first — algorithm steps, loop structure, and control flow must mirror the source; behavioral equivalence is only used when the ecosystem gap makes structural impossible\r
3. No mock, ever — tests must use real implementations and real test data\r
4. Block, don't skip — when a decision cannot be made autonomously, stop and ask the human; never label-and-continue\r
5. State persists across sessions — all state lives in YAML files in the workspace, readable by any AI agent or human\r
6. Evidence before completion — every unit of work must produce verifiable evidence of execution before being marked done\r \r ---\r \r

Global Anti-Cheating Policy\r

\r This skill operates under the assumption that an AI agent may attempt to mark tasks complete\r without actually doing the work. Every phase has mechanisms to detect and prevent this.\r \r The Three Forms of AI Task Fraud (all prohibited):\r \r | Form | Example | Detection |\r |---|---|---|\r | Batch fabrication | Scripts generate IPO content without reading source | source_lines field will be wrong/empty |\r | Silent bulk-confirm | NEEDS_REVIEW → CONFIRMED without evidence | confirmation_evidence field empty |\r | Premature phase advance | Marking P3 DONE when entries have empty fields | Self-verification checks fail |\r \r Evidence Requirements by Phase:\r \r | Phase | Required Evidence |\r |---|---|\r | P2 | confirmation_evidence block per CONFIRMED entry |\r | P3 | READ_EVIDENCE + BEHAVIOR_PROOF per function; source_lines in every step; source_line on every magic number |\r | P4 | Compilation succeeds; IPO entry updated with target_lines; every fix triggers TDD Retrospective |\r | P5 | TEST OUTPUT EVIDENCE (actual runner output, not just "tests pass"); every fix triggers TDD Retrospective; full suite re-run after each fix; Checklist Summary at phase end |\r | Fix | retrospective-checklist.yaml entry with RCA → scope_scan_query (defined BEFORE scan) → scope scan results → consistent fix (see tdd-retrospective.md) |\r | PGR | Full audit report output in response listing every item checked; each FINDING citing exact artifact (file path, field, value); each FIXED citing same artifact after change; findings_count: 0 proven by enumerated item list; phase_gates.PGR_N.passed_at timestamp set only after zero-findings pass |\r \r TDD Retrospective Integration\r \r The Retrospective Protocol is mandatory at every fix point:\r

• Trigger: Compilation error, vet failure, structural deviation, test failure\r
• Steps: RCA (root cause analysis) → Checklist rule → Scope scan → Consistent fix\r
• Output: Entry in retrospective-checklist.yaml with root cause category and generalized rule\r
• Scope scan constraint: scope_scan_query MUST be written before scanning (prevents post-hoc bias)\r
• Impact: After each fix, full test suite is re-run; new failures each trigger independent retrospectives\r \r See Retrospective Protocol below and references/tdd-retrospective.md.\r \r Self-Verification is not optional. Each phase that has a Self-Verification Protocol\r must run it and output the report before advancing. The report must appear in the AI's\r response — not silently written to a file.\r \r The AI must never say "done" without evidence. "I have completed X" is not a valid\r completion statement without accompanying evidence artifacts.\r \r ---\r \r

Environment Detection\r

\r This skill runs in Claude Code, Cursor, OpenCode, or GitHub Copilot. At session start, detect the environment:\r \r

IF bash tool is available AND can write files → full_mode (Claude Code / OpenCode)\r
IF only file editing available → editor_mode (Cursor / Copilot)\r
```\r
\r
In **full_mode**: use bash scripts for scanning, run `scan_assets.py` directly.\r
In **editor_mode**: generate file lists manually by reading directory structure; instruct user to run scripts manually if needed.\r
\r
**Workspace location**: Always at the project root, in a directory called `migration_workspace/`.\r
\r
```\r
\x3Cproject-root>/\r
├── \x3Csource_code>/          ← original project (read-only, never modify)\r
├── \x3Ctarget_code>/          ← translated output (created by this skill)\r
└── migration_workspace/\r
    ├── migration-state.yaml      ← SESSION ENTRY POINT: read this first every session\r
    ├── asset-inventory.yaml\r
    ├── ecosystem-map.yaml\r
    └── ipo-registry.yaml\r
```\r
\r
---\r
\r
## Session Start Protocol\r
\r
**Every time you start a new session, do this first — no exceptions:**\r
\r
1. Check if `migration_workspace/migration-state.yaml` exists\r
   - YES → read it, understand current phase and `current_task`, resume from there\r
   - NO → this is a new project, run **P0 Bootstrap**\r
\r
2. Read `current_task` block. If `status: BLOCKED`, present the block to the user immediately and wait for their input before doing anything else.\r
\r
2b. **Check phase gate consistency**: For every phase marked `DONE` in the `phases` block, verify the corresponding `phase_gates.PGR_N.passed_at` is non-empty. If a phase is `DONE` but `passed_at` is empty, the PGR was not completed. Re-run PGR-N for that phase before advancing to the next phase. Load `references/phase-gate-review.md` for the audit criteria.\r
\r
3. **Check if the user's opening message is a status/gap question:**\r
   - Triggers: "还差什么", "进度怎样", "gap report", "show status", "还有哪些", "差多少", "完成了多少"\r
   - If YES → run P6 Gap Report immediately, output the summary to the user, then ask how to proceed\r
   - If NO → continue to step 4\r
\r
4. Load the language pair module: `references/lang-pairs/\x3Csource>-\x3Ctarget>.md`\r
\r
5. Proceed with the current phase.\r
\r
---\r
\r
## Five-Phase Pipeline\r
\r
```\r
P0 Bootstrap          → Initialize workspace, detect language pair, load lang-pair module\r
P1 Asset Scan         → Inventory every file, assign migration strategy\r
P2 Ecosystem Mapping  → Map all imports/types/stdlib to target equivalents, identify gaps\r
P3 IPO Analysis       → Document every function: Inputs, Process (incl. magic numbers), Outputs\r
P4 Translation        → Translate function by function using IPO registry + ecosystem map\r
P5 Verification       → Structural review + real-data behavioral tests (no mock)\r
P6 Gap Report         → Multi-dimensional completeness audit (invoke at any time)\r
```\r
\r
Each phase has a detailed reference file. Load it when entering that phase:\r
\r
| Phase | Reference File |\r
|-------|----------------|\r
| P0    | `references/phase-0-bootstrap.md` |\r
| P1    | `references/phase-1-asset-scan.md` |\r
| P2    | `references/phase-2-ecosystem-map.md` |\r
| P3    | `references/phase-3-ipo-analysis.md` |\r
| P4    | `references/phase-4-translation.md` |\r
| P5    | `references/phase-5-verification.md` |\r
| P6    | `references/phase-6-gap-report.md` |\r
| **Fix** | **`references/tdd-retrospective.md` ← mandatory on every fix in P4/P5** |\r
| **PGR** | **`references/phase-gate-review.md` ← mandatory between every phase transition** |\r
\r
---\r
\r
## Phase Gate Review Protocol (PGR)\r
\r
**A phase is not complete when the AI says it is complete. A phase is complete when PGR-N passes with zero findings.**\r
\r
After every phase finishes, the AI enters an autonomous self-auditing loop before advancing to the next phase. This loop requires no human involvement.\r
\r
### Updated Pipeline with PGR Gates\r
\r
```\r
P0 Bootstrap → [PGR-0] → P1 Asset Scan → [PGR-1] → P2 Ecosystem Map → [PGR-2]\r
    → P3 IPO Analysis → [PGR-3] → P4 Translation → [PGR-4] → P5 Verification → [PGR-5] → DONE\r
```\r
\r
### How PGR Works\r
\r
Each PGR-N runs an **enumerate → audit → fix → re-audit** loop:\r
\r
1. **Enumerate** — list every expected output of the completed phase\r
2. **Audit** — check each output against phase-specific criteria; record any FINDING with artifact evidence\r
3. **Tally** — if `findings_count == 0`, advance; if `findings_count > 0`, proceed to Fix\r
4. **Fix** — fix each FINDING autonomously; record artifact evidence of each fix\r
5. **Re-audit** — return to Step 1 (full re-enumeration required after every fix pass)\r
6. **Pass** — when zero findings: set `phase_gates.PGR_N.status: PASSED`; only then set `phases.PN_xxx: DONE`\r
\r
### Core Rule\r
\r
The phase status `DONE` in `migration-state.yaml` must NEVER be set directly at the end of a phase.\r
It is only set by PGR-N as the final action of a passed audit. Any session that finds a phase marked\r
`DONE` without a corresponding `phase_gates.PGR_N.passed_at` timestamp must re-run PGR-N before\r
advancing (see Session Start Protocol).\r
\r
### PGR Reference\r
\r
| Gate | Triggered After | Reference |\r
|------|----------------|-----------|\r
| PGR-0 | P0 Bootstrap | `references/phase-gate-review.md#pgr-0` |\r
| PGR-1 | P1 Asset Scan | `references/phase-gate-review.md#pgr-1` |\r
| PGR-2 | P2 Ecosystem Map | `references/phase-gate-review.md#pgr-2` |\r
| PGR-3 | P3 IPO Analysis | `references/phase-gate-review.md#pgr-3` |\r
| PGR-4 | P4 Translation | `references/phase-gate-review.md#pgr-4` |\r
| PGR-5 | P5 Verification | `references/phase-gate-review.md#pgr-5` |\r
\r
For the full protocol including per-phase audit criteria, finding formats, and anti-cheating rules,\r
see: `references/phase-gate-review.md`\r
\r
---\r
\r
## P0 Bootstrap (New Project)\r
\r
When `migration-state.yaml` does not exist:\r
\r
1. Ask the user:\r
   - Source language and directory path\r
   - Target language\r
   - Any known constraints or priorities\r
\r
2. Determine language pair key (e.g., `python-rust`). If the file `references/lang-pairs/\x3Cpair>.md` does not exist, load `references/lang-pairs/TEMPLATE.md` and tell the user this pair needs a new module — offer to draft one before continuing.\r
\r
3. Copy all five template files from `templates/` into `migration_workspace/`:\r
   - `migration-state.yaml` → fill in meta block\r
   - `asset-inventory.yaml` → empty, ready for P1\r
   - `ecosystem-map.yaml` → empty, ready for P2\r
   - `ipo-registry.yaml` → empty, ready for P3\r
   - `retrospective-checklist.yaml` → empty, ready for first P4/P5 fix\r
\r
4. Set `phases.P0_bootstrap: DONE` and `phases.P1_asset_scan: IN_PROGRESS`\r
\r
5. Immediately proceed to P1.\r
\r
---\r
\r
## Blocking Protocol\r
\r
When you cannot proceed without a human decision:\r
\r
1. Write to `migration-state.yaml`:\r
   ```yaml\r
   current_task:\r
     status: BLOCKED\r
     block_reason: "\x3Cspecific reason>"\r
     human_input_required: "\x3Cexact question for the human>"\r
   ```\r
\r
2. Output to the user:\r
   ```\r
   ⛔ BLOCKED — Human decision required\r
\r
   Phase: \x3Cphase>\r
   Item: \x3Citem_id>\r
\r
   Problem: \x3Cwhat cannot be resolved automatically>\r
\r
   Required decision: \x3Cspecific question>\r
\r
   Options considered:\r
     A) \x3Coption with trade-off>\r
     B) \x3Coption with trade-off>\r
\r
   Please reply with your decision and I will continue.\r
   ```\r
\r
3. Stop. Do not proceed to any other task.\r
\r
---\r
\r
## Progress Reporting\r
\r
After completing any task unit, update `migration-state.yaml` and output a brief status line:\r
\r
```\r
✅ [P2] numpy.float64 → f64 (behavioral, precision gap noted)\r
⛔ [P2] numpy.random.default_rng → BLOCKED (see above)\r
🔄 [P3] entropy.py::calculate_entropy → IPO documented\r
```\r
\r
At the end of each session, output a summary:\r
```\r
Session Summary\r
  Phase: P2 Ecosystem Mapping\r
  Completed this session: 12 entries\r
  Remaining: 34 entries\r
  Blocked: 1 (awaiting your decision on numpy RNG)\r
  Next session: resume P2 from item "scipy.stats.entropy"\r
```\r
\r
---\r
\r
## YAML Schema Reference\r
\r
For full field definitions of all five YAML files, see: `references/schemas.md`\r
\r
---\r
\r
## Retrospective Protocol\r
\r
Every fix in P4 or P5 — compilation error, vet failure, test failure, structural deviation — mandatorily triggers the TDD Retrospective Protocol. A fix without a retrospective is a local patch. A fix with a retrospective is a systemic improvement.\r
\r
See `references/tdd-retrospective.md` for the full protocol.\r
\r
### Why Root Cause, Not Phenomenon?\r
\r
Traditional bug tracking records **what failed**:\r
```\r
test_loop_tool_order FAILED\r
Expected execution order: [search, read, write]\r
Actual order: [write, read, search]\r
```\r
\r
This documents a symptom. The same underlying problem will manifest differently next time.\r
\r
The retrospective records **structural root causes**:\r
```\r
Root cause: ecosystem_gap_unapplied\r
Problem: Python dict preserves insertion order (3.7+). IPO registry documented this gap\r
and specified IndexMap/[]Entry as compensation. Translation used map[K]V, silently losing order.\r
```\r
\r
When the next function translates a Python dict, the AI can check the retrospective **before**\r
translating, preventing the error instead of fixing it after failure.\r
\r
Each migration's lessons become infrastructure for the next migration of the same language pair.\r
\r
### Core Design Principles\r
\r
#### 1. Root Cause Categories\r
\r
Nine predefined categories force abstract thinking:\r
- `ecosystem_gap_unapplied` — known gap was not applied\r
- `semantic_contract_lost` — implicit contract not preserved\r
- `invariant_not_transferred` — inferred invariant missing\r
- `magic_number_decontextualized` — constant without context\r
- `control_flow_collapsed` — IPO steps merged/reordered\r
- `error_class_narrowed` — specific exception generalized\r
- `side_effect_dropped` — documented side effect missing\r
- `ipo_source_lines_wrong` — P3 analysis based on wrong lines\r
- `test_fixture_mismatch` — fixture format changed\r
- `other` — describe if no category fits\r
\r
Each fix produces exactly ONE entry with ONE category. No category hopping.\r
\r
#### 2. Scope Scan: Query BEFORE Execution\r
\r
**Mandatory rule**: Define `scope_scan_query` before scanning.\r
\r
This prevents LLM cheating patterns like:\r
- Scan codebase → observe results → retroactively define "the scope that matches findings"\r
\r
Example:\r
```yaml\r
Root cause: dict insertion-order dependency not preserved\r
\r
scope_scan_query: "grep -rn 'map\[string\]' internal/ --include='*.go'"\r
(The query is written BEFORE executing the grep. It appears in the retrospective entry.)\r
```\r
\r
The query is your prediction of where the root cause manifests. If results don't match predictions,\r
it's a signal that the root cause analysis was incomplete.\r
\r
#### 3. Consistent Fix Across All Instances\r
\r
Scope scan identifies all instances with the same root cause. All are fixed simultaneously\r
using the same fix strategy. This prevents:\r
- The bug reappearing in a file not yet reviewed\r
- Maintenance inconsistency (same bug, different fixes in different places)\r
\r
After scope fix, **full test suite is re-run** (not just the failing test). Any new failures\r
trigger independent retrospectives — they are not merged.\r
\r
#### 4. Ecosystem Map Auto-Update\r
\r
Flag `ecosystem_map_update_required: true` in the retrospective entry triggers automatic\r
update to `ecosystem-map.yaml` at phase-end.\r
\r
Example:\r
- P4: dict ordering bug found, fixed, retrospective entry created\r
- Entry sets `ecosystem_map_update_required: true`\r
- P4 end: ecosystem map updated with stronger guidance\r
- **Next migration benefits** — same class of error is harder to commit\r
\r
### Checklist Summary (Phase-End Report)\r
\r
At the END of P4 and P5, output a **Checklist Summary**:\r
\r
```\r
RETROSPECTIVE CHECKLIST SUMMARY (end of P5):\r
  total_rca_entries:          24\r
  total_instances_found:      67\r
  total_instances_fixed:      64\r
  instances_deferred:         3\r
\r
Most common root cause categories:\r
  1. ecosystem_gap_unapplied         (9 entries)   → suggests ecosystem map gaps\r
  2. semantic_contract_lost          (6 entries)   → suggests IPO analysis depth issue\r
  3. magic_number_decontextualized   (4 entries)   → suggests naming discipline\r
\r
Ecosystem map updates applied: 3\r
  - dict iteration order guidance strengthened\r
  - float precision rules clarified\r
  - exception mapping for stdlib errors expanded\r
\r
Next language pair migration of python→go should consult these 24 entries\r
before beginning translation — prevents category-1 errors upfront.\r
```\r
\r
This summary is the handoff to the next migration team or agent.\r
\r
### Integration with P4/P5\r
\r
**P4 Trigger:**\r
```\r
Compilation/vet error found\r
  ↓\r
Fix applied\r
  ↓\r
Trigger: Retrospective Protocol\r
  ↓\r
RCA → Checklist rule → Scope scan query → Scope scan → Consistent fix\r
  ↓\r
Resume P4 from next file\r
```\r
\r
**P5 Trigger:**\r
```\r
Structural deviation or test failure found\r
  ↓\r
Fix applied\r
  ↓\r
Trigger: Retrospective Protocol\r
  ↓\r
RCA → Checklist rule → Scope scan query → Scope scan → Consistent fix\r
  ↓\r
Full test suite re-run (not just failing test)\r
  ↓\r
If new failures: each triggers independent retrospective\r
  ↓\r
Resume P5 from next function\r
```\r
\r
For detailed protocol, see: `references/tdd-retrospective.md`\r