# Write evidence-backed technical review findings

Canonical: https://githtml.com/guides/write-evidence-backed-code-review-findings
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

An actionable technical review finding explains the condition, the evidence, and the consequence. Distinguish confirmed behavior from a hypothesis and suggest the smallest useful next step. Avoid presenting stylistic preferences as correctness failures, and keep each finding focused enough that the author can verify or challenge it directly.

## Start with the triggering condition

An illustrative finding might state that a missing export identifier reaches a lookup function without the validation described in the API guide. Before calling that a defect, inspect the relevant caller and downstream behavior. The consequence may be a documented error, an unintended failure, or no issue at all. Google's troubleshooting guidance supports testing explanations against observations; apply that discipline to review comments. A suspicious line is a starting point, not the entire argument. Link source at the reviewed revision so the author can reproduce your reasoning.

## Build the finding from four parts

Use condition, evidence, impact, and next step. An illustrative completed finding could say that an empty identifier is accepted by the visible handler, a linked test covers only valid identifiers, and the public error behavior remains unverified; request a negative test or the missing validation evidence. This is deliberately a question when the consequence has not been established. If a defect is confirmed, state the actual failure and affected scenario clearly. Do not inflate severity because a possible consequence sounds serious without evidence that it can occur.

1. Condition: identify the input, state, or sequence that matters.
2. Evidence: cite the source or result and explain what it demonstrates.
3. Outcome: state the verified consequence or the precise uncertainty to resolve.

## Keep the recommendation proportionate

A narrow validation gap rarely justifies an unsolicited redesign of the whole service. Recommend the smallest correction or investigation that addresses the evidence, and leave implementation choices open when several are valid. Separate blocking findings from suggestions using the team's conventions. If reviewing an HTML packet on a phone, capture findings in an appropriate external review channel and retain the document revision in your note. gitHtml is the reading surface, not a code-review approval system. Revisit the finding after the author responds rather than treating the first interpretation as permanent.

## Sources and further reading

- [Google SRE: Effective Troubleshooting](https://sre.google/sre-book/effective-troubleshooting/)
- [GitHub Docs: Getting permanent links to files](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files)

## Related guides

- [Review architecture boundaries from a phone without losing context](https://githtml.com/guides/review-architecture-boundaries-on-phone)
- [Trace data flow through a technical review document](https://githtml.com/guides/trace-data-flow-in-technical-review)
- [Review a PostgreSQL query-plan report safely](https://githtml.com/guides/review-postgresql-query-plan-report)
- [Review performance claims without being fooled by one fast run](https://githtml.com/guides/review-performance-claims-with-distributions)

Editorial approach: https://githtml.com/guides/about