Handoff Protocol

Handoff Protocol

When to use this

Any time work splits into three roles: the decision-maker (sets direction, makes the call), the reviewer (audits, accepts), and the implementer (does the work). They may be three people, or a person plus a reviewer plus an automated agent. This skill covers the format and discipline of the handoffs between them, so collaboration does not run on guesswork, does not burn communication cost, and does not produce silent errors.

General rules

Rule 1: Report results as a one-line conclusion, never a dump of raw output

The reviewer wants the conclusion, not everything on your screen. When something finishes, report one line: what you did, green or red, and the key numbers.

• ✓ "Full test run: 1372 passed / 0 fail (baseline 1341 + 31 new tests)"
• ✗ Pasting hundreds of lines of test output and letting them find it. Raw output stays in a file or a log, and you point at it when asked. Communication space is finite; do not use it to haul noise.

Rule 2: Progress updates conserve space

When reporting progress mid-way through a long task, one line as well: where you are, whether anything is wrong. Do not paste full detail at every step — conversational and context space is a scarce resource, and filling it up makes the important parts harder to see, not easier.

Rule 3: Do not run silently for long stretches (estimate first, report on a rhythm, stop when overrun)

• Estimate before you start: roughly how long will this take?
• Report on a rhythm: on a long task, every couple of minutes (2–3), say "still running, here is where I am." Do not vanish.
• Stop when clearly overrun: when the actual time clearly exceeds the estimate (by 1.5×, say), stop and diagnose; do not wait indefinitely — it is usually stuck, not slow.
• Do not retry things already known to be innocent: re-running things already verified green burns time; investigate what is actually suspect.

Rule 4: Tell a phantom stall from a real failure; never "fix" a phantom stall as if it were a bug

When a long task stalls or errors, ask first: is my artifact wrong (a real failure), or is this environmental noise (a phantom stall)?

• Typical sources of a phantom stall: a leftover old process competing for resources or file locks, state from the previous round that was not cleaned up, a temporarily flaky external dependency, multiple instances of the same named resource fighting each other.
• Handling: first isolate (remove the interference precisely — end the process by PID, do not kill innocents; end precisely the program that is interfering, never everything) → re-run clean → if the re-run is green it was a phantom stall, not a bug, and you do not touch the artifact; if it reproduces consistently it is a real failure and only then do you start debugging.
• The iron rule: never treat a phantom stall as a bug to fix — "changing things on a hunch" will turn a good artifact into a broken one. Reproduce first, characterize second, act third.

Rule 5: What you hand the reviewer must be directly auditable

The reviewer must be able to re-check it at a glance, without rebuilding your context:

• The conclusion (green/red) + the evidence (key numbers / reconciliation) + the boundaries (what was verified, what was not — labeled honestly).
• If the reviewer will paste it upward, give them a copy-ready finished paragraph (heading + conclusion + evidence + boundaries) rather than making them assemble it.
• Reconcile precisely: "original N + M new = N+M" — the numbers add up, and that is what makes the gate trustworthy.

Rule 6: The implementer does not edit documents owned by the decision-maker or the reviewer

Role boundaries are a safety mechanism, not a formality:

• The implementer does not modify documents the decision-maker owns (specs, requirements, records of rulings). To add content → cite them from your own design or plan document, or propose the change and let the decision-maker make it. If you find such a document has been modified by someone else (there are changes in the working tree) → do not touch it, do not commit it; just report it.
• Likewise, the acceptance criteria are the reviewer's to set, and the implementer does not loosen them unilaterally.
• The cost of crossing the line: the decision-maker loses control of the source of truth, and everyone downstream is wrong along with it.

Rule 7: Report honestly; do not dress up bad news

If the tests went red, say red and paste the output; if something was skipped, say it was skipped; if it is done and verified, say so plainly with no unnecessary hedging. Gating only works if the reports are trustworthy — gloss over it once and you have put every future report back under suspicion, and the cost of collaborating explodes.

Case files from this project (supporting evidence, not required for the general rules)

• One-line self-check + reconciliation (Rules 1/5): in one financial-reporting automation project, every task closed with "pytest X passed / 0 fail," and every merge gate reported "baseline 1341 + 31 new tests = 1372" — the reviewer re-checked from that line plus the reconciliation numbers, never from raw output.
• A phantom stall in practice (Rule 4): one full test run "stalled" — an old test process left over mid-way (genuinely running a full sweep) was fighting the official run for Windows file locks, which produced the phantom stall. Handling: kill the leftover process precisely by PID + re-run in isolation to take a clean green, ruling it "a phantom stall, not a real fail," and no artifact was modified. A separate misdiagnosis of webapp "flakiness" taught the same lesson — "never fix flakiness on a hunch" — and only the real root cause (an atomic-file-write race) was fixed.
• Not editing the decision-maker's documents (Rule 6): the main spec file is maintained in the decision-maker's working tree; the implementation found it had been modified → did not touch it, did not commit it, and cited it only from independent spec/plan documents. This echoes the sister skill spec-citation's "read-only when you do not own it."
• No silent running (Rule 3): the project has an explicit "no silent running" working rule — estimate long commands first, report every 2–3 minutes, stop on overrun, and do not re-run things already verified innocent.
• Two-way reconciliation (Rules 4/5/7, a complete live case): on the same matter, both directions were stopped by checking against the truth:
  • On the implementer's side (a self-report caught): a deliverable that had only been described verbally and never actually submitted for review was marked "already reviewed." The reviewer's one-line reconciliation caught it on the spot ("content instructed ≠ artifact reviewed"; four had been reviewed, five were claimed). The lesson: "done" recognizes only what passed the acceptance gate, not what you believe should have passed (echoing verification-discipline's "never trust a self-report").
  • On the reviewer's side (an opinion blocked by checking): the reviewer, working from a rendered copy of a post, issued the instruction "delete the duplicated paragraph and complete the truncated sentence"; the implementer checked against the real file — that paragraph was neither duplicated nor truncated, it was a rendering artifact of the copy → did not comply blindly, did not delete a duplication that did not exist, and reported back asking them to re-check against the real file (echoing the spirit of Rule 4's "artifact vs. real problem": verify before acting).
  • The combined iron rule: the implementer does not mislabel something "reviewed," and the reviewer checks an opinion against the real artifact before it is executed — neither side runs on impressions or copies; both run on reconciliation against the truth. Both corrected honestly, with no digging in.
• Disclosing your own false green unprompted (Rule 7, a positive example): while re-measuring against real files, the implementer discovered that an equivalence test they had submitted earlier had gone green only because "two writes happened to land in the same timestamp bucket" — and said so before the reviewer could catch it: "that earlier test was just a same-second fluke," attaching a part-by-part comparison proving the content was in fact identical and the difference was purely the timestamp, together with the fix (fixed timestamps), all in one submission. The reviewer therefore only had to re-check rather than investigate — one voluntary disclosure buys the no-verification-needed cost of every report afterwards.