Turning "It Probably Runs" into "It Runs Every Time": The Local Reproduction Protocol

**Specific Scenario**: You wrote an automation script that runs smoothly on your machine. You send it to a colleague, and they reply, "I'm getting an error." Or worse—three months later, you try to run it yourself and spend hours fixing the environment. This awkward "it works on my machine" situation isn't caused by poor code quality; the root cause is that **you didn't treat the reproduction process as part of the deliverable**.

What Is This Skill?

The Local Reproduction Protocol refers to describing, in a fixed set of steps, "how a stranger can reproduce your results from scratch in a clean environment" before delivering any script, configuration, or workflow. Crucially, you must execute these steps yourself. It is not just documentation; it is an **executable verification protocol**—it only counts as truly working if the protocol itself runs successfully.

When to Use It

- Scripts or workflows delivered for others to execute (internal tools, CI tasks, data pipelines)

- When you rely on third-party APIs, databases, or containers, and the other party's environment doesn't exactly match yours

- Tools you maintain yourself that haven't been re-run in over 30 days

- Any situation where "I ran it, so it's proven" needs to become "It's only proven if *they* can run it"

When Not to Use It

- One-off data analysis that ends the same day—writing reproduction docs takes longer than the analysis itself; just record a screen capture or take screenshots

- When the other party's environment is identical to yours (same machine, same container)—reproduction is redundant

- When requirements are changing rapidly and the code has already gone through three versions today—the written process will be obsolete instantly

How to Do It (5 Steps)

1. **Assume the reader is a "new hire who knows nothing"**: Avoid vague instructions like "run that script." Write out complete commands, including the working directory, arguments, and environment variables.

2. **List all implicit dependencies**: Python version, Node version, database tables that must exist, which file contains the API key, timezone settings. These are the number one killers of "it works on my machine."

3. **Write the minimal path**: Don't run every feature. Run only the shortest path for core functionality. The goal is to "determine if the environment is correct within 5 minutes," not to "verify all edge cases."

4. **Run through the process yourself from scratch**: Execute it in a new terminal, a new directory (or a clean container). If any step gets stuck, it’s a bug in your deliverable, not a user error.

5. **Include the process in the deliverable**: Put it in the "Quick Start" section of your README, or in a `REPRODUCE.md` file at the project root. Don’t keep it only in your head or in chat logs.

Gotchas

- **Pitfall 1 – "Good enough is fine"**: Writing "install dependencies" doesn't count. You must write `pip install -r requirements.txt`, and ensure `requirements.txt` is locked (generated via `pip freeze` or `poetry lock`).

- **Pitfall 2 – Environment drift**: Three months later, your machine will differ from the one you used when writing the protocol. Always do a fresh run on your current machine before each delivery; don’t trust "it worked last time."

- **Pitfall 3 – Confusing reproduction with testing**: The reproduction protocol verifies "whether the environment can run it," not "whether the code logic is correct." You need both, but mixing them up leads to gaps.

- **Pitfall 4 – Only documenting the happy path**: At minimum, include a note like "If step 1 fails, the most likely cause is XXX." This saves others (and your future self) significant troubleshooting time.

Minimal Viable Version

A template you can use today. Place this in your project root as `REPRODUCE.md`:

# Reproduction Steps (2026-09-02)

## Environment Requirements
- OS: macOS 14+ / Linux (glibc 2.31+)
- Python: 3.12.x (not 3.11, see Pitfall 2)
- Requires a .env file (see template in .env.example)

## Minimal Path (~3 minutes)
1. python -m venv .venv && source .venv/bin/activate
2. pip install -r requirements.lock
3. cp .env.example .env  # Fill in REAL_DB_HOST
4. python main.py --quick-check
   Expected output: "OK: 3/3 checks passed"

## If Step 4 Fails
- `ModuleNotFoundError`: Check if you activated the venv from Step 1
- `Connection refused`: Is DB_HOST in .env set to 127.0.0.1?

"It works on my machine" is the lowest standard. "It runs in a clean environment following my steps" is the delivery standard. This distinction is the distance between you and being considered "reliable."