werkrevisor/docs/prs/2026-10-10-PR#72-pr-doc-hints-as-line-comments.md

PR#72: Hints on PR Documents Are Line Comments Again

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.

Related Links

• PR#66: hints on documentation stay in the result comment.
• werkator PR#145: corrects the PR document of werkator PR#141.

The Problem

Since 0.31.0, a hint on a file of the category docs stands only in the result comment and holds no merge. In the 20 PRs since then, 6 findings stood only in the result comment:

PR	Finding	File	Rating
werkrevisor #68	a count in the Werkbaum is wrong	Werkbaum	real, reached main
werkator #141	"fails at once", but the test waits five seconds	PR document	real, reached main
werkrevisor #70 (2 findings)	Given/When/Then, implementation details	PR document	real, Jev's YELLOW had them too
werkator #132	a scenario narrates the mechanism	PR document	style
werkator #133	"as" reads awkwardly	PR document	style

Both real errors that reached main were statements about the PR, one of them in a PR document. The PR document is what the human reviewer reads first, and what a later reader takes as the record of the PR.

Non-Goals

• No change for hints on other documentation: README, guides and the Werkbaum keep the behaviour of PR#66.
• No change to hint_min or to the verdicts.

The Scenarios

Feature: a hint on a PR document gets an answer

Scenario#72.01: a hint on a PR document is a line comment

So that a wrong statement about the PR is answered before the merge.

• Given a GREEN review with automerge
• And its only finding is a hint on a file of [pr_doc] globs
• When werkrevisor publishes the review
• Then the hint is a line comment that holds the merge

Verified by

• test_doc_hints.DocHintsTest.test_a_hint_on_a_pr_document_is_a_line_comment

Scenario#72.02: a hint on other documentation stays in the result comment

So that the rounds saved by PR#66 stay saved.

• Given a GREEN review with automerge
• And its only finding is a hint on a README or guide, not on a PR document
• When werkrevisor publishes the review
• Then the hint stands only in the result comment
• And the merge is scheduled

Verified by

• test_doc_hints.DocHintsTest.test_a_hint_on_documentation_is_no_line_comment

The Solution

• A GREEN finding on a file of [pr_doc] globs is a line comment again; other documentation keeps PR#66.
• tools/review-rounds lists, per PR since a date, the review rounds, their verdicts, the line comments and the findings that stood only in the result comment; it gave the table above.
• Version 0.31.6.

Follow-up PRs

• Run tools/review-rounds again after the next 10 to 15 PRs and check the effect of 0.31.x and of this PR.