Comment-discipline doesn't reach the agents that write comments

[williamthorsen]

Problem

comment-discipline is the largest live feedback cluster in the event store — roughly 38 events from 2026-06-10 to 2026-07-12, seven rated high or critical. The doctrine was last substantively revised on 2026-07-01 (#920) and events kept firing eleven days later, including two high-impact captures on 2026-07-12. This is recurrence after revision, not a backlog of pre-fix reports.

The store carries its own diagnosis, in three parts:

• The doctrine is never opened. Every consumer reaches it through a runtime Markdown link, which is an optional read; no orchestration agent reaches it at all. A 2026-06-19 run found orchestrated-coder, orchestrated-reviewer, and the aspect-* reviewers had no comment standard in context, and needed a /revise-comments pass that cut ~60% of comment volume. A doctrine the agent doesn't open cannot bind it, however well written. Same weakness as Inline output-shaping specs so skills cannot improvise them #971.
• Comment text drafted for another file isn't recognized as a source comment. A replacement comment proposed inside a review finding takes the same audit as one typed into the file, but the agent doesn't treat it as one — it restates the code and carries ephemeral example values lifted from the source (2026-06-29).
• The additive method has failed. History and motivation "keep leaking into code comments despite repeated guidance refinements" (2026-06-28). When a skill fails, the remedy is to cut and clarify — especially the concrete example — rather than add guardrails (2026-06-19).

The bucket choice that produced this is itself documented. _partials/README.md is the canonical reference for where shared Markdown lives, and it assigns "doctrine references" to _data/, reached by a runtime link. So the failure is not a one-off misplacement — the convention prescribes it, and the next apply-time doctrine will be mounted the same way.

Context

The doctrine lives in _data/comment-discipline.md, linked at runtime from code-patterns, respond-to-review, testing-conventions, and code-simplification-reviewer. Only revise-comments inlines anything: _partials/comment-audit-checklist.md, which restates the ten deletion rules as ten bullets.

Subagent skills: frontmatter injects a skill's content into the subagent's context. orchestrated-coder injects code-patterns and testing-conventions; all five reviewers inject review-criteria. Inlining the doctrine into those skills reaches every subagent without editing one.

Proposed solution

Scope by destination, not channel: the doctrine governs comment text destined for source, wherever the agent authors it — writing code, revising it, editing after a review, or proposing replacement text inside a review finding. Review comments themselves are conversation and take a thin bar in review-criteria instead; rules that route rationale to the PR channel cannot also ban it there.

Collapse the doctrine into a single inlined partial and delete both _data/comment-discipline.md and _partials/comment-audit-checklist.md. The ten deletion rules and the checklist that restates them consolidate into three tests — the stranger test, the deletion test, the one-location test — each carrying its tells and a worked before/after pair drawn from an observed failure.

Re-key the bucket criterion in _partials/README.md on when the agent needs the content rather than what kind of content it is. A doctrine the agent applies every time it performs an act binds only when it is already in context; one consulted when a decision arises stays in _data/. Without this, the fix stops at comment discipline and the convention keeps routing the next apply-time doctrine behind a link.

Acceptance criteria

Must have

• The doctrine governs comment text destined for source wherever it is authored, including text proposed inside a review finding.
• Every agent that writes or judges comments carries the doctrine in context at the point of writing; no runtime link to it survives anywhere.
• review-criteria states the bar for proposed comment text and for findings that recommend adding a comment.
• The doctrine states each rule once; no rule is restated in a second place.
• The rule count is reduced, and every surviving rule carries a tells line or a worked example.
• What the revision adds is scope and examples, not new rules.
• _partials/README.md selects the bucket by when the agent needs the content, and no longer routes doctrine to _data/ by kind. Its examples resolve to partials that exist.
• A regression test fails if a consumer stops carrying the doctrine, or if a subagent that writes or judges code stops injecting a skill that carries it.

Should have

• The two 2026-07-12 failures — a comment addressed to the reviewer, and counterfactual padding — are each represented by a worked example.

[williamthorsen]

Inlining is necessary but not sufficient

This ticket's thesis is that a doctrine reached by an optional link cannot bind, so it must be inlined into the context of every agent that writes a comment. The reach half of that holds: the orchestration agents genuinely had no comment standard in context, and they do now.

The binding half did not survive contact with the change itself.

While implementing this ticket, the agent wrote a four-line comment above an unrelated test fix that narrated the debugging session which produced it — the failing config key, the agent cache, the reasoning behind the chosen remedy. It also leaked change history into three comments in the new regression test. Every one of them fails the stranger test (would this interest only someone who watched the change happen?), which the same agent had authored, in this branch, hours earlier.

So the doctrine was inlined, in context, freshly composed, and self-authored — and it still did not fire at the moment of writing. The failure was not availability.

What the counterexample suggests. The gap is not what the tests say but when they fire. A doctrine in context is consulted when the agent thinks to consult it, and the moment immediately after it has finished arguing for something is precisely when it does not think to. Whatever the agent has just defended becomes what it writes into the comment.

That generalizes the trigger already on record. Event 01KXBBYDWBVAF9E7PEW5P7D2RK (2026-07-12) names post-review comment authoring as the high-risk moment. There was no review in this case — only a debugging session the agent had reasoned its way through out loud. The trigger is post-argument comment authoring of any kind: after a review, after a diagnosis, after a design discussion.

Captured as event 01KXE6HM0NNENJCPG8H1GFBV1P (high impact). A follow-up almost certainly has to work on firing conditions rather than on the text of the rules, and the acceptance criteria here — all met — do not measure that.