Prepare PR

Overview

Prepare the PR head branch for merge after /review-pr.

Inputs

• Ask for PR number or URL.
• If missing, use .local/pr-meta.env if present in the PR worktree.

Safety

• Never push to main.
• Only push to PR head with explicit --force-with-lease against known head SHA.
• Do not run git clean -fdx.
• Wrappers are cwd-agnostic; run from repo root or PR worktree.

Execution Contract

1. Run setup:

scripts/pr-prepare init <PR>

If setup reports rebase conflicts, resolve files and continue rebase non-interactively:

git -C .worktrees/pr-<PR> add <resolved-files>
git -C .worktrees/pr-<PR> -c core.editor=true rebase --continue

2. Resolve findings from structured review:

• .local/review.json is mandatory.
• Resolve all BLOCKER and IMPORTANT items.

3. Commit scoped changes with concise subjects (no PR number/thanks; those belong on the final merge/squash commit).

4. Run gates via wrapper.

5. Push via wrapper (includes pre-push remote verification, one automatic lease-retry path, and post-push API propagation retry).

Optional one-shot path:

scripts/pr-prepare run <PR>

Steps

1. Setup and artifacts

scripts/pr-prepare init <PR>

ls -la .local/review.md .local/review.json .local/pr-meta.env .local/prep-context.env
jq . .local/review.json >/dev/null

2. Resolve rebase conflicts if present

If scripts/pr-prepare init <PR> stopped on conflicts, resolve and continue until rebase completes:

cd .worktrees/pr-<PR>
git status --short
git add <resolved-files>
GIT_EDITOR=true git rebase --continue

Do not use plain git rebase --continue in automation.

3. Resolve required findings

List required items:

jq -r '.findings[] | select(.severity=="BLOCKER" or .severity=="IMPORTANT") | "- [\(.severity)] \(.id): \(.title) => \(.fix)"' .local/review.json

Fix all required findings. Keep scope tight.

4. Update changelog/docs (changelog is mandatory in this workflow)

jq -r '.changelog' .local/review.json
jq -r '.docs' .local/review.json

Changelog gate requirement:

• CHANGELOG.md must include a newly added changelog entry line.
• When PR author metadata is available, that same changelog entry line must include (#<PR>) thanks @<pr-author>.
• Append new entries to the end of the relevant section (### Changes or ### Fixes). Do not insert at the top or middle of the section — append-only ordering prevents merge conflicts when multiple PRs touch the same version block.

5. Commit scoped changes

Use concise, action-oriented subject lines without PR numbers/thanks. The final merge/squash commit is the only place we include PR numbers and contributor thanks. If you create a dedicated changelog commit, the subject must describe the actual user-facing change content; avoid generic subjects like "add PR entry" or "update changelog".

Use explicit file list:

scripts/committer "fix: <summary>" <file1> <file2> ...

6. Run gates

scripts/pr-prepare gates <PR>

7. Push safely to PR head

scripts/pr-prepare push <PR>

This push step includes:

• robust fork remote resolution from owner/name,
• pre-push remote SHA verification,
• one automatic rebase + gate rerun + retry if lease push fails,
• post-push PR-head propagation retry,
• idempotent behavior when local prep HEAD is already on the PR head,
• post-push SHA verification and .local/prep.env generation.

8. Verify handoff artifacts

ls -la .local/prep.md .local/prep.env

9. Output

• Summarize resolved findings and gate results.
• Print exactly: PR is ready for /merge-pr.

Guardrails

• Do not run gh pr merge in this skill.
• Do not delete worktree.
• Do not run plain git rebase --continue from automation; use GIT_EDITOR=true git rebase --continue (or -c core.editor=true).