werkrevisor/docs/prs/2026-10-08-PR#50-doc-check-answered-hints.md

PR#50: a resolved hint of the PR document check does not come back for an unchanged section

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.

The Problem

Since PR#47, Jev compares each section of the PR document with a change summary, and a possible contradiction becomes a hint as a line comment, which holds the merge until it is resolved. Each new commit gets a new review, and a resolved line comment is not reused, so the same hint on the same unchanged section comes back. In PR#49, the author had to answer the same false hint on the Non-Goals three times.

Non-Goals

• No change for an ORANGE contradiction: it needs a new commit or a human, as before.
• No change for the hints of the model review.

The Scenarios

Feature: a resolved hint of the PR document check stays answered

Background

• Given a [doc_check] section
  • and an earlier review wrote a hint of the PR document check on a section of the PR document
  • and the author resolved this line comment

Scenario#50.01: a resolved hint is not repeated while its section is unchanged

So that the author answers a false hint once, not after every commit.

• When a new commit leaves the section unchanged, and Jev flags it again
• Then werkrevisor writes no new line comment for this section
  • and a hint in the result comment counts the hints that were not repeated

Verified by

• test_doccheck: test_a_resolved_hint_is_not_repeated_while_its_section_is_unchanged

Scenario#50.02: a changed section is checked again

So that a new contradiction in an edited section is not hidden by an earlier answer.

• When a new commit changes the text of the section, and Jev flags it again
• Then werkrevisor writes a new line comment for this section

Verified by

• test_doccheck: test_a_changed_section_is_checked_again

Scenario#50.03: an ORANGE contradiction comes back

So that a contradicting test claim still needs a new commit or a human, as before.

• Given the resolved line comment was ORANGE, e.g. a contradicting test claim
• When a new commit leaves the section unchanged, and Jev flags it again as ORANGE
• Then the review is ORANGE again
  • and werkrevisor writes a new line comment for this section

Verified by

• test_doccheck: test_an_orange_contradiction_comes_back

The Solution

• Each line comment of the PR document check names a fingerprint of its section: a hash of its kind, title, text and Gherkin steps.
• Before it writes a hint, werkrevisor looks for a resolved line comment of the bot with the same fingerprint; if it finds one, it skips the hint.
• The README section [doc_check] says so.
• werkrevisor 0.23.1.

Prerequisite PRs

• PR#49: the README explains why output limit and timeout depend on the model, merged.