Why annotate analyser findings on the change under review instead of only failing the build?

### Two different jobs: deciding and explaining A pipeline that runs analysis has to do two things, and they are frequently confused. It has to **decide** — this change may or may not merge — and it has to **explain** — here is what is wrong, where, and what to do. A pass/fail status does the first job well and the second job not at all. An annotation attached to the changed lines does the second job well and should not be trusted with the first. Keep them separate. One status, owned by the gate, answers "can this merge". Annotations are presentation: they put the finding in front of the author at the moment and place where the decision to change the code is being made. ### Why the log is not good enough When the only artefact is a red build with a link, the author pays a context switch to open the log, another to find the analysis step among the others, another to map a file path and line number back to the change they are looking at, and often a fourth to work out which rule fired and whether it is worth arguing with. Each of those is small; together they are the difference between fixing the finding now and adding it to a mental list. On a change that produced a handful of easy findings, the surfacing cost can exceed the fixing cost. An annotation on the changed line collapses that to zero: file, line, rule identifier, one-sentence explanation, and where possible the suggested fix, rendered next to the code. ### What a good annotation contains - **The rule identifier**, so the author can look up its rationale, and — if they disagree — write a correctly targeted, justified suppression instead of a broad one. - **A statement of what is wrong in this specific code**, not the rule's generic description. "This comparison of monetary amounts uses floating-point equality" beats "avoid float equality". - **What to do**, and the fix itself where the analyser can produce one. - **Severity, disambiguated.** An analyser's own severity level for a rule is not the same thing as the business urgency of the finding, and a reviewer reading the annotation should be told which is meant. ### The failure mode: volume Annotation quality collapses with quantity. A change that arrives with 143 annotations is a change whose annotations will all be collapsed unread, and the useful one among them is lost. Three defences: 1. **Attribute to the change.** Annotate findings the change introduced, not every pre-existing finding in the files it happens to touch. Otherwise a one-line edit to an old file buries the author in inherited debt they did not create and cannot triage. 2. **Cap and summarise.** Post the first N inline and a single summary carrying the counts by rule, with a link to the rest. The summary also gives you somewhere to say "and 118 more of the same rule", which is itself the most useful signal on that change. 3. **Annotate errors inline, aggregate warnings.** If everything is annotated with equal weight, nothing is. ### Idempotence Annotations are posted per run, and changes get pushed repeatedly. Without care, the third push leaves three copies of every finding, and a finding the author has already fixed still sits there from run one. Replace the previous run's annotations rather than adding to them, resolve or delete annotations for findings that no longer reproduce, and key annotations to content rather than to a line number so a shifted line does not create a duplicate. A review surface littered with stale bot output trains reviewers to filter out the bot entirely — which costs you the human findings that were mixed in with it. ### Where this sits in the stack Annotation is the last of the feedback placements, and it should mostly be a safety net: the editor and the commit-time check should already have shown the author almost everything the pipeline annotates. If the review surface is where people routinely first learn about a rule, the earlier placements are not working, and the annotation quality is treating a symptom. Finally, this is a courtesy that only pays if it is honest. An annotation that says a line is wrong when the rule is a matter of taste, or that offers a fix that does not compile, is worse than a log entry, because it arrives with the authority of the review surface. Annotate what you would be willing to defend in review yourself.