/code-review: structured output is hard to read, and the format changes with the effort level

Status Open
Reported on v2.1.220
Maintainer reply None cached
Activity 1 comment · opened Aug 3, 2026

Version: 2.1.220
Platform: macOS (darwin 24.6.0)

Summary

Two related problems with /code-review:

1. The structured findings output is hard to read. At higher effort levels the results are emitted through the ReportFindings tool and rendered as a structured findings list. This is impossible to read. I keep asking to re-format into a human readable format.

<img width="1480" height="137" alt="Image" src="https://github.com/user-attachments/assets/1b578e93-6c4c-414c-b79e-88b6b6b9bd6b" />

2. The output format silently changes depending on the effort level. /code-review and /code-review xhigh do not present results the same way. The ReportFindings tool contract makes this explicit:

Use this only when the active code-review instructions tell you to report findings with this tool; otherwise follow whatever output format those instructions specify.

and its level field is documented as "Effort level the review ran at", with values low | medium | high | xhigh | max. So which output path is taken is a function of the effort tier.

From a user's point of view, asking for a more thorough review should not change how the results are displayed. Effort is a depth knob; it should not also be a presentation knob.

Impact

Turning up effort to get a better review means giving up the readable output. That is a bad trade to have to make, and it isn't documented anywhere, the format change is a surprise every time.

Expected

  • One consistent, human-readable output format across every effort level: markdown, root cause / theme first, findings ordered by severity, file:line references inline.
  • If the structured ReportFindings payload is needed for host-UI rendering or for the "apply fixes" flow, keep emitting it — but don't let it replace the readable write-up.
  • If both formats must exist, make it a user setting rather than an implicit consequence of the effort argument.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗