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

1. Collect the diff summary — changed files/areas per stack; new endpoints/migrations/UI.
2. Pull the proof — the /verify reports and .kv/last-verify.json markers per stack;

the QA suite result. If proof is missing or status:"fail", say so — do not claim green.

1. Pull the reviewer findings — .sdlc/<slug>/architecture-review.md and each stack's

reviews/summary.md; separate what was fixed from what is deferred/accepted.

1. Assess risk & release readiness — migrations, flags, rollout/backout, data impact.
2. Write the pack and state the exact decision required.

The pack must include (with evidence/links)

1. What changed — feature summary + per-stack change list.
2. Why — link the PRD/HLD; the problem solved.
3. Files changed — grouped by area; call out anything security/auth/data-sensitive.
4. API / DB / UI impact — contract changes (breaking?), migrations (+ rollback), new UI states.
5. Tests & proof — commands run and pass/fail (from /verify); coverage vs threshold;

QA journeys covered; screenshots / Playwright traces for frontend.

1. Review findings fixed — with the reviewer + severity.
2. Findings intentionally NOT fixed — each with a reason and risk acceptance.
3. Risks & limitations — known issues, perf/scale caveats, follow-ups.
4. Rollout & backout — flag state, phased plan, metrics to watch, how to revert.
5. 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 .sdlc/<slug>/review-pack.md. Return pack_path. Never claim readiness without the proof to back it — the review pack is a decision aid, not a rubber stamp.