Add comment discipline to agent guidance and review pipeline

[williamthorsen]

Problem

When an agent writes code in an interactive session, it routinely produces comments that memorialize the conversation that led to the code rather than communicating what a future reader needs to know. The pattern shows up in two related forms:

• Content failure. Comments reference chat-time reasoning ("we discussed," "this test locks the affordance in"), the originating ticket or PR, sibling files recoverable by grep, or restate what the surrounding code already says.
• Volume failure. Large file headers duplicate per-function JSDoc, inline comments paraphrase the next line, defensive prose covers unreachable cases, the library being used is re-taught, the same fact is documented in multiple places, and domain leaks appear in shared code.

orchestrated-coder does not exhibit the pattern at the same rate because it works from a written plan and carries no conversation context to leak. Interactive coding fails on both axes: it carries conversational pressure to "show its work," and it does not load the relevant guidance skills (code-patterns, testing-conventions) automatically.

Across one observed three-file commit, comments accounted for roughly 120 of 750 lines; a reasonable trimmed target was 40 lines, a 65% reduction without losing any signal. A separate observed case was a four-line test comment containing a ticket reference, a PR reference, a "this test locks the affordance in" sentence, and an over-scoped eslint-disable rationale, where the human-written replacement was a single sentence explaining the actual non-obvious fact (the styled behavior was not observable in jsdom).

The closest existing guidance is a single bullet in code-simplification-reviewer.md ("Redundant comments that describe obvious code") and the code-patterns/SKILL.md "Documentation" section, which addresses form (JSDoc params, section separators) rather than content economy. Neither captures the full failure mode, and neither is loaded at the point of authorship in interactive sessions.

Context

This ticket folds in #656 (originally "Comment-verbosity guidance for interactive main-agent coding sessions"), which characterized the same problem from a different angle. Both tickets share the same root cause (conversational context leaking into source comments) and the same proposed mechanism (a pre-completion audit). #656 contributed the broader rule taxonomy and the orchestrated-vs-interactive diagnostic; #642 contributed the test-comment and eslint-disable carve-outs. The combined rule set is more comprehensive than either alone.

Constraints that shaped the design:

• Agent-agnostic. The solution must work on Rovo Dev and other platforms in addition to Claude Code. This rules out platform-specific hooks (PreToolUse settings.json hooks) as the primary mechanism.
• No new interactive-session burden. Comment guidance does not load at session start. There are no additions to AGENTS.md or collaboration/SKILL.md.
• Trigger at writing time, not session start. For the orchestrated path, this is achievable because orchestrated-coder loads code-patterns and testing-conventions declaratively at subagent start. For the interactive path, no equivalent trigger exists in an agent-agnostic content-only world; the design accepts this gap and relies on reviewer-side enforcement to catch what slips through.
• Reviewer-side enforcement. code-simplification-reviewer already has scope coverage for comments but only one bullet of guidance. The change expands it so /review-branch catches the pattern at the rate the user currently catches it by hand.

Proposed solution

Codify a single canonical statement of comment discipline that fires at writing time for orchestrated coding and at review time for all changes. The rule has three parts:

• A positive baseline that every non-trivial function, method, class, and component carries a one-line description.
• Ten deletion rules drawn from the union of Add comment discipline to agent guidance and review pipeline #642 and Comment-verbosity guidance for interactive main-agent coding sessions #656, covering: paraphrasing the next line, conversation references, ephemeral artifact references, library re-teaching, unreachable-case defenses, duplicated facts, tutorial file headers, process commentary, domain leaks in shared code, and "what" inline comments.
• Two positive carve-outs: test comments (non-obvious setup, indirect assertions, intentional skips) and eslint-disable rationales (only the specific suppression).

An audit checklist factors out the per-comment deletion test ("would a competent reviewer lose anything if I deleted this?") so it can be transcluded into multiple consumer skills without drift.

Consumer surfaces:

• The skills code-patterns and testing-conventions carry the rule for the orchestrated-coder path. Both are declared in orchestrated-coder.md's frontmatter and load when orchestrated coding starts.
• code-simplification-reviewer.md expands its existing single-bullet comment scope into the full taxonomy, so /review-branch catches violations during review.

Surfaces deliberately not touched:

• AGENTS.md: no session-start burden on interactive coding.
• collaboration/SKILL.md: no interactive-session checkpoint.
• A dedicated comment-revision subagent is acknowledged as a possible fallback if reviewer-side enforcement proves insufficient in practice. It is deferred as a follow-up.

Acceptance criteria

• A canonical reference doc exists for comment discipline, covering the positive baseline, the ten deletion rules, the two carve-outs (test comments, eslint-disable rationales), and a before/after example drawn from observed cases.
• An audit checklist partial exists and is transcluded into the consumer skills.
• code-patterns/SKILL.md carries a "Code comments" section that points to the reference doc and transcludes the audit checklist.
• testing-conventions/SKILL.md carries a section listing the test-comment carve-outs and pointing to the reference doc.
• code-simplification-reviewer.md is updated so its scope lists the comment-discipline patterns it must flag, with a pointer to the reference doc and a calibrated severity example.
• /review-branch finds and reports comment-discipline violations during code review on a representative change.
• No additions to AGENTS.md or collaboration/SKILL.md.
• Issue Comment-verbosity guidance for interactive main-agent coding sessions #656 is closed as superseded, with the closure referencing this ticket.