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 verification receipts and per-repository verification status your
instructions supply (commands run, exit codes, the verified commit, changed tests) and the
QA suite result. If proof is missing, failed, or verifies a different commit than the one
being released, 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)
- Unconfirmed decisions — first — when your instructions supply an assumption log, open
the pack with it: every assumption and every item left open, as written, and every gate
answered without a person. These are guesses nobody confirmed; never fold them into
"what changed" or soften them.
- Acceptance-criteria trace — when your instructions supply one, show it as written: each
criterion, the cases that cover it, and its result. A criterion that is failing or not run
makes the recommendation "not-ready" unless the human already accepted it.
- Design drift — when your instructions supply a drift report, list every place the code
departs from the approved design as written; blocking drift makes the recommendation
"not-ready" until the code or the design is changed and re-approved.
- 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 — per repository, the commands run and their pass/fail from the
verification receipt, checks that were skipped, and each existing test the branch changed
with the reviewer's justification; coverage only where a receipt records it; 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.
- Autopilot run — assumptions or open items exist → name the ones that change behaviour a
user will see; an open item that blocks an acceptance criterion makes the pack "not-ready".
- Missing proof — no verification receipt, a failed check, or a receipt for a different
commit than the one released → the pack recommends "not-ready".
- Changed tests — an existing test modified or deleted without a stated justification →
list it under risks; never present it as passing coverage.
- 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).
1---2name: human-review-pack3description: Assemble a concise, evidence-backed PR/release review pack — what changed and why, impact, the verification proof, reviewer findings (fixed and deferred), and the exact decision needed. Read-only; writes the pack. Front door for /human-review-pack.4allowed-tools: Read, Grep, Glob, Bash, Write5tags: [sdlc, review, release]6metadata:7 source: https://skillmd.com/skills/keyvaluesoftwaresystems/human-review-pack8---910# human-review-pack1112Assemble everything a human needs to approve a PR or release — **with evidence, not13claims.** Read-only. The pack must let a reviewer decide in minutes and must not overstate14readiness.1516## Steps171. **Collect the diff summary** — changed files/areas per stack; new endpoints/migrations/UI.182. **Pull the proof** — the verification receipts and per-repository verification status your19 instructions supply (commands run, exit codes, the verified commit, changed tests) and the20 QA suite result. If proof is missing, failed, or verifies a different commit than the one21 being released, say so — do not claim green.223. **Pull the reviewer findings** — from the architecture review and each stack's review;23 separate what was **fixed** from what is **deferred/accepted**.244. **Assess risk & release readiness** — migrations, flags, rollout/backout, data impact.255. **Write** the pack and state the exact decision required.2627## The pack must include (with evidence/links)280. **Unconfirmed decisions — first** — when your instructions supply an assumption log, open29 the pack with it: every assumption and every item left open, as written, and every gate30 answered without a person. These are guesses nobody confirmed; never fold them into31 "what changed" or soften them.321. **Acceptance-criteria trace** — when your instructions supply one, show it as written: each33 criterion, the cases that cover it, and its result. A criterion that is failing or not run34 makes the recommendation "not-ready" unless the human already accepted it.352. **Design drift** — when your instructions supply a drift report, list every place the code36 departs from the approved design as written; blocking drift makes the recommendation37 "not-ready" until the code or the design is changed and re-approved.383. **What changed** — feature summary + per-stack change list.394. **Why** — link the requirement/HLD; the problem solved.405. **Files changed** — grouped by area; call out anything security/auth/data-sensitive.416. **API / DB / UI impact** — contract changes (breaking?), migrations (+ rollback), new UI states.427. **Tests & proof** — per repository, the commands run and their pass/fail from the43 verification receipt, checks that were skipped, and each existing test the branch changed44 with the reviewer's justification; coverage only where a receipt records it; QA journeys45 covered; screenshots / Playwright traces for frontend.468. **Review findings fixed** — with the reviewer + severity.479. **Findings intentionally NOT fixed** — each with a reason and risk acceptance.4810. **Risks & limitations** — known issues, perf/scale caveats, follow-ups.4911. **Rollout & backout** — flag state, phased plan, metrics to watch, how to revert.5012. **Decision needed** — approve / changes requested / reject, and exactly what to approve51 (e.g. merge order backend → frontend).5253## Edge cases to represent honestly54- **Partial green** — some checks pass, one is flaky/red → say it plainly; don't average it away.55- **Deferred blockers** — a major finding accepted for later needs explicit sign-off and a ticket.56- **Autopilot run** — assumptions or open items exist → name the ones that change behaviour a57 user will see; an open item that blocks an acceptance criterion makes the pack "not-ready".58- **Missing proof** — no verification receipt, a failed check, or a receipt for a different59 commit than the one released → the pack recommends "not-ready".60- **Changed tests** — an existing test modified or deleted without a stated justification →61 list it under risks; never present it as passing coverage.62- **Breaking contract change** — surface prominently with the consumer migration plan.63- **Risky migration / irreversible step** — flag as requiring extra human attention.6465## Output66Write the pack to the artifact path your instructions specify (the orchestrator passes it).67Running standalone? write to a sensible path you choose and tell the user where. Never claim readiness68without the proof to back it — the review pack is a decision aid, not a rubber stamp.6970## Output contract71Return `pack_path`, `recommendation` (`ready` | `changes-requested` | `not-ready`,72mirroring the pack's "Decision needed" section), and `summary` (one line the human reads73at the release gate).