Agent narrates history in comments when responding to a review

[williamthorsen]

Agent narrates history in comments when responding to a review

Problem

When respond-to-review edits code to implement an accepted finding, the agent frequently writes comments that narrate the change — what the code looked like before, why it changed, the reviewer's concern, or the finding/acceptance-criterion ID that prompted it. Comments must stand on their own for a future reader who has no review context. This is the comment-discipline failure, surfacing specifically in review response.

Context

respond-to-review/SKILL.md makes code edits for every ACCEPTed finding but never references comment-discipline — no link, no audit checklist. The agent edits code while still in conversation with the reviewer, with no in-context reminder to switch voices. Code-writing surfaces like code-patterns already inline the comment-discipline rules; respond-to-review is the gap. The failure is recorded across several codeassembly KB events, which converge on one root cause: the rules must surface at write time, not as an after-the-fact audit.

Proposed solution

Surface comment-discipline at the point respond-to-review edits code, reusing the existing comment-audit-checklist partial (the mechanism code-patterns already uses), not a new rules doc.

• Add a ## Comment discipline section that frames the review-response failure (the reviewer-conversation voice must not leak into comments — no change-narration, no reviewer-concern retelling, no finding/AC IDs), includes the shared audit-checklist partial, carries a concrete review-response before/after example, and links to the full comment-discipline.md.
• Add pointers to the section from the evaluation step and the change-summary output, so the rule sits adjacent to where the agent edits code.

Acceptance criteria

Must have

• respond-to-review surfaces comment-discipline where it edits code for an accepted finding: a dedicated ## Comment discipline section, plus pointers from the evaluation step and the change-summary output.
• The section reuses the shared comment-audit-checklist partial and links to comment-discipline.md — it does not restate the rule set — and carries a concrete review-response before/after example.
• The guidance explicitly names the review-response failure modes: narrating the change, retelling the reviewer's concern, and citing finding or acceptance-criterion IDs in comments.

Should have

• The partial include resolves through the install pipeline and existing content checks pass (no path-allowlist regression).