ORA-2026-0111: Comments at the constraint boundary

ORA-2026-0111: Comments at the constraint boundary

Rule

The default of "no comments" is correct. The exception is sharper than current practice suggests:

If you debugged it for >5 minutes, the next agent will too — leave the breadcrumb.

A comment is required at any boundary where the surrounding code surprised the author. Surprise is the load-bearing signal: stateless agents cannot ask the original author, cannot read PR descriptions reliably, cannot replay the conversation that produced the code. The comment IS the cross-agent knowledge transmission channel.

Three categorical positions

1. WHAT comments remain a smell. // increment counter over i++ is wrong in any context. Names carry contracts (ORA-2026-0044) does the WHAT work. Self-documenting code beats commented bad code.

2. Reference-rot comments remain banned. "added for issue #123," "used by FooHandler," "fix for the Y flow" — these die fast. They belong in commit messages, PR descriptions, or durable doctrine IDs. Inline references to ticket numbers (CMB-, HWD-, FLT-*) are also rot-prone because tickets supersede.

3. WHY comments at the constraint boundary are under-supplied at fleet scale and must be over-supplied to compensate. The cultural pressure of "default no comments" causes seats to omit comments that would have saved the next seat hours. The fleet-aware threshold is broader than the single-team threshold.

Constraint-boundary comments — required

Any of these is a constraint boundary:

• An external API or library that behaves differently than its name suggests (e.g., "alacritty 0.17 window.position.x is in backing pixels, not logical points")
• A platform/runtime quirk being worked around (e.g., "bash 3.2 strict-mode array landmines, dropping set -u")
• A non-obvious invariant the code relies on (e.g., "speaker_id must be human-locked before this runs; see span_attributions.attribution_lock")
• A deliberate non-DRY repetition because the cases will diverge (e.g., "kept separate from foo() because invoice path will need vendor-specific markup")
• A workaround for a specific upstream bug, with version (e.g., "until alacritty resolves issue #6203")
• A reference to durable doctrine (e.g., // per ORA-2026-0044 (names carry contracts))

Doctrine references are exempt from the rot critique because ORA entries are immutable once filed (they get superseded by new entries, not mutated). Inline ticket references (// for FLT-0702) remain rot-prone — tickets supersede, get cancelled, get renumbered.

Why

The reconstruction channels that make comments redundant in single-team human codebases mostly don't reach a fresh seat in a stateless multi-agent fleet:

• A new seat cannot ask the author — there is no author still in context
• git blame returns commit messages that are often terse and rot independently
• PR descriptions live on GitHub, not in the local checkout that the seat reads
• Slack threads, design docs, and tribal knowledge don't propagate through the boot sequence
• Tests document behavior but rarely document constraint-boundary reasoning

The comment IS the ambient knowledge transmission for stateless agents. Without it, the next seat re-derives the bug at full cost — sometimes mis-derives it and re-introduces the issue. The Randy Booth genealogy case is the canonical example: a fresh investigator looking at a span shown as "Unknown Project" reasonably concludes the pipeline has an architectural keyword-matching failure, when the actual cause is OpenAI 429 + no retry. A constraint-boundary comment in the ai-router code ("OpenAI quota errors here are not retried — see ORA-2026-0XXX") would have eliminated the wrong-path investigation.

How to apply

• After every meaningful piece of code you write, ask: "Did anything about writing this surprise me?" If yes, comment the surprise. If no, no comment.
• Use the 5-minute rule: if any constraint took you >5 minutes to discover, comment it.
• Format the comment to lead with the rule/constraint, then the why. One line if possible. Multi-line only when the why genuinely needs it.
• Reference durable doctrine (ORA-2026-XXXX) liberally; reference tickets sparingly and never as the sole source of truth.
• Header comments at the top of a script or module that document usage / contract / inputs and outputs are NOT subject to the no-comment default — they are the help text and the seat's first orientation. Keep them tight and accurate.

Anti-patterns this doctrine corrects

• Stripping a comment because "names should be self-documenting" when the comment was actually capturing a non-obvious constraint
• Writing comments that say WHAT the next line does (these violate ORA-2026-0044 by signaling the names don't carry their contracts)
• Ticket-number trails inline (// see CMB-1234) — replace with doctrine ID or remove
• Long preambles inside functions explaining design philosophy — move to header or design doc
• "TODO: revisit" without owner, date, or condition — either fix it now, file a ticket with a trigger, or remove

Boundary check at file commit time

Before committing code that touched a constraint boundary, ask: "Did the next agent inherit my discovery?" If the constraint is only in your head, the file is incomplete. Either the comment goes in, the doctrine is filed, or both.