Worktree Isolation for OSS Bugs: A Review Packet Maintainers Can Trust

On a typical issue tracker, a contributor clones a small HTTP client and treats a timeout as a one-line constant change. The pull request description cites a single local test run on the newest interpreter the laptop already had installed. Continuous integration then fails on an older runtime the contributor never installed, and the thread spends days reconstructing a reproduction. Maintainers are not rejecting the idea of a fix; they are rejecting a change that never isolated the failing command.

Public discussion around AI coding tools often frames models as ready to emit complete patches from a full repository dump. That framing skips the part of open source work that still fails in practice: proving the bug, constraining the diff, and showing one command before and after. A model that reads an entire tree will invent helpers, ignore matrix cells, and rewrite style the project does not use. A smaller packet built inside an isolated git worktree gives both humans and models the same evidence.

Whole-repo pastes hide the failure

Open source reviews fail for mechanical reasons that have little to do with model quality or contributor intent. The reviewer cannot see which command actually failed, which files were incidental, or which contributing rules the author actually read. A paste of the repository also hides generated lockfiles, vendored snapshots, and local configuration that should never leave the laptop.

A useful packet answers four points with files rather than adjectives:

• Which worktree and commit reproduced the bug in isolation
• Which exact command failed, including arguments and exit status
• Which files the patch actually touches, shown as a unified diff
• Which project rules constrain the change, quoted from tests or CONTRIBUTING

The rest of this article proposes a workflow. Commands are examples for a typical Python library and should be adapted to the target project's documented test runner.

Isolate the bug in a throwaway worktree

Cloning a second full copy is slower than git worktree, and a second worktree keeps failed experiments off the main checkout. The contributor should start from the revision named in the issue, not from a personal branch that already contains unrelated formatting. A clean tree makes later diffs honest, because generated files from a previous attempt will not leak into the patch.

# Proposed workflow — adapt paths and the issue SHA to the target repository.
git fetch origin
git worktree add ../repro-issue-1842 origin/main
cd ../repro-issue-1842
git switch -c repro/issue-1842

If the issue names a tag or a commit, check that revision out before installing dependencies so the failing command matches the report. Project docs, not a model guess, should decide how extras and test tools are installed.

# Example only: pin the reported revision, then install from the project docs.
git checkout --detach 7c1a9e4
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Capture the failing command as the contract

A stack trace in an issue comment is not a contract. The contract is a command that exits non-zero in this worktree and will be re-run after the patch. Write that command into a file so later review, CI, and any model see the same bytes.

# Proposed capture: store stdout, stderr, and the exit code beside the tree.
mkdir -p .repro
printf '%s\n' 'python -m pytest tests/test_retry.py::test_timeout_default -q' > .repro/failing_cmd.sh
chmod +x .repro/failing_cmd.sh
set +e
.repro/failing_cmd.sh > .repro/before.txt 2>&1
echo $? > .repro/before.exit
set -e
cat .repro/before.exit

If the exit file does not contain a non-zero status, stop immediately. The environment does not yet reproduce the bug, and a patch would be guesswork. Common misses include the wrong extra, a missing locale, and a test that only fails under a specific language minor version.

Truncate the log before anyone pastes it into a review tool. Long traces bury the assertion, and remote reviewers should not need the full pip wheel noise.

# Proposed helper: keep the packet readable.
from pathlib import Path

LIMIT = 80
log = Path(".repro/before.txt").read_text(errors="replace").splitlines()
Path(".repro/before.tail.txt").write_text("\n".join(log[-LIMIT:]) + "\n")

Keep the patch inside the failing command's neighborhood

Once the command fails, search only the modules that command imported. A model asked to fix retries will often rewrite the public client class, add a helper the suite never calls, or change default arguments that other tests rely on. The human author should produce the smallest diff that turns the captured command green.

# Example investigation commands, not a diagnosis of any real project.
python -c 'from retry_client import Client; print(Client.__module__)'
git grep -n "timeout" -- "*.py"
git grep -n "def test_timeout_default"

After editing, re-run the same script without changing its arguments. If unrelated files appear in git diff --stat, reset them before the packet is built. Formatters that touch the whole tree belong in a separate commit, and only when the project already requires that formatter in CI.

set +e
.repro/failing_cmd.sh > .repro/after.txt 2>&1
echo $? > .repro/after.exit
set -e
test "$(cat .repro/after.exit)" = "0"
git diff --stat
git diff -- "*.py" "tests/*.py"

A second local command is worth running when the project already documents it: the unit node that failed, then the nearest file or folder that guards regressions. Expanding to the full suite too early hides the original contract inside unrelated noise.

Build a review packet instead of uploading the tree

The packet is a single markdown file plus the unified diff. It should be small enough to read in one sitting and free of secrets, absolute home paths, and vendor directories. Optionally append short quotes from CONTRIBUTING.md, the issue's acceptance comments, and the project's test matrix file.

# Proposed packet builder. Review the output before any remote upload.
{
  echo "# Review packet for issue 1842"
  echo
  echo "## Reproduction"
  echo "- commit: $(git rev-parse HEAD)"
  echo "- command: \`$(tr '\n' ' ' < .repro/failing_cmd.sh)\`"
  echo "- exit before: $(cat .repro/before.exit)"
  echo "- exit after: $(cat .repro/after.exit)"
  echo
  echo "## Failing command output (truncated)"
  echo '```

'
  tail -n 80 .repro/before.txt
  echo '

```'
  echo
  echo "## Diff"
  echo '```

diff'
  git diff -- "*.py" "tests/*.py"
  echo '

```'
} > .repro/REVIEW_PACKET.md

Do not paste entire policy documents into the packet. A model that receives twenty pages of contributing guide will ignore the one rule that matters, such as no new runtime dependencies. Quote the rule in one block, then keep the rest of the file mechanical.

Files that must stay out of the packet

• .env, tokens, cookie jars, and editor settings
• node_modules, .venv, vendor, and built wheels
• Unrelated dirty files from a formatter or a failed rebase
• The full git object store; the worktree diff is enough

Decision table: what a model is allowed to do

This table is the working artifact of the workflow. The model does not replace the test runner, and it does not replace the project's hosted CI. It reviews a bounded packet after the failing command has already turned green.

Packet section	Human owner	Model role	Reject if
Failing command	Contributor	May suggest a narrower test node id	The command was never run locally
Diff	Contributor	Review only: style, missing tests, API breakage	The model authors files not in the packet
CONTRIBUTING quotes	Contributor	Check the diff against quoted rules	The quote is paraphrased from memory
CI matrix note	Contributor	Flag untested runtimes	The model claims a matrix cell passed without a log

Treat any suggested patch from the model as a comment, not as a commit. Re-run .repro/failing_cmd.sh after every accepted edit, even when the comment looks purely stylistic. Style-only rewrites still break public signatures in libraries with downstream users.

Where a free model and a free server fit

Some contributors cannot install every CI runtime on a laptop, and some want a second pass on the packet before the pull request. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option, which can re-run the captured command and return comments on REVIEW_PACKET.md rather than on a full repository archive. Contributors who already have a green local command can use that optional remote pass, then still wait for the project's hosted CI before pinging maintainers.

The useful split stays strict. The server re-runs .repro/failing_cmd.sh in a clean environment. The model receives the packet and returns a review, not a rewritten tree. If the remote command disagrees with the local exit codes, the packet is incomplete and the pull request should wait.

Limitations and who should skip this

The workflow does not claim that a free server matches every OS, libc, or language version in a project's matrix. It does not verify performance, concurrency, or network flakiness that only appears under load. Models still invent APIs that look plausible in a diff comment and still miss license headers the project requires.

Skip this approach in the following cases:

1. The bug is under a security embargo, or the fixture contains production data.
2. Reproduction needs hardware or licensed runtimes the remote environment cannot provide.
3. The change is a documentation typo that never needed a model or a second server.
4. The contributor cannot compare the model's review against the actual test log.

A review packet is extra ceremony for a one-character fix in a personal script. It earns its keep on libraries with downstream users, public APIs, and CI matrices that a laptop will not cover. It also fails closed: if the captured command never failed, there is no patch to review, and if the packet includes secrets or the entire tree, the remote step should not run.

Closing sequence

The sequence is isolate, capture, patch, packet, then optional remote review. Maintainers can re-run one command and read one diff without reconstructing the author's laptop. Models stay useful when they are downstream of evidence, not when they are asked to invent the evidence from a repository zip. Those two stops prevent the most common failure in AI-assisted open source work: a fluent diff that never reproduced the bug.