Fill a Retry Docket Before the Second Pass

A second model pass should wait for a written docket. Cheap retries hide the real defect under fresh wording. Review time disappears when nobody names the stop rule.

That rule belongs in the team wiki before the next generation. The page stays short enough to read during a handoff. The gate stays stricter than the prompt that failed.

Public developer threads keep returning to retries and weak checks. A second generation can sound cleaner while the assumption stays wrong. Agreeable wording is not evidence that the patch is safe.

This playbook treats the second pass as a controlled shift. The model does not judge its own repair. A free practice host does not become the production lane.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. The operator describes free model access and a free server option. MonkeyCode is described here as an open-source project. This draft does not freeze quotas, names, hardware, or duration. Those terms can move between one week and the next. A squad reads the live project notes before it relies on them.

The free lane still changes how a retry feels. A second pass looks cheap when no personal invoice appears. A free server can hold the practice checkout off the main branch.

Cheap is not the same thing as harmless. Noise still lands in review and in the shared log. The docket exists to make that cost visible.

A ferry will not leave the dock without a paper slip. The slip names the cargo, the dock, and the last safe turn. No slip means the boat stays tied to the pier.

The retry docket is that slip for a failed patch. It records the failing check before anyone asks for new words. It also records the one condition that ends the loop.

The docket works like a library hold slip, not like a new book. The slip points at one title and one pickup window. It does not let the reader reorder the whole shelf.

Three roles keep the slip from turning into theater. The Patch Author owns the failing change and the first check. The Docket Clerk refuses a second pass until every field is present.

The Host Steward runs the practice host and returns logs. The steward does not return a verdict on the design. Logs travel better than opinions across a shift change.

The author does not approve their own retry. The clerk does not edit the patch during the field check. The steward does not merge anything from the practice host.

Those walls stop a friendly loop from becoming a silent rewrite. A missing field sends the work back to the author. A vague failure reason sends the work back as well.

A bare request to try again is not evidence. The return trip is the control, not a delay for its own sake. One complete docket buys one second pass, not a series.

Handoff one starts when a named check fails. The author files the docket in the wiki or on the pull request. Handoff two starts when the clerk marks that page complete.

Handoff three starts only on the practice host. The steward runs the same failing command before any generation. The steward runs that same command again after the second pass.

The clerk then closes the docket with one of three outcomes. The outcomes are fixed, still failing, or human rewrite. The steward removes the practice checkout on the same day.

The page below is a proposal for the wiki, not a measured rollout. Names in the sample are placeholders, not a real rotation. The names change to people who can actually refuse a pass.

# Retry Docket — one-page run

Status stays draft until the clerk marks it complete.
Scope is one failing patch, one second pass, and one practice host.

Docket id, patch author, and failing check name sit on separate lines.
The first failing command, expected result, and actual result follow.
The next lines name what must change and what must stay unchanged.
Secrets present must read no.
Practice host must name the free server lane, not production.
Stop rule must read one second pass, then a human rewrite.
Clerk and steward names close the header.

The author attaches the failing command output.
The clerk rejects blank fields and secret-looking values.
The steward checks out the patch on the practice host only.
The steward runs the same failing command before any generation.
The author may request one second pass if the failure still matches.
The steward runs the same command after that second pass.
The clerk closes the docket as fixed, still failing, or human rewrite.
The steward deletes the practice checkout on the same day.

The wiki page is the human copy of the same gate. The flat file is the machine copy the checker reads. Both copies must name the same failing check.

The checker below is a proposed gate for the wiki. It is not a measured control from a live fleet. It reads a flat text file and rejects blank required fields. It also rejects a docket where the author clerks their own retry.

#!/usr/bin/env python3
"""Proposed docket check. Not executed as a fleet control."""

import sys
from pathlib import Path

REQUIRED = [
    "docket_id",
    "patch_author",
    "failing_check",
    "first_command",
    "expected",
    "actual",
    "must_change",
    "must_stay",
    "secrets_present",
    "practice_host",
    "stop_rule",
    "clerk",
    "steward",
]

def parse_simple(text: str) -> dict:
    data = {}
    for raw in text.splitlines():
        line = raw.strip()
        if not line or line.startswith("#") or ":" not in line:
            continue
        key, value = line.split(":", 1)
        data[key.strip()] = value.strip()
    return data

def main() -> int:
    if len(sys.argv) != 2:
        print("usage: python3 retry_docket.py docket.txt")
        return 2
    data = parse_simple(Path(sys.argv[1]).read_text(encoding="utf-8"))
    missing = [key for key in REQUIRED if not data.get(key)]
    if missing:
        print("reject: missing " + ", ".join(missing))
        return 1
    if data["secrets_present"].lower() != "no":
        print("reject: secrets must be no")
        return 1
    if data["stop_rule"] != "one-second-pass-then-human":
        print("reject: stop rule drifted")
        return 1
    if data["patch_author"] == data["clerk"]:
        print("reject: author cannot clerk their own docket")
        return 1
    print("complete: second pass may be queued once")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

The clerk runs it from the repository root before the steward queues work. A nonzero exit means the second pass stays parked. A zero exit means one pass may start, not that the patch is correct.

python3 retry_docket.py docket.txt
printf '%s\n' "docket_exit=$?"

The sample invoice case is fictional and unexecuted in this draft. Half-up rounding is only a stand-in for a named failing check. The author swaps in the real test name before the file goes live.

docket_id: RD-2026-10-13-014
patch_author: dev.a
failing_check: test_invoice_rounds_half_up
first_command: python3 -m unittest tests.test_invoice
expected: half-up rounding on 1.005
actual: half-even result 1.00
must_change: prompt must cite the rounding test name
must_stay: public function signature
secrets_present: no
practice_host: free-server-lane
stop_rule: one-second-pass-then-human
clerk: dev.b
steward: dev.c

The shell capture is also a proposal for the practice host. It stores the command, the time, and the exit code beside the output. The clerk compares the before log and the after log before closing.

#!/bin/sh
# Proposed log capture. Not executed in this draft.
set -eu
label="${1:?need before-or-after}"
shift
mkdir -p .retry-logs
log=".retry-logs/${label}.log"
tmp="$(mktemp)"
set +e
"$@" >"$tmp" 2>&1
code=$?
set -e
{
  echo "label=${label}"
  echo "utc=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
  echo "cmd=$*"
  echo "exit=${code}"
  cat "$tmp"
} > "$log"
rm -f "$tmp"
echo "wrote ${log} exit=${code}"
exit "$code"

sh capture_retry_log.sh before python3 -m unittest tests.test_invoice
sh capture_retry_log.sh after python3 -m unittest tests.test_invoice
diff -u .retry-logs/before.log .retry-logs/after.log || true

The diff command may exit nonzero when the logs differ. That nonzero state is information, not a failed capture. The clerk reads the hunks before anyone calls the retry a fix.

That script stays off production data and off secret files. Tokens, keys, and customer rows stay out of the wiki page. The secrets field exists so the clerk can reject the page early.

Free model access participates only after the docket is complete. The author may use it for that single second pass. The prompt must cite the failing check and the must-stay line.

The free server option participates as the practice host label. The steward follows the current setup notes rather than a frozen recipe. This article does not invent machine size, region, or lifetime.

A vanished lane stops the shift and forces a rewritten plan. Yesterday's pool is not assumed to exist this morning. A docket that cites a vanished host is incomplete.

The stop rule is the part teams try to soften. One second pass is the whole allowance in this playbook. A third generation needs a new docket and a human rewrite plan.

Still failing after the second pass is a successful use of the gate. The gate did its job by ending the loop. The author then repairs the code by hand or files a narrower task.

This approach will not fit every team desk. It does not fit when one person owns the toy project and the review. It does not fit when the change already sits in an incident channel.

It does not fit when the work needs an audited model contract. A free lane is a practice lane, not a compliance story. It does not fit when the failing check cannot be named in one line.

It also does not fit when the patch touches secrets, billing, or production data. The sample checker cannot see intent hiding inside a diff. A human still has to read the change before any merge.

The limits sit in the open on purpose. The script does not score quality, speed, or model taste. No benchmark in this draft claims a win over another tool.

The clerk can rubber-stamp fields without reading the failure. The steward can leave a practice process running overnight. The author can change three things while the docket names one.

Those failures are process failures, not model mysteries. The page makes them easier to see during the next handoff. It does not remove the need for tests that already exist.

The clerk pins the live access notes beside the wiki page. The pin happens on the day the team adopts the docket. If the notes and the page disagree, the live notes win.

A squad reviews MonkeyCode's current free-access notes, then pins this docket beside them.

Comments

[Francisco Grandón]

The ferry slip analogy is brilliant. The illusion of "cheap retries" in generative AI is one of the quietest engineering budget killers around—just because inference tokens are fractions of a cent doesn't mean developer review time and context drift are free.

Requiring a written docket or explicit stop-rule before triggering that second generation pass is essentially bringing back POSIX exit codes and deterministic circuit breakers. When an agent fails a check, having it immediately churn out alternative prose without recording what broke just creates agreeable noise that masks the underlying fault.

We've seen this exact pattern: teams end up running what is effectively an unhedged Markov chain where each unconstrained retry actually increases the odds of introducing subtle hallucinations. Tying the boat to the pier until the specific regression criteria is formally defined is the only way to keep automated workflows honest.

It’s almost comedic: sixty years after Edsger Dijkstra warned us about unstructured jumps, we replaced goto statements with probabilistic retry loops and acted surprised when the system landed in an infinite apology loop. Formal bounds win every time.

Really thoughtful and practical perspective!