Administrator
Published on 2026-11-13 / 10 Visits
0
0

Stale TODOs Are Hidden Agent Instructions: Add a Scope Gate

A TODO comment looks passive to a human. A coding agent reads it while planning, can retrieve the linked issue, and may turn it into work. The comment has crossed a boundary: from historical context into an instruction candidate.

Google's November 2026 Agent Distraction report makes that risk measurable. In millions of internal file-reading sessions, 13% exposed an agent to a TODO or FIXME carrying a bug reference. Agents acted on the referenced bug after 6% of encounters, and 83% of those actions were not requested by the developer.

The operational lesson is wider than clean up your TODOs. Repository text is part of the agent control plane. It needs freshness checks, explicit authority and a scope-expansion gate.

What Google's numbers establish

Google separated the observed funnel into distinct stages:

Stage Reported result What it means
Sessions exposed to a structured TODO/FIXME 13% The agent read a comment carrying a bug reference
Encounters followed by action on that bug 6% Subsequent behavior targeted the referenced bug ID
Follow-up actions not requested by the developer 83% The agent created a secondary task
Unprompted detours aimed at closed dead ends 41% 32% were fixed or verified and 9% were obsolete or won't-fix
Unprompted detours aimed at still-open issues 57% The work could be valid, but was outside the request
Unprompted detours aimed at duplicate or restricted issues 2% The reference could not be treated as ordinary current work

The report also associates unprompted detours with 70% more steps, 77% more tokens and 105% more wait time after controlling for developer, repository complexity, task type, model tier, files read, prompt length and encounter step. It reports developer-clustered standard errors and p values below 0.0001.

Those figures come from Google internal observational telemetry. The dataset, coefficient table, confidence intervals and an external replication are not public. They support a concrete risk and a useful measurement design. They do not establish universal rates for another repository or prove that deleting a TODO will produce the reported savings.

That evidence boundary matters because the easiest mistake is to turn one precise internal result into a generic ROI promise.

A TODO is a cached pointer, not current authority

Google's current C++ style guide defines TODOs as markers for temporary or short-term code. It asks authors to include a bug ID, owner or other identifier so later readers can retrieve context. It also says a TODO is not a commitment that the named person will fix the problem.

This creates two records:

  1. The inline comment is a cached pointer placed near the code.
  2. The issue tracker is the changing system of record for status, discussion and ownership.

Humans often reconcile the two silently. They notice that the comment looks old, remember the project history, or ignore an unrelated marker. An agent sees salient task language in the exact file it is already reading. If the harness gives every imperative-looking sentence equal authority, the stale pointer can outrank the current user request.

The fix is to treat repository context as typed input:

Context Default authority Required check
User request Current task Validate permissions and acceptance criteria
Repository instruction file Scoped standing rule Resolve path scope and version
Linked issue Candidate work state Read current status and access level
TODO or FIXME Historical hint Resolve the link and test task relevance
Comment without an owner or ID Unverified hint Preserve as unknown or send to review

Task relevance and issue status are independent. A closed issue can leave behind a useful design warning. An open issue can still be outside the user's request.

Build four gates instead of one cleanup script

Gate 1: Inventory structured work markers

Scan code, tests, configuration and active design documents for TODO, FIXME, HACK, XXX, deprecation notes and issue URLs. Record at least:

  • repository, path, line and current file hash;
  • marker type and normalized issue identifier;
  • comment age and last modifying commit;
  • owning component and code owners;
  • whether the reference is resolvable from the agent environment.

This is discovery, not a deletion list. A natural-language TODO with no identifier has weaker evidence than a marker linked to a live issue.

Gate 2: Join the marker to current state

Resolve structured references against the issue tracker and classify them:

  • open and related to current code;
  • open but unrelated to the requested task;
  • fixed, verified, obsolete or won't-fix;
  • duplicate or superseded;
  • restricted or unavailable;
  • unresolved because the identifier is malformed or the tracker is offline.

Keep the unresolved class. Converting access failure into closed would make the cleaner destructive exactly where its evidence is weakest.

Google says its own cleaner inspected the issue, file and code history before proposing a deletion. Over six months, it removed thousands of references that it could confirm were obsolete, with more than 95% acceptance from human reviewers. The acceptance result is evidence for a reviewed proposal workflow, not permission to delete every marker on a closed ticket.

Gate 3: Require an explicit scope-expansion event

When an agent wants to investigate or modify work not entailed by the user request, the harness should require a structured event before more tools are called:

{
  "event": "scope_expansion_request",
  "source": {
    "path": "src/cache/store.cc",
    "line": 184,
    "marker": "TODO",
    "issue_id": "bug/12345",
    "issue_state": "ASSIGNED"
  },
  "requested_task": "fix cache eviction race",
  "proposed_detour": "replace legacy serializer",
  "relationship": "adjacent_not_required",
  "action": "defer"
}

The verdict can be proceed, defer, record-only or need-more-evidence. Low-risk reading can receive a bounded allowance. Code changes, issue updates and other side effects should require a stronger relationship to the task.

This gate is more durable than adding ignore TODO to a prompt. It creates an observable decision that can be tested and audited.

Gate 4: Compare the final diff with the task contract

Pre-commit validation should answer three questions:

  1. Which requested acceptance criterion does each changed file support?
  2. Did the patch modify code associated only with a discovered TODO?
  3. Did tests, documentation or public behavior expand beyond the task boundary?

A useful invariant is simple: every changed component must map to the task, a required dependency, or an approved scope-expansion event. An unexplained change blocks commit and returns the agent to the task contract.

This connects context hygiene to a commit gate. The comment may influence reasoning, but the final side effect still needs a separately verifiable authorization path.

Measure the detour funnel with stable denominators

One agent-distraction rate hides different failure modes. Keep a funnel:

eligible file-reading sessions
  -> sessions exposed to a structured work marker
  -> markers followed by targeted retrieval or code search
  -> unprompted scope-expansion events
  -> out-of-scope edits attempted
  -> out-of-scope edits committed

Add a separate cleanup funnel:

markers scanned
  -> references resolved
  -> markers classified obsolete
  -> cleanup changes proposed
  -> cleanup changes accepted
  -> accepted changes later reverted

Do not divide accepted cleanups by exposed sessions or compare a repository-wide inventory with one model's task traces. The objects, time windows and denominators differ.

For evaluation, add boundary cases to the coding-agent suite:

  • a closed issue whose comment can be safely removed;
  • a closed issue whose comment still explains a compatibility constraint;
  • an open issue unrelated to the prompt;
  • an open issue required to complete the prompt;
  • a restricted issue the agent cannot resolve;
  • a TODO whose wording conflicts with a newer repository instruction;
  • a legitimate nearby defect that should be reported but not fixed.

The expected output is not always ignore. Reliable behavior means classifying the marker, preserving uncertainty and keeping the patch within authorized scope.

Cleanup and runtime control solve different problems

Repository cleanup reduces exposure. Runtime scope control limits damage when stale or merely adjacent work remains. Both are necessary because no repository stays perfectly fresh.

The maintenance loop is:

scan references
  -> join current issue state
  -> review evidence and history
  -> propose a narrow cleanup
  -> run tests and human review
  -> monitor reverts and new detours

The runtime loop is:

read marker
  -> classify authority
  -> test relevance to the task
  -> emit scope-expansion decision
  -> validate final diff

This complements eval-driven instruction deletion. Prompt cleanup removes obsolete control text from the system prompt. Repository hygiene removes obsolete control text from the environment. Both changes need regression tests because old text can still encode a real constraint.

The operating rule

Treat every TODO as a low-authority instruction candidate, not as inert prose and not as an automatic task.

Resolve its identity, read current state, check relevance to the user's request, and require an observable scope decision before it changes code. Then verify the final diff against the original task.

Agent-friendly repositories need clean code and clean authority. The second property is what stops yesterday's note from becoming today's unauthorized work.

References


Comment