| name | human-review-guide |
| description | Build a human-facing review.md for a change set (uncommitted, given commits, or a PR) — PlantUML diagram diffs, screenshots of impacted screens, a code-review summary, the core business logic, and the acceptance tests, each with code snippets and IntelliJ deep-links. Explicit invocation only — user types /human-review-guide. |
| disable-model-invocation | true |
/human-review-guide — assemble a review.md for a human
Produce one file, review/review.md, that lets a human review a change set fast:
diagram deltas, screenshots, the code-review summary, the core logic, and the
acceptance tests — every code reference a clickable IntelliJ deep-link.
You are the assembler, not the reviewer of record — surface everything a reviewer
needs and point at what deserves their eyes. Do not commit, push, or --fix.
Step 0 — Resolve the change set (from $ARGUMENTS)
Pick the mode from what the user passed:
- empty → uncommitted work:
BASE=HEAD, diff = git --no-pager diff HEAD (staged + unstaged).
- a ref / range / SHA(s) (e.g.
abc123, main..HEAD, HEAD~3) → BASE=<the older ref>,
diff = git --no-pager diff $BASE..$HEAD.
- a PR (
#123, 123, or a github URL) → gh pr checkout <n> (or gh pr diff <n>),
set BASE=$(gh pr view <n> --json baseRefName -q .baseRefName).
Establish two things and reuse them everywhere below:
CHANGED=$(git --no-pager diff --name-only $BASE...HEAD) (or HEAD for uncommitted).BASE — the ref to diff against (used by the PlantUML tool).
Print a one-line scope banner: mode, refs, and git --no-pager diff --stat. If the
change set is empty, say "Nothing to review." and stop.
Create the output dir: review/assets/.
Step 1 — PlantUML diagram deltas (only if any *.puml changed)
One bundled script covers all three architecture diagrams — domain model, DB
schema, and packages — diffing each against the merge-base with $BASE,
rendering them, and dropping everything into review/assets/:
.claude/skills/human-review-guide/scripts/collect-review-artifacts.sh $BASE
It produces, when the change set warrants it:
| Artifact | Use in review.md |
|---|
review/assets/<name>.diff.svg | embed one per changed diagram |
review/assets/architecture.html | standalone gallery — link it, don't inline it |
review/assets/SUMMARY.md | same deltas as remote-rendered markdown (fallback) |
Additions render red, removals red + struck-through. Embed under
## Architecture deltas, one subsection per diagram, each with a one-line
plain-English note on what structurally changed (new entity, dropped relation,
moved component).
If it prints no architecture diagram changed, omit the section entirely —
that is a clean exit (0), not a failure. Do not retry it or diff the .puml
files by hand.
Notes:
- The script is a thin orchestrator over
scripts/architecture-diff.sh,
puml_diff.py, and scripts/build_pr_gallery.py. Call it rather than those
directly, and never copy their logic into the skill — a second fork of the
review pipeline would drift silently.
puml-diff-vs-git.sh remains the single-diagram primitive. Reach for it only
when you want one specific diagram against an unusual ref.- Without
plantuml on PATH the script skips local rendering and says so; fall
back to the encoded plantuml.com URLs already in SUMMARY.md. The section
survives, but the images then need the network.
- PR mode: CI publishes this same gallery to
https://victorrentea.github.io/petclinic/pr/<n>/ and links it from a sticky
comment. Link that page — but still embed the SVGs locally, because the
published gallery is deleted when the PR closes.
pr-diff/ is git-ignored scratch space and safe to regenerate; never commit it.
Step 2 — Screenshots of impacted screens (only if frontend changed)
If any petclinic-frontend/src/app/** files changed, map each changed feature folder
(owners, pets, vets, visits, pettypes, specialties, invoice, …) to its
route and capture the current screen.
Pre-check the dev server: curl -s -o /dev/null -w "%{http_code}" http://localhost:4200/.
If not 200, skip this section with the note "frontend not running — screenshots
skipped (start ./start-frontend.sh)" and continue; never abort the whole review.
When up, use chrome-devtools-mcp: new_page → resize_page 1280×800 →
navigate_page to http://localhost:4200/<route> → take_screenshot (png) into
review/assets/<feature>-<state>.png. One or two shots per impacted feature is
enough. Embed under ## Impacted screens with a caption naming the route.
Step 3 — Code-review summary
Run a read-only review of the same change set — invoke /code-review (no --fix,
no --comment). Distill its output into ## Code-review findings: a short table
severity · file:line · issue → suggestion, most-severe first, each file:line
rendered as an IntelliJ deep-link (see IntelliJ links below). If it's clean, say so.
Step 4 — Core business logic
Read the diff and identify the substance — the rules/decisions that changed, not
the plumbing (DTOs, mappers, imports, formatting). Under ## Core business logic,
write 2–5 bullets in domain language ("a visit can no longer be booked in the past"),
each backed by a short code snippet (the few decisive lines) and an IntelliJ
deep-link to the exact line. This is the section a domain expert reads first.
Step 5 — Acceptance tests
Find the tests that pin this behavior: backend *Test.java /
petclinic-ui-test/features/** / frontend *.spec.ts touched by or covering the
change. Under ## Acceptance tests, list each as a deep-linked file:line with a
one-line "asserts that …". Then state plainly whether the changed business logic is
covered — and call out any behavior from Step 4 with no matching test.
IntelliJ deep-links (use for every code reference)
Format each reference as a Markdown link whose target opens the exact line in IntelliJ:
[`Owner.java:42`](jetbrains://idea/navigate/reference?project=petclinic&path=<repo-relative-path>:42)
project=petclinic (this repo's IntelliJ project name).path is repo-relative (e.g. petclinic-backend/src/main/java/.../Owner.java);
line number appended after : (1-based). Requires JetBrains Toolbox installed.
Output & wrap-up
- Write everything to
review/review.md; keep image links relative (assets/…png)
so the file is portable. Order sections: scope → Architecture deltas → Impacted
screens → Code-review findings → Core business logic → Acceptance tests.
- End review.md with a ## Review these first list: the 2–3 spots most deserving
human judgment (riskiest change, uncovered logic, deferred finding).
review/ is a throwaway artifact — remind the human to delete it (or add to
.gitignore) rather than commit it.- Print the path to
review/review.md and offer to open it. Do not commit or push.
