final-review

Category: Tools & Productivity | Uploader: normalled | Downloads: 0 | Version: v1.0（Latest）

Use after a PR has been labeled `first pass reviewed` for at least 10 minutes — verifies CI is still green and no new commits landed since the label, aggregates outstanding non-blocking observations, posts an approving review, replaces the label with `approved`, and merges.

Changelog: Source: GitHub https://github.com/normalled/apijack

Directory Structure

Current level: tree/main/.claude/skills/final-review/

📁 scripts/
- 📄 find-final-review-candidate.sh 1.5 KB
📄 SKILL.md 4.8 KB

SKILL.md

---
name: final-review
description: Use after a PR has been labeled `first pass reviewed` for at least 10 minutes — verifies CI is still green and no new commits landed since the label, aggregates outstanding non-blocking observations, posts an approving review, replaces the label with `approved`, and merges.
---

# Final Review

Phase 4 of the apijack issue workflow. The first-pass reviewer leaves a PR with `first pass reviewed`. After a 10-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 10 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:

```bash
gh pr view <pr> --json state,mergeable,mergeStateStatus,labels,headRefOid
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 (`gh pr comment` is allowed for this) and stop.

### 2. Read the prior first-pass-review body

```bash
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:

```bash
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:

```bash
.claude/skills/review-issue/scripts/post-review.sh <pr> approve .claude-jobs/review-bodies/final-<pr>.md
```

`--approve` registers a GitHub-recognized approval AND posts the body as a review comment in one call.

#### Body template

```
> 🤖 **Final review by claude** — generated by the `final-review` skill. CI is green, no blockers, soak window elapsed. Approving 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

```bash
.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

```bash
gh pr merge <pr> --merge --delete-branch
```

`--merge` (not squash) preserves history on `dev`. `--delete-branch` removes the issue branch.

### 7. 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.

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

final-review

Directory Structure

SKILL.md

Report

Notice