Leave a Replay Script, Not a Transcript

A backend engineer opened a pull request at sixteen forty after an afternoon spent steering a coding agent. The ticket claimed the pagination bug was gone, the tests were green, and the cache key no longer collided under concurrent load. Reviewers cloned the branch onto a laptop that had never seen the chat and watched the build fail before the first test even started. The session had felt like engineering while the agent still held context, then collapsed like a stage set after the lights died.

That failure is not a mystery about model quality so much as a mystery about evidence that cannot leave the room. A chat transcript is a memoir of intent, not a receipt that another machine can cash. Teams that treat the memoir as a merge criterion keep discovering that the work existed only inside one warm session. A time-boxed spike can refuse that bargain by demanding a replay script the agent must leave behind.

The hypothesis for this spike is deliberately narrow and written down before any prompt is sent. Given a frozen git worktree, one failing characterization test, and a ninety-minute clock, the agent must emit a replay script. That script restores a clean tree, applies only committed files, and exits zero on a host that never hosted the chat. If the script cannot be copied to a second machine and run without the agent, the spike is killed even when the conversation sounded confident. Ship-or-kill in this ritual means the leftover witness, not the storytelling quality of the session.

Think of the replay script as a black-box recorder rather than a pilot's memoir written after a tense landing. The memoir can be eloquent, selective, and sincerely wrong, because it is composed while the engines are still warm. The recorder is boring on purpose, capturing commands, inputs, and exit statuses that another cockpit can play back later. Engineering, inside this small ritual, is whatever still works after the agent has left the building.

The proposed layout is a disposable directory that the human operator creates before the clock starts. Nothing in that directory is sacred except the hypothesis file and the failing test that already exists on main. The agent may write a patch and a replay script, yet it may not ask reviewers to trust the warmth of the session. The tree below is a proposal, not a captured run from a production incident.

spike-replay/
  HYPOTHESIS.md
  clock.env
  fixtures/
    failing_test.py
  leftover/
    replay.sh
    patch.diff
    RESULT.json

The hypothesis file states one predicate in language a shell script can later honor without debate. A sample file might read as follows, and it should stay short so nobody smuggles extra hopes into the spike.

# Hypothesis
On a clean clone of commit 9f3c1aa, applying leftover/patch.diff
and running leftover/replay.sh exits 0, and
pytest fixtures/failing_test.py -q reports one passed test.
Kill the spike if replay.sh is missing, calls an agent, or
reads files outside the clone.

The clock file freezes the budget so the spike cannot quietly become an unstructured afternoon of retries. The values below are operator-chosen constants for the ritual, not product limits of any vendor or model.

# clock.env — proposed constants for a local spike
SPIKE_MINUTES=90
HYPOTHESIS_ID=replay-witness-001
BASE_SHA=9f3c1aa
ALLOWED_PATHS='src/pagination.py tests/test_pagination.py leftover/replay.sh leftover/patch.diff'

The characterization test should already fail on main, because a spike that invents both the bug and the fix is writing fiction. The example below is a proposed pytest module for a pagination helper that drops the last page when the total is an exact multiple of the page size.

# fixtures/failing_test.py — proposed characterization test
import pagination

def test_last_page_when_total_divides_page_size():
    rows = list(range(20))
    page = pagination.page(rows, page=2, size=10)
    assert page == [10, 11, 12, 13, 14, 15, 16, 17, 18, 19]

Before the agent starts, the operator clones a clean worktree and records a fingerprint of the source tree. That fingerprint later proves the replay did not lean on leftover editor buffers or hidden agent caches. The commands below are ordinary git and hashing usage, and they should be run by the human rather than by the model.

git fetch origin
git worktree add /tmp/spike-replay-wt "$BASE_SHA"
cd /tmp/spike-replay-wt
git rev-parse HEAD > /tmp/spike-replay/BASE_HEAD.txt
find src tests -type f -print0 | sort -z | xargs -0 sha256sum \
  > /tmp/spike-replay/TREE_BEFORE.txt

The replay script is the only artifact allowed to argue for a ship decision after the session ends. A proposed shape is a bash file that refuses the original chat directory and prints a small RESULT.json file. Anything that shells out to an agent CLI, reads a chat history folder, or mutates files outside the allowed paths is an automatic kill.

#!/usr/bin/env bash
# leftover/replay.sh — proposed witness; unexecuted template
set -euo pipefail
cd "$(git rev-parse --show-toplevel)"
test -f leftover/patch.diff
git apply --check leftover/patch.diff
git apply leftover/patch.diff
python -m pytest fixtures/failing_test.py -q
python - <<'PY'
import json, pathlib, subprocess, os
head = subprocess.check_output(["git", "rev-parse", "HEAD"], text=True).strip()
payload = {
    "hypothesis_id": os.environ.get("HYPOTHESIS_ID", "unset"),
    "head": head,
    "status": "pass",
}
pathlib.Path("leftover/RESULT.json").write_text(json.dumps(payload, indent=2))
print(json.dumps(payload))
PY

A second host, or a second worktree on the same laptop, is what turns that script into evidence instead of theater. The operator copies only the replay script, the patch, and the hypothesis file, then repeats the clone at the frozen base commit. If the script needs the original session's virtualenv, the agent's notes, or an unsaved buffer, the hypothesis is dead. That second run is the whole point of the ninety minutes, because the agent is not invited to the replay.

Some teams will want the agent itself to run on a machine that is not the developer's everyday laptop, because laptops accumulate helpful accidents over ordinary weeks. Cached credentials, global language toolchains, and yesterday's container layers all act like backstage crew who remain after the play ends. A free remote server, used as a clean room rather than as a gift of extra capacity, keeps those accidents off the stage for the length of the spike. MonkeyCode's free model access and free server option can host that clean-room session so the spike starts without the laptop's hidden inventory.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The product belongs in that clean-room role and nowhere else in the method. The same replay still works if the agent runs locally, provided the script is copied to a second tree that never saw the chat. Claims about particular model names, token quotas, hardware sizes, or guaranteed runtimes are omitted because they are not part of the ritual and they go stale quickly. The spike cares about whether the leftover script exits zero, not about which invoice the session would have produced.

The human operator does not negotiate extra scope once the ninety-minute watchdog is running in a second terminal. A short wrapper can terminate the session when the clock expires, and it should be started before the first prompt so the limit is not a mood. The snippet below is a proposed watchdog, not a measured benchmark of any coding assistant or hosted runtime.

# proposed watchdog; run in a separate terminal
source clock.env
START=$(date +%s)
LIMIT=$((SPIKE_MINUTES * 60))
while true; do
  NOW=$(date +%s)
  if [ $((NOW - START)) -ge "$LIMIT" ]; then
    echo "SPIKE_TIMEOUT hypothesis=$HYPOTHESIS_ID" >&2
    exit 124
  fi
  sleep 5
done

When the clock stops, the operator does not hold a retrospective about how reasonable the agent sounded during the session. The kill path is mechanical if the replay script is missing, calls an agent, fails to apply at the frozen commit, or still fails on the second host. The ship path is equally mechanical when the second-host replay exits zero, the result file matches the hypothesis identifier, and the diff stays inside the allowed files. Either way, the transcript is archived as color commentary and is never treated as proof.

A tiny Python checker can make the kill path harder to talk around during a hurried review. The proposed module compares the earlier fingerprint with a post-replay inventory and rejects surprise files the way a customs officer rejects an undeclared suitcase. It is dull on purpose, which is the opposite of a chat that wants to keep explaining its own cleverness after the clock has already stopped.

# proposed leftover/check_inventory.py — unexecuted
import pathlib, subprocess, sys

raw = pathlib.Path("clock.env").read_text()
allowed = set(raw.split("ALLOWED_PATHS=")[1].split("'")[1].split())
diff = subprocess.check_output(["git", "diff", "--name-only"], text=True)
surprise = [line for line in diff.splitlines() if line and line not in allowed]
if surprise:
    print("KILL unexpected paths:", surprise)
    sys.exit(2)
print("INVENTORY_OK")

This ritual is a poor fit for exploratory design work where the question is still which product to build next. It is also a poor fit for incidents that need live production traffic, because a ninety-minute clean room will not see those failures. Teams that already enforce a green CI gate on every agent patch may find the extra replay script redundant, and they should keep the stricter gate they already trust. The audience for the witness script is a group that has been merging memoirs and wants one afternoon of countermeasure, not a new religion about assistants.

Public conversation around AI coding often blurs a session that felt productive with a change that another engineer can rebuild from scratch. That blur is older than any particular model release, and it does not require a vendor ranking to diagnose on a working team. The replay script is a small, unfashionable object that restores a boundary the chat interface keeps erasing. The agent may talk for ninety minutes, and only the commands that survive eviction count as engineering once the session is gone.