| name | final-review |
| description | Use after a PR has been labeled `first pass reviewed` for at least 4 minutes — verifies CI is still green and no new commits landed since the label, aggregates outstanding non-blocking observations, posts an approval comment, replaces the label with `approved`, merges, and labels every issue referenced by `Closes |
Final Review
Phase 4 of the apijack issue workflow. The first-pass reviewer leaves a PR with first pass reviewed. After a 4-minute soak window — long enough for a human to intervene, short enough to keep the loop moving — the final reviewer takes the PR across the line.
When to Use
- A PR is labeled
first pass reviewed and the label has been there for at least 4 minutes
- CI is fully green and the PR is mergeable
- No new commits have landed on the head since the first-pass-reviewed label was applied
This skill is invoked automatically by the final-review cron, or manually via /final-review <pr>.
Steps
1. Verify the gate is still satisfied
The cron's prompt_cmd already gates on label-applied-time and head-vs-label staleness. Re-verify the rest before any write, and capture the head SHA — step 6 will pin the merge to it so a commit landing mid-flow can't be merged in unreviewed:
HEAD_SHA=$(gh pr view <pr> --json headRefOid --jq '.headRefOid')
gh pr view <pr> --json state,mergeable,mergeStateStatus,labels
gh pr checks <pr>
gh api "repos/normalled/apijack/pulls/<pr>/reviews" \
--jq 'map(select(.state == "CHANGES_REQUESTED" and .dismissed_at == null)) | length'
Abort and STOP — without writing anything — if any of:
- PR state is not
OPEN
first pass reviewed is not currently on the PR- Any check status is
fail, pending, queued, or in_progress
mergeable is false or mergeStateStatus indicates conflicts- Any active "request changes" review (the count above is non-zero)
If the gate fails, leave a brief comment naming the failed check via scripts/pr-comment.sh <pr> <body-file> and stop.
2. Read the prior first-pass-review body
gh api "repos/normalled/apijack/pulls/<pr>/reviews" \
--jq 'map(select(.body // "" | startswith("> 🤖 **Automated review by claude**")))
| sort_by(.submitted_at) | reverse | .[0].body // empty'
Extract the bullets inside <details><summary>Non-blocking observations</summary> ... </details>. These are the items to surface in the approval comment. Ignore the Nitpicks block — too noisy for this summary.
3. Cross-reference open issues
For each non-blocking observation, check whether an open issue already tracks it:
gh issue list --repo normalled/apijack --state open --limit 50 --json number,title,body,labels
Match by topical keywords from the observation (function names, file paths, behaviors). If a single open issue clearly covers the bullet, append (#NN). If unclear or no match, leave the bullet alone — do not invent issue links.
4. Build the approval body
Use the Write tool — never inline in a heredoc — to avoid backtick-escaping artifacts.
Write the body to .claude-jobs/review-bodies/final-<pr>.md. Then:
.claude/skills/review-issue/scripts/post-review.sh <pr> comment .claude-jobs/review-bodies/final-<pr>.md
You don't need to literally approve the PR. Just post a comment that says you approve. The workflow signal is the approved label moved in step 5.
Body template
> 🤖 **Final review by claude** — generated by the `final-review` skill. CI is green, no blockers, soak window elapsed. Marking approved and merging.
Approved.
### Outstanding observations from first-pass review
- <bullet copied verbatim from the first-pass body> [optional `(#NN)` link if a tracking issue exists]
- <next bullet>
If the first-pass review had no Non-blocking observations block at all, omit the ### Outstanding observations heading entirely — keep the body to two short lines.
5. Move the label
.claude/skills/review-issue/scripts/set-review-label.sh <pr> "approved"
This atomically removes first pass reviewed and adds approved. Other PR labels are untouched.
6. Merge (SHA-pinned)
.claude/skills/final-review/scripts/merge-pr.sh <pr> "$HEAD_SHA"
The script pins the merge to $HEAD_SHA, so a commit landing between step 1 and step 6 causes GitHub to reject the merge with 409. If the script exits non-zero, STOP — do not retry. The cron will pick the PR up again next tick after the new commit gets a fresh first-pass review.
7. Label referenced issues with merged to dev
.claude/skills/final-review/scripts/label-merged-issues.sh <pr>
Parses the PR body for Closes #N / Fixes #N / Resolves #N and adds the merged to dev label to each referenced issue. The label marks the issue as shipped to dev, pending release to main. Idempotent and best-effort — per-issue failures are logged but do not fail the run.
8. Stop
This skill does NOT invoke next-deployer. Publishing to the rolling next channel is a separate concern; if you want it automated, that belongs in its own cron.
Red Flags — Do Not Approve
- "CI has one flaky test, the rest pass" → STOP, leave a comment, ask a human
- "There's a
request-changes review but it's old / unresolved" → STOP
- "The first-pass label is only 8 minutes old, close enough" → STOP, the cron will catch it next tick
- "There's a commit right after the first-pass label, but it's just a typo fix" → STOP, the first-pass review is stale; force a re-review
- "There's no prior first-pass body to read" → STOP, the cron should have filtered this out; abort defensively
Output
Either: an approving review + merged PR + deleted branch, or: a comment naming the failed gate and STOP.
