| name | human-review-pack |
| description | Assemble a concise, evidence-backed PR/release review pack — what changed and why, impact, the verify proof, reviewer findings (fixed and deferred), and the exact decision needed. Read-only; writes the pack. Front door for /human-review-pack. |
| allowed-tools | Read, Grep, Glob, Bash, Write |
| tags | ["sdlc","review","release"] |
human-review-pack
Assemble everything a human needs to approve a PR or release — with evidence, not
claims. Read-only. The pack must let a reviewer decide in minutes and must not overstate
readiness.
Steps
- Collect the diff summary — changed files/areas per stack; new endpoints/migrations/UI.
- Pull the proof — the
/verify reports and per-stack verify markers; the QA suite
result. Read the inputs your instructions point to. If proof is missing or status:"fail",
say so — do not claim green.
- Pull the reviewer findings — from the architecture review and each stack's review;
separate what was fixed from what is deferred/accepted.
- Assess risk & release readiness — migrations, flags, rollout/backout, data impact.
- Write the pack and state the exact decision required.
The pack must include (with evidence/links)
- What changed — feature summary + per-stack change list.
- Why — link the requirement/HLD; the problem solved.
- Files changed — grouped by area; call out anything security/auth/data-sensitive.
- API / DB / UI impact — contract changes (breaking?), migrations (+ rollback), new UI states.
- Tests & proof — commands run and pass/fail (from
/verify); coverage vs the
coverage bar (80% on changed code); QA journeys covered;
screenshots / Playwright traces for frontend.
- Review findings fixed — with the reviewer + severity.
- Findings intentionally NOT fixed — each with a reason and risk acceptance.
- Risks & limitations — known issues, perf/scale caveats, follow-ups.
- Rollout & backout — flag state, phased plan, metrics to watch, how to revert.
- Decision needed — approve / changes requested / reject, and exactly what to approve
(e.g. merge order backend → frontend).
Edge cases to represent honestly
- Partial green — some checks pass, one is flaky/red → say it plainly; don't average it away.
- Deferred blockers — a major finding accepted for later needs explicit sign-off and a ticket.
- Missing proof — no verify marker, or
status:"fail" → the pack recommends "not ready".
- Breaking contract change — surface prominently with the consumer migration plan.
- Risky migration / irreversible step — flag as requiring extra human attention.
Output
Write the pack to the artifact path your instructions specify (the orchestrator passes it).
Running standalone? write to a sensible path you choose and tell the user where. Never claim readiness
without the proof to back it — the review pack is a decision aid, not a rubber stamp.
Output contract
Return pack_path, recommendation (ready | changes-requested | not-ready,
mirroring the pack's "Decision needed" section), and summary (one line the human reads
at the release gate).
