# 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](../../tests/test_changed_lines.py)
- [test_changed_lines.ChangedLinesTest.test_writing_rule_on_old_text](../../tests/test_changed_lines.py)

#### 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](../../tests/test_changed_lines.py)
- [test_changed_lines.ChangedLinesTest.test_first_round](../../tests/test_changed_lines.py)
- [test_changed_lines.ChangedLinesTest.test_unreadable_earlier_file](../../tests/test_changed_lines.py)
- [test_changed_lines.ChangedLinesTest.test_doc_hint_line_comments_keeps_the_hint](../../tests/test_changed_lines.py)
- [test_changed_lines.ChangedLinesTest.test_a_finding_on_a_heading_covers_its_section](../../tests/test_changed_lines.py)
- [test_changed_lines.ChangedLinesTest.test_a_paragraph_rule_covers_its_paragraph](../../tests/test_changed_lines.py)

## 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.