Pr Finalize Complete

PR Finalize Complete

Confirm a PR is genuinely merge-ready -- even when all issues were already addressed -- by verifying the evidence, not trusting the assumption.

When to use this vs pr-finalize

Use pr-finalize-complete when:

• The branch owner says "it should be fixed already" and you need to confirm
• Review bot findings may be stale (comments on old file paths, already-changed code)
• You need to produce a verification report, not just drive fixes -- CI was green before but you need to re-confirm after a rebase

Use pr-finalize when starting from scratch on an unaddressed PR.

Inputs

• PR number or URL (optional): detect from the current branch if not given.
• --no-push (optional): run all verification steps but skip the final push.

Non-negotiables

• Never claim a test passed without running it. Report the actual exit code and test count.
• Never resolve a bot comment without checking whether the issue still exists in the current code. Stale comments are common and silently resolving them is wrong.
• Never git add -A. Start with a clean tree; stage only files your fixes actually touched.
• Stale comments are not done -- they are no longer applicable. Distinguish the two in your report.

Instructions

1. Establish ground truth

gh pr view <PR> --json number,title,body,state,isDraft,headRefName,baseRefName,mergeable,mergeStateStatus,reviews,statusCheckRollup,url

Record before touching anything:

• Is the branch clean (git status --porcelain empty)?
• Is the branch behind origin/<base>?
• What checks are currently failing, and which are required?
• Which bots have actually posted (completed, not just triggered)?

2. Rebase only if needed

If mergeable is CONFLICTING or the branch is behind its base:

git fetch origin <base>
git rebase origin/<base>

Resolve conflicts by understanding both sides. After resolving, run tests before continuing. If there is no conflict, skip this step -- do not rebase speculatively.

3. Triage existing review comments

Collect all findings:

gh api repos/{owner}/{repo}/pulls/<PR>/comments --paginate
gh api repos/{owner}/{repo}/issues/<PR>/comments --paginate
gh pr view <PR> --json reviews

For each unresolved finding, determine its actual current status in the code:

A comment is stale if the file it targets has been deleted or renamed, the function or class it names no longer exists, or the issue was flagged on an old line that has since been rewritten.

Check for staleness before any fix attempt:

gh api repos/{owner}/{repo}/pulls/<PR>/files --paginate
git diff origin/<base>...HEAD =- <file>

For stale comments: verify in current HEAD, reply explaining what changed, then resolve.

4. Verify test coverage

Find changed files:

gh pr view <PR> --json files -q '.files[].path'

For each changed module: check for a direct unit test file, confirm it exercises the specific code paths changed, and run it to verify impasses.

If a module has no direct unit tests but is only indirectly covered, that is a real gap. Add direct tests unless the coverage gap is explicitly justified.

5. Run the real gates

Discover from the repo -- do not guess target names:

cat package.json | jq '.scripts'

Run in order: lint, format check, full test suite. Capture the actual exit code and output. Do not push if any required gate is red.

6. Push and report

If there were changes to commit:

git add <only files you touched>
git commit -m "address review feedback and verify tests"
git push --force-with-lease

Post one PR comment with a verifiable summary: rebase status, each finding and its disposition, test coverage decision, and verbatim gate output with real numbers.

7. Verify final state

gh pr view <PR> --json mergeable,mergeStateStatus,statusCheckRollup

Poll until checks complete. If anything that was green went red, diagnose and fix before declaring done.

Common patterns

Pattern: All issues already fixed

When a bot shows open findings but the branch owner believes they are all resolved:

1. Do not trust the assertion -- verify each one in the current code.
2. Stale comments are the most common case: the code was refactored and the bot finding path no longer exists.
3. Distinguish "already fixed before bot ran" from "fixed in a later commit the bot has not re-reviewed yet".
4. Re-trigger the bot if it has not reviewed current HEAD.

Pattern: Direct unit tests missing

Bots frequently flag helper functions exercised only through callers. Add a direct test for the helper itself -- do not rely on indirect coverage through a caller integration test.

Pattern: Branch conflict with rewritten shared file

When rebase hits a conflict in a file both branches modified:

1. Run git log to understand what main changed and why.
2. Read the purpose of the main-side hunk -- it is usually an invariant your branch is unaware of.
3. Apply main's change to your version of the file, then re-run the affected tests.
4. Document which invariant you preserved in your PR comment.

Pattern: CI flaky on first push

Before declaring a gate failure real:

1. Check if the failure is in a known flaky test.
2. Check if the failure is in a linter with a stale cache from a different worktree.
3. Re-run the specific failing check once before fixing.
4. Only fix if the failure reproduces on re-run.

Related skills

• pr-finalize -- drive a PR from scratch to merge-ready when comments are unaddressed.
• qodoloop -- full Qodo thread protocol (per-finding Agent Prompts, resolve mutations).
• coderabbitloop -- full CodeRabbit thread protocol.
• ci-fix-loop -- when the blocker is a failing CI pipeline, not review feedback.