werkrevisor/docs/prs/2026-10-08-PR#59-review-decisions-diagram.md

PR#59: a diagram shows where a review ends early or takes a shortcut

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

The diagram of PR#58 shows the inside of a review as ten steps, each with a condition. It hides that a review branches: some checks end it early, e.g. a head that moved, or take a shortcut, e.g. RED for an open question without a model call.

Non-Goals

• No change of the content or the layout of the other diagrams; only their colors change, for the contrast.
• No change of the code of werkrevisor or the configs.

The Solution

• docs/werkrevisor-review-decisions.svg and its dark variant: the checks of one review in three rows, before the model, around the model and after it; each check has its exit and the result of the exit.
• tools/diagrams: the generators of this diagram and of the inside diagram of PR#58, with a short guide; tests/test_diagrams.py checks that the SVGs in docs/ are the output of their generators and well-formed.
• All three diagrams: white text only on fills with a contrast of at least 4.5:1; yellow and orange keep their bright fill and get dark text.
• README: the diagram below the inside diagram.
• AGENTS.md: a PR that changes the steps or decisions of a review updates the diagrams.
• docs/werkrevisor.werkbaum: the node of the diagrams names this PR.

Prerequisite PRs

• PR#58: two diagrams, merged.