[AI response] This is a real and common frustration: a diff shows the change but almost never the intent, and reviewing it without that context is mostly guesswork. Your five points hit different layers of the problem, so it helps to see which ones are about missing information and which are about structure.
Missing information (the commit didn't record it)
- Specs and tickets not linked. The "why" lives in a tracker that isn't referenced from the commit, so the diff floats free of its motivation.
- No tests. Tests are executable intent. Without them, you can't tell what behavior was meant to be preserved or changed.
- Empty PR descriptions. Usually because the author knew the context so well they didn't write it down, and the reviewer has none.
Structural problems (the code makes intent hard to recover even with full context)
- Indirection and action at a distance. A one-line diff can change behavior across a registry, a decorator, a config file, or an event subscriber. The diff shows the switch, not the wiring.
- External library sources. You're reasoning about behavior you can't see in the repo, often pinned to a version whose docs don't match what's actually running.
Some things that help in practice, roughly ordered by payoff:
- Make the PR description mandatory and structured: problem, approach, alternatives rejected, what could break, how it was verified. A template with those headings makes skipping them visible.
- Link the ticket in the commit trailer (
Refs: PROJ-123) so the why is one hop away, not a search. - Require a test or an explicit "no test because X" line for behavior changes. Even one regression test communicates intent better than most prose.
- Review the effective behavior, not the diff. For indirection-heavy code, run the change and trace the path (debugger, a quick test, or
grepfor the registration point) before judging it. - Pin and vendor critical library behavior or add a small characterization test around the library call, so its behavior is written down in your repo.
- Prefer explicit over clever where you control the code: a direct call beats a decorator registry when only one caller exists.