What happened
On PR #3031, the review agent's first complete review (SHA 4747e82, run 28759467965) found 4 medium-severity [missing-doc] findings: missing CLI README entry, missing repos.md, missing CLI internals entry, and missing operations guide entry. The author added all 4 docs in subsequent commits. The next review (SHA dfbe3ec, run 28760527985) then flagged [scope-creep] for including '4 documentation files beyond the plan's explicit PR 4 scope.'
What could go better
The review agent was flagging the author for fixing its own findings — a self-contradictory outcome. While the scope-creep finding noted the docs 'were added to address prior review findings,' the finding itself creates noise and could confuse authors into thinking they shouldn't fix review findings. Confidence: high — the causal chain is unambiguous. Additionally, the human reviewer (rh-hemartin) was confused by 206 lines of auto-formatter changes in config.ts, commenting 'Not sure why config.ts was changed.' The review agent had correctly identified these as auto-formatter output but buried the explanation in review prose rather than surfacing it as an explicit callout.
Proposed change
In the review agent's skill or prompt, add guidance: when reviewing a subsequent push, cross-reference new files/changes against the prior review's findings. If new changes directly remediate prior findings (e.g., adding docs that were flagged as missing), do not flag them as scope-creep. This could be implemented as part of the pre-review context injection work in #1013. Additionally, when a file's diff is predominantly formatting/style changes (>80% whitespace or punctuation changes), surface an explicit informational note identifying it as auto-formatter output and stating which functional change triggered the formatting run.
Validation criteria
On the next 5 PRs where the review agent flags missing docs/tests and the author adds them in a follow-up push, subsequent reviews should not flag those additions as scope-creep. On PRs with auto-formatter changes, the review should explicitly call them out rather than burying the explanation.
Generated by retro agent from #3031
What happened
On PR #3031, the review agent's first complete review (SHA 4747e82, run 28759467965) found 4 medium-severity
[missing-doc]findings: missing CLI README entry, missing repos.md, missing CLI internals entry, and missing operations guide entry. The author added all 4 docs in subsequent commits. The next review (SHA dfbe3ec, run 28760527985) then flagged[scope-creep]for including '4 documentation files beyond the plan's explicit PR 4 scope.'What could go better
The review agent was flagging the author for fixing its own findings — a self-contradictory outcome. While the scope-creep finding noted the docs 'were added to address prior review findings,' the finding itself creates noise and could confuse authors into thinking they shouldn't fix review findings. Confidence: high — the causal chain is unambiguous. Additionally, the human reviewer (rh-hemartin) was confused by 206 lines of auto-formatter changes in config.ts, commenting 'Not sure why config.ts was changed.' The review agent had correctly identified these as auto-formatter output but buried the explanation in review prose rather than surfacing it as an explicit callout.
Proposed change
In the review agent's skill or prompt, add guidance: when reviewing a subsequent push, cross-reference new files/changes against the prior review's findings. If new changes directly remediate prior findings (e.g., adding docs that were flagged as missing), do not flag them as scope-creep. This could be implemented as part of the pre-review context injection work in #1013. Additionally, when a file's diff is predominantly formatting/style changes (>80% whitespace or punctuation changes), surface an explicit informational note identifying it as auto-formatter output and stating which functional change triggered the formatting run.
Validation criteria
On the next 5 PRs where the review agent flags missing docs/tests and the author adds them in a follow-up push, subsequent reviews should not flag those additions as scope-creep. On PRs with auto-formatter changes, the review should explicitly call them out rather than burying the explanation.
Generated by retro agent from #3031