werkrevisor/docs/prs/2026-10-20-PR#125-diagrams-on.md

PR#125: Diagrams for werkrevisor, Drawn by Sonnet for PRs That a Human Reviews

Version: minor

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#121: diagrams of PR Lens in the result comment, default off.

Problem

Since PR#121 werkrevisor can attach diagrams of PR Lens, but no repository uses them yet. Without a model, they take the review model; for werkrevisor that is MiniMax M3, whose graph documents do not validate, not even after the repair round of PR Lens.

A GREEN PR merges without a human, so its diagrams cost money that nobody looks at.

Non-Goals

• No diagrams for hs-review.
• No diagram cost in the usage record yet.

Specification

Feature: only a PR that a human reviews gets diagrams

Scenario#125.01: a GREEN PR gets no diagrams

… so that no money goes into diagrams that nobody looks at.

• Given a host config with [diagrams] enabled = true and the default skip_green = true
• When werkrevisor publishes a GREEN result
• Then it calls no PR Lens and attaches nothing

Verified by

• test_prlens.DiagramsInTheResultCommentTest.test_a_green_pr_gets_no_diagrams

Scenario#125.02: a PR that a human reviews gets diagrams

… so that the human reviewer sees what the PR touches.

• Given a host config with [diagrams] enabled = true and skip_green = true
• When werkrevisor publishes a YELLOW, ORANGE or RED result
• Then the result comment links the diagrams, unless the diff holds a possible secret (Scenario#121.07)

Verified by

• test_prlens.DiagramsInTheResultCommentTest.test_a_pr_that_a_human_reviews_gets_diagrams

Solution

• [diagrams] skip_green, default true: a GREEN result draws nothing.
• config/werkrevisor.toml switches the diagrams on, with model = "anthropic/claude-sonnet-5.5" and timeout_seconds = 120: with 2 review calls of up to 300 s, the default of 300 s could exceed the 15 minutes of the Werkator build.

The choice of the model, measured on 2026-10-20 on the merged werkrevisor PR#117, PR#118, PR#122 and PR#123:

Model	Valid	Time	Cost per head	Content
MiniMax M3, the review model	0 of 1	–	–	the graph document misses title, lanes and nodes, also after the repair round
GPT-6 Luna	4 of 4	42–75 s	about 0.01–0.02 USD	system context and rough boxes, e.g. "Codex Runner → bwrap sandbox → Codex CLI"
Sonnet 5.5	4 of 4	18–43 s	about 0.10–0.20 USD	changed functions with their files, NEW and REMOVED nodes, e.g. the dropped economy-model summary of PR#117

werkrevisor PRs often have 5 to 8 heads; with skip_green, only the heads that a human reviews cost.

Additional Changes

• werkrevisor/pr_lens.mjs ends a failure with one line: the code and message of PR Lens and its first details. Before, the log of werkrevisor showed only the last line of the stack trace, Node.js v20.19.2.
• docs/werkrevisor.werkbaum: #diagrams.on is [^].

Deployment: config/werkrevisor.toml reaches mih09 with the release, if PR#124 is merged by then; otherwise tools/sync-host-config --apply mih09-werkator@mih09.hostsharing.net werkrevisor after the release, since 0.52.0 does not know skip_green.

Follow-up PRs

• hs-review puts the SVGs next to its draft for dev.hostsharing.net.
• The cost of the diagrams in the usage record and in the budget of a review.