finalize-pr

What this skill does

# Finalize PR

**FULLY AUTOMATIC** - Fully automates PR finalization: monitor, fix, prepare for merge. Assumes PR already exists.
No manual intervention required. For manual review-focused workflows, use `/review-pr`.

> **State warning**: Automated reviewers (CodeQL, Copilot, AI reviews) post
> asynchronously. CI may have re-run. Merge conflicts may have appeared.
> Re-fetch live PR state from Step 1.

## Critical Rules

1. **Wait for user approval to merge** - Report ready status, then pause for user merge command
2. **Verify all checks pass via Phase 3 gate** - Re-run Phase 3 against live API on every
   invocation; "mergeable" means git-conflict-free only, not fully unblocked.
3. **Resolve all conversations** - Automatically invoke `/resolve-pr-threads` for review threads
4. **Fix all CodeQL violations** - Check repository and automatically fix using `/resolve-codeql`
5. **Simplify all code changes** - Invoke /simplify at Step 2.3.5 (after all fixes). Pre-push simplification is handled by `/ship`.
6. **Validate locally before pushing** - Run project linters and tests
7. **Monitor CI early, block last** - Start CI monitoring in background immediately, but fix other issues while it runs
8. **Update PR metadata automatically** - Before reporting ready, update title, description, and linked issues via haiku subagent
9. **Take direct action** - Identify issues and fix them automatically (except merge decisions)
10. **Include bot PRs** - Never filter by author. All modes include dependabot, release-please, claude, github-actions, etc.
11. **Never cross org boundaries** - Org mode derives owner from current repo only

## Phase 1: PR Discovery and Targeting

Steps 1.1–1.4 run sequentially.

### 1.1 Parse Argument

| Argument | Mode | Target |
|---|---|---|
| _(none)_ | Current branch | Single PR on current branch |
| `42` | Single PR | PR #42 |
| `all` | Repo-wide | All open PRs in current repo |
| `org` | Org-wide | All open PRs across all repos in current org |

### 1.2 Discover PRs

- **Single/current-branch**: Resolve PR number from current branch, proceed to Phase 1.5.
- **Repo-wide (`all`)**: List all open PRs (limit 50) with number, title, author, headRefName.
- **Org-wide (`org`)**: Enumerate repos, list open PRs per repo (limit 50 each, 50 total cap), include `repository` field.

### 1.3 Tag Bot PRs

Tag PRs where `author.login` ends with `[bot]` for reporting. Process identically to human PRs.

### 1.4 Confirm Batch (Multi-PR Only)

Display discovery list before proceeding. Verify working tree is clean (if dirty, ask user to commit/stash). Note current branch for restoration.

## Phase 1.5: Build Context Brief (if not provided)

If invoked via `/ship`, a context brief is already in session context — skip this step.

If invoked standalone, build a lightweight brief from:

1. PR description: `gh pr view <PR_NUMBER> --json body --jq '.body'`
2. Commit log relative to PR base: `BASE=$(gh pr view <PR_NUMBER> --json baseRefName --jq '.baseRefName') && git log --oneline origin/$BASE..HEAD`

Synthesize purpose, key changes, and intentional patterns into a 5-10 line block.
This informs `/resolve-pr-threads` (Phase 2.2) when evaluating reviewer feedback.

## Phase 2: Resolution Loop (AUTOMATIC)

**Execution strategy**: Start CI monitoring in the background (Step 2.1) and
fix all other issues in parallel while CI runs. Never block on CI when other
work is available. Pre-push simplification is handled by `/ship`; within this
skill, /simplify runs once at Step 2.3.5 after all fixes are applied.

_For multi-PR modes, Phases 2-5 execute once per PR in sequence. Check out each PR branch at the
start of each iteration. For org-wide mode, use `repository.nameWithOwner` from Phase 1 as the
`--repo` argument when checking out._

Steps 2.1 and 2.2 start concurrently (2.1 is non-blocking). Steps 2.3 and 2.4 run sequentially after 2.2.

### 2.1 Start CI Monitoring (BACKGROUND)

Launch CI monitoring in a background Task agent (`run_in_background: true` on the Task tool).
Monitor CI checks using `--watch` so the agent blocks until all complete.

Do NOT wait for the agent to finish — proceed to 2.2 immediately.

### 2.2 Parallel Fixes

Run these checks simultaneously. Launch independent fixes in parallel via
Task agents when they touch different files. Invoke `superpowers:dispatching-parallel-agents` for dispatch patterns.

#### CodeQL Violations

Run the **canonical code-scanning alert count** from /gh-cli-patterns.
Replace `<OWNER>` and `<REPO>` per the placeholder convention in that skill.

**If violations found**: Invoke `/resolve-codeql fix`, validate locally.

#### Review Threads

Invoke `/resolve-pr-threads`. It exits cleanly when no threads exist.
After completion, validate locally.

#### Merge Conflicts

Check if the PR has git conflicts (`mergeable` field). **`mergeable: MERGEABLE` means no git
conflicts only** — it does NOT mean the PR is fully ready to merge. **If conflicts**: Fetch main,
attempt merge, report unresolvable conflicts for user. After resolution, validate locally. Full
readiness verification (including `mergeStateStatus`, CI, CodeQL, review decision, threads) happens
in Phase 3.

### 2.3 CI Failure Fixes

Check background CI results from 2.1:

- **All passing**: Proceed to Phase 3
- **Failures**: Fetch failed run logs, fix locally, validate, commit and push.
  Restart background CI monitoring and loop back to 2.2 if new issues emerged.

### 2.3.5 Final Simplification

After all fixes from 2.2 and 2.3 are complete, invoke /simplify once on all
cumulative changes. This is the single /simplify pass within `/finalize-pr` —
it catches any code introduced by fix iterations (CodeQL fixes, CI fixes,
review thread implementations) that wasn't part of the original pre-push
simplification. If /simplify produces changes, validate locally, commit,
and push before proceeding to 2.4.

### 2.4 Health Check

Verify final PR state, mergeability, and check status. If fixes introduced new issues, loop back to 2.2.

## Phase 3: Pre-Handoff Verification

> ⛔ **NO SHORT-CIRCUIT — EVERY INVOCATION, EVERY TIME.**
> Run this gate against live API state now, even if this PR was verified
> 30 seconds ago. Subagent self-reports and prior in-session messages are
> historical snapshots, not current truth. The world changes: CodeQL
> completes async, required reviewers post async, Renovate force-pushes,
> branch protection re-evaluates. Re-run every query below.

### 3.1 PR State Gate (GraphQL — re-run now)

Run the **canonical PR-readiness gate** from /gh-cli-patterns against
`<PR_NUMBER>`. Replace `<OWNER>`, `<REPO>`, `<PR_NUMBER>` per the placeholder convention in
that skill.

**Required values — if any fail, return to Phase 2:**

| Field | Required | Abort message |
|-------|---------|---------------|
| `state` | `OPEN` | "PR is not open" |
| `mergeable` | `MERGEABLE` | "PR has git conflicts — rebase/merge in Phase 2" |
| `mergeStateStatus` | `CLEAN` or `HAS_HOOKS` | "PR merge state is `{value}` — blocked, return to Phase 2" |
| `isDraft` | `false` | "PR is a draft — mark ready for review first" |
| `reviewDecision` | `APPROVED` or `null` | "Review decision is `{value}` — changes requested or required" |
| `statusCheckRollup.state` | `SUCCESS` | "CI rollup is `{state}` — fix failures in Phase 2" |
| All `reviewThreads.isResolved` | `true` | "Unresolved threads — run `/resolve-pr-threads`" |
| `reviewThreads.pageInfo.hasNextPage` | `false` | "More than 100 threads — paginate manually and re-verify" |

> **`mergeStateStatus` values that are NOT ready:** `BEHIND` (needs rebase),
> `BLOCKED` (branch protection — could be required review, CodeQL, or required
> status check), `DIRTY` (conflicts), `DRAFT`, `UNKNOWN` (GitHub computing),
> `UNSTABLE` (checks failed or pending). Any of these = return to Phase 2.

### 3.2 CodeQL Gate (REST — separate from CI, re-run now)

`statusCheckRollup` does NOT include CodeQL alert state. Run the **canonical code-scanning
alert count** from