Review report

Skill: pageship-review-report

A review report tells the reader whether a change or a plan is ready, what is wrong with it, how much each problem matters and how sure the reviewer is. The reader fixes the worst finding first and trusts each finding as far as its evidence goes.

Your agent picks a review report in two cases:

• You ask it to review a change, a plan or another document. The findings, severities and verdict are the agent’s own, and the summary says so.
• You ask it to write up a review someone else did, such as notes or comments. That review is the source, and its findings, severities and verdict keep their words.

What the reader gets

The parts come in this order:

1. Title and summary. What was reviewed, then the verdict in one sentence, the number of findings at each severity, the most severe finding, and who reviewed it. With more than five findings, a table of them follows, each linked to its finding.
2. Findings. Most severe first. Each has a one-sentence heading, its severity and status in words, where it is, what was checked, the evidence, and a fix when the evidence points to one.
3. Open questions. Concerns the agent can’t tie to a place in the subject, and causes or consequences the evidence doesn’t show.
4. Scope. What was reviewed and how, and what wasn’t, with the reason.
5. Verdict. The verdict, the rule it follows from, and what would change it.

How it rates findings

Each finding has a status:

• Verified. The evidence shows the problem by itself, such as a command’s output or two passages that contradict each other.
• Not verified. It rests on reading or reasoning the agent could not confirm. The finding says what would confirm it.

When the agent reviews, it rates each finding as a blocker, major, minor or note. The verdict follows from the most severe finding: Not ready with any blocker, Ready after changes with a major and no blocker, and Ready otherwise. When your project defines its own scale, the agent maps it onto this one and says how.

The review leaves the subject as it found it. To run tests, the agent copies the project to a temporary folder and deletes the copy afterwards.

Patterns it often uses

• Code blocks for the quoted lines behind a finding.
• Tables for the findings summary.

Example request

Review the changes on this branch against main and write up the findings as a review report.