werkrevisor/docs/prs/2026-10-12-PR#91-hints-on-changed-lines.md

PR#91: From the Second Round On, a Hint on Unchanged Text Holds No Merge

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

Problem

tools/review-rounds https://git.javagil.de mi 2026-10-09T20:00 werkrevisor werkator werkcrappit werkprobe werkregie counted 89 PRs on 2026-10-12: 47 needed one review round, 23 two, 10 three or four, 9 five or more; the mean is 2.0. The 42 PRs with more than one round got 111 line comments of ai-reviewer, read from their reviews in Gitea: 51 on documents, 43 on code, 13 for writing rules and 4 by Codex. In 24 of the 35 such PRs with line comments, the documents and writing rules outnumber the code.

Each fix of a document starts a new round, and the model then finds a new small point in text that the earlier rounds had already seen, e.g. werkrevisor PR#90 with five GREEN rounds.

Non-Goals

• No change for findings on code, and none for ORANGE or RED findings on documents.
• Open line comments of earlier rounds stay open until they are answered.

Specification

Feature: from the second round on, a hint on unchanged text holds no merge

Scenario#91.01: a new hint on text of the last round stands only in the result comment

So that a fix of one point does not start a round for the next point in text that the last round had seen.

• Given a PR after its first review round, and a document line that the new head did not change
• When werkrevisor reports a GREEN hint or a writing rule on that line
• Then the hint or the writing rule stands only in the result comment, and the merge is scheduled

Verified by

• test_changed_lines.ChangedLinesTest.test_new_hint_on_old_text
• test_changed_lines.ChangedLinesTest.test_writing_rule_on_old_text

Scenario#91.02: a hint on a changed line still holds the merge

So that new text gets the same review as before.

• Given a GREEN hint on a document line that changed since the last reviewed head, or a first round
• When werkrevisor reviews the head
• Then the hint is a line comment that holds the merge

Verified by

• test_changed_lines.ChangedLinesTest.test_hint_on_changed_line
• test_changed_lines.ChangedLinesTest.test_first_round
• test_changed_lines.ChangedLinesTest.test_unreadable_earlier_file
• test_changed_lines.ChangedLinesTest.test_doc_hint_line_comments_keeps_the_hint
• test_changed_lines.ChangedLinesTest.test_a_finding_on_a_heading_covers_its_section
• test_changed_lines.ChangedLinesTest.test_a_paragraph_rule_covers_its_paragraph

Solution

• The last reviewed head is the head of the newest result comment of the bot for another commit.
• Lines are unchanged if difflib finds them in the file of that head; a file that cannot be read counts as changed.
• A finding on a Markdown heading, e.g. of the PR document check, covers its whole section, and a paragraph rule covers its whole paragraph, so a change below the anchor line still counts.
• Documents are the category docs and [pr_doc] globs; findings on code and ORANGE or RED findings are not affected.
• Open line comments of earlier rounds still hold the merge until they are resolved.
• [review] doc_hint_line_comments = true keeps every hint of the model a line comment, also on unchanged text.
• README: a paragraph in "PR workflow and automerge"; the PR workflow diagram says "old text gets no new hint".
• Werkbaum: #model.rounds.check with the counts, #model.rounds.changed.
• Version 0.36.0.

Open Questions

None.