When Agent Cleanups Erase the Why: A Comment Handoff You Can Paste Into the Wiki

You open a morning pull request and notice that the diff looks almost polite at first glance. An agent shortened three helpers, dropped unused blanks, and deleted the comment above the vendor retry guard. That comment had said the first timeout is a warm-up miss, and the retry budget must ignore it. Shared tests are green, so you need a handoff that names who restores that why before the cleanup is treated as done.

The review gap this card closes

A shorter function is not a clearer change when the reason for a guard disappears with the comment. Teams already argue about clean code and clear code, and agent cleanups make that argument land inside the diff. This playbook gives you roles, a handoff order, and a one-page wiki run you can paste before the next cleanup. It does not replace code review, and it does not pretend that every removed comment was either waste or wisdom.

Four roles on one handoff line

You assign four names before the cleanup branch opens, even when two names belong to the same small team. The diff author, whether human or agent-assisted, attaches an inventory of removed comments before requesting a decision. The rationale keeper decides whether each removed comment stays, moves, or dies, and they must not be the only author of the diff.

The scratch runner executes a narrow check on a disposable environment and records the exact command beside the result. The wiki clerk publishes the signed card after the keeper decides, and that clerk does not approve the code change. You write those names on the card even if the agent cannot hold a role, because accountability stays with people.

Handoff timing you do not skip

The diff author hands the completed inventory to the rationale keeper before anyone rewrites a surviving comment in the branch. The keeper hands a signed disposition back to the scratch runner only for rows marked as behavior risk. The scratch runner hands the command log to the wiki clerk, and the clerk publishes before the approver is pinged. You do not skip ahead to merge when one of those handoffs is still verbal, because verbal notes vanish after the pull request scrolls.

Paste this one-page run into the wiki

You copy the card into the team wiki under a stable title so reviewers are not hunting through chat for the latest rule. You keep one card per pull request, because a living mega-page hides which commit the disposition actually covered. You redact hostnames and customer identifiers before the card is saved, even when the comment was already public inside the repo. You link the card from the pull request body so the next reader can find the why without asking who remembers it.

# Comment handoff card
- Date:
- Repo:
- Base commit:
- Head commit:
- Diff author:
- Rationale keeper:
- Scratch runner:
- Wiki clerk:
- Inventory command:
- Scratch command and exit code:
- Secrets checked (yes/no):

## Hits
| File | Removed line (redacted) | Disposition (keep/move/delete/stop) | Evidence |
| --- | --- | --- | --- |
| | | | |

## Keeper note
- Unverified model guess used (yes/no):
- Disagreement with ticket (yes/no):
- Merge allowed (yes/no):

Steps you follow on the cleanup branch

1. Freeze the comparison range

You start from a named base branch so the inventory does not mix yesterday's cleanup with unrelated local edits. You record the base commit and the head commit on the card before anyone amends the branch again. You refuse a review that only shows a screenshot of the editor, because the wiki needs a command someone else can rerun. If the branch was rebased, you regenerate the inventory instead of trusting the previous list of deleted lines.

2. Build the comment inventory

You pipe the unified diff into a small scanner that prints removed lines which look like comments. You treat that output as a lead list, not as proof, because block comments and generated files confuse simple markers. You open each hit in the file and note whether the surrounding code still states the same constraint in names or tests. You drop license headers and obvious section banners from the decision list so the keeper is not buried in noise.

3. Classify before you rewrite

You use the decision table below so two reviewers do not invent private rules during the same pull request. You restore a comment when it names a vendor limit, a race, a migration, or a deliberate non-action. You move a long explanation to the wiki when the code stays, and you add a pointer only if the team already uses pointers. You allow a deletion when the comment only restates the function name and the tests already document the behavior.

4. Separate style cleanup from behavior risk

You do not rerun the whole suite for a comment-only deletion if the diff contains no code line changes. You do ask the scratch runner for a narrow check when a comment and a condition were edited in the same hunk. You keep that check off the shared release lane so a rehearsal failure does not block unrelated ship work. You paste the command, the exit code, and the commit under test into the card before the keeper signs.

5. Sign, publish, and stop

You stop the merge if the inventory still has an unclassified removed comment, even when the tests are green. You stop again if the model draft and the ticket disagree, because a fluent summary is not a source of record. The wiki clerk publishes the card in the agreed folder and links it from the pull request before approval. You merge only after the keeper name, the date, and the disposition of each hit are visible to the next reader.

Commands you keep beside the card

# Unexecuted examples. Replace branch names and test paths before you trust them.
git fetch origin
git merge-base origin/main HEAD
git rev-parse HEAD
git log --oneline origin/main..HEAD

git diff --unified=3 origin/main...HEAD -- '*.py' '*.ts' '*.go' ':!vendor' ':!dist' \
  | python3 scripts/comment_handoff.py > /tmp/comment-inventory.txt

# Stop before any model call if a common secret marker appears.
git diff origin/main...HEAD | grep -E 'AKIA|BEGIN PRIVATE KEY|api_key' \
  && echo 'stop: possible secret' || echo 'no common secret marker'

# Narrow scratch check. Do not point this at production.
python3 -m pytest tests/test_vendor_timeout.py -q --tb=line
echo "exit=$?"

You save the three-dot diff command on the card so a teammate can rebuild the inventory without guessing your local branch state. You run the secret-marker grep before any model call, and you stop the whole handoff if that grep prints a hit. You treat the pytest line as a template, and you replace the path with the narrow test that covers the restored comment. You label every command unexecuted until someone on your team has run it against a real branch and kept the output.

An unexecuted scanner you can adapt

#!/usr/bin/env python3
# Unexecuted example: list removed comment-like lines in a unified diff.
# This script does not decide safety. Adapt markers and exclude paths first.

import sys

MARKERS = ('#', '//', '/*', '*', '--')


def removed_comments(diff_text: str):
    hits = []
    current = 'unknown'
    for raw in diff_text.splitlines():
        if raw.startswith('diff --git '):
            parts = raw.split()
            current = parts[-1] if parts else 'unknown'
            continue
        if not raw.startswith('-') or raw.startswith('---'):
            continue
        body = raw[1:].strip()
        if body.startswith(MARKERS):
            hits.append((current, body[:160]))
    return hits


def main() -> int:
    rows = removed_comments(sys.stdin.read())
    if not rows:
        print('no removed comment-like lines detected')
        return 0
    for path, body in rows:
        print(f'{path}\t{body}')
    return 2


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

You run this only as a lead list, and you expect false hits from SQL dashes, markdown bullets, and license banners. You exclude vendored paths in the git command so the keeper reads your code rather than a dependency changelog. You treat exit code 2 as a human must classify, not as a product failure and not as an automatic revert. You change the marker tuple before you trust it on a repo whose comments do not look like these prefixes.

Decision table for the keeper

You read each row as a default, then you write an exception on the card when the code proves the default wrong. You do not let a model pick the disposition, because the keeper signature is the point of the handoff. You prefer stop over a guessed delete when the evidence column would otherwise be empty. You can add a row for your own domain, such as feature flags, without changing the four role names.

What you see in the removed line	Default disposition	Scratch check	Wiki evidence
Restates the function or variable name	Delete	None if no code changed	style-only
Names a timeout, retry, race, migration, or vendor quirk	Restore or move, with a pointer only if your team already uses pointers	Narrow test for that behavior	Ticket or incident id
Conflicts with the current code or test	Stop	Reproduce the disagreement	Quote the conflicting lines, redacted
Holds a secret, token, customer id, or private hostname	Remove from code, do not paste the secret, rotate if it was real	Do not send the line to a model	redacted only

Where a disposable model pass fits

You can rehearse the unverified guess and the narrow check when free model access and a free server option are available to the team.

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

MonkeyCode is the offering this walkthrough uses for those two options, and you confirm current docs before you rely on either one. If you need a low-friction place to practice, those free options can host a rehearsal, without any claim about quotas, hardware, or duration. You keep secrets and production logs out of the prompt and off the disposable server, then you copy results back to the card.

Limitations and who should skip this

This scanner only sees removed lines that begin with common comment markers, so it misses many block-comment edits. A model can invent a confident reason for a comment that was actually stale, sarcastic, or copied from another file. You should not use this playbook as incident command, as a solo approval path, or as a regulated audit system. You skip it when comments currently store credentials, because the first job is removal and rotation, not a wiki essay.

You also skip it when nobody will sign as rationale keeper, since an unsigned card is only theater. Free access is not a capacity plan, and you should not promise teammates a quota or uptime from this article. Generated files, lockfiles, and vendored trees will flood the inventory unless you exclude those paths in the command. You revisit the card when review tools change, or the handoff ages into the stale note you meant to protect.

What you do before the next cleanup

You paste the card, fill the four names, and run the inventory on the next cleanup before style talk starts. You record an empty inventory too, so the next reviewer can see that someone actually looked. You link the card from the pull request, and you treat a missing link as a reason to pause. The useful outcome is a diff whose why survives the cleanup, not a shorter file that nobody can explain.