Say what a reader gets before showing them the metaphor - #6
Conversation
The first lines described a pit crew and left the reader to work out that this is three GitHub Actions workflows, run on their own endpoint, that put a bug review, a security review and a recorded acceptance test on their pull requests. They now say that, and the pit crew follows as the picture rather than the definition. Two sections carry what the old text only implied. One walks a pull request from the first push to the acceptance test's video, so the output is visible before any YAML. The other names who this is for: a team without a second reviewer, one paying a hosted bot more than it explains, one that has to answer for where its code goes, and one whose issues carry acceptance criteria. "What you get" becomes "How the output behaves", because the new walk-through answers what you get and that section never did: it is about the properties that make the output usable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VbUeBhYNsQ6xKQWdPrj2HK
Security review —
|
Bug review —
|
Updated language for clarity and improved readability throughout the document.
Security review —
|
Bug review —
|
"One file in your repository. That is the whole installation." described the bug review and quietly implied the other two came with it. It is now one file per agent, which is still the whole of that agent's installation, because the scripts, the prompts and the permission profiles stay in the package. The endpoint, the key and the model are configured once for all three, and the closing paragraph says what the other two files cost: a name for the security review, and for the acceptance test a different trigger and two variables of its own. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VbUeBhYNsQ6xKQWdPrj2HK
Bug review —
|
Security review —
|
2 participants
What changes, and why
The README opened with the pit-crew image and left a first-time reader to work out what the thing actually is. The intro now states it plainly - three review agents, installed as GitHub Actions workflows, run on your own LLM endpoint, giving a bug review, a security review and a recorded acceptance test - and the metaphor follows as the picture rather than the definition.
Two new sections carry what the old text only implied:
## What you getbecomes## How the output behaves, because the new walk-through answers what you get and that section never did - it is about the properties that make the output usable. The acceptance-test section gained one sentence naming what it leaves behind, since the video was previously mentioned only in a table cell.Text only. No code, no workflow, no configuration changes.
Agent behaviour
No prompt, manifest or profile is touched.
Documentation
docs/is up to date, or not affecteddocs/is unaffected; every existing link from the README still points where it did.How it was verified
node --test(133 passing),node scripts/check-syntax.mjsandnode scripts/release.mjs --verifyall pass.actions/agent/action.ymlis not touched, so the self-review caveat does not apply. The new prose was also run through a copy check for stock LLM phrasing; the two dash-as-separator hits it found were rewritten.Generated by Claude Code