MABELab-RS/porting/TRANSLATION_PLAYBOOK.md

Translation Playbook

This playbook outlines repeatable steps for translating C++ to Rust using LLMs.

0) Choose a small vertical slice

• One header + corresponding implementation.
• Confirm dependencies are already scaffolded (traits exist).

1) Header → Rust traits/structs (no logic)

• Input: C++ header.
• Extras: glossary, style, determinism docs, an example skeleton from a similar module.
• Output: compilable Rust module with todo!() bodies, doc comments preserved.

2) Implementation pass

• Input: C++ .cpp (or .hpp inline bodies), the Rust skeleton from step 1.
• Ask: preserve semantics; avoid global state; return Result<_, _> on fallible paths.
• Output: implemented functions + unit tests.

3) Compile & test

• Run cargo build, cargo clippy -D warnings, cargo test.
• If failures: feed only the relevant compiler error lines and the failing snippet into a review-fixit prompt.

4) Parity (optional)

• If MABE2 compiled locally, run tiny deterministic scenarios on both and compare key metrics (seed, steps, mean fitness).
• Record tolerances for float diffs.

5) PR discipline

• One module per PR; include tests and brief README note summarizing changes and any TODOs