Prepare PR

Overview

Prepare a PR head branch for merge with review fixes, green gates, and deterministic merge handoff artifacts.

Inputs

Ask for PR number or URL.
If missing, use
```
.local/pr-meta.env
```
from the PR worktree if present.
If ambiguous, ask.

Safety

Never push to
```
main
```
or
```
origin/main
```
. Push only to the PR head branch.
Never run
```
git push
```
without explicit remote and branch. Do not run bare
```
git push
```
.
Do not run gateway stop commands. Do not kill processes. Do not touch port 18792.
Do not run
```
git clean -fdx
```
.
Do not run
```
git add -A
```
or
```
git add .
```
.

Execution Rule

Execute the workflow. Do not stop after printing the TODO checklist.
If delegating, require the delegate to run commands and capture outputs.

Completion Criteria

Rebase PR commits onto
```
origin/main
```
.
Fix all BLOCKER and IMPORTANT items from
```
.local/review.md
```
.
Commit prep changes with required subject format.
Run required gates and pass (
```
pnpm test
```
may be skipped only for high-confidence docs-only changes).
Push the updated HEAD back to the PR head branch.
Write
```
.local/prep.md
```
and
```
.local/prep.env
```
.
Output exactly:
```
PR is ready for /mergepr
```
.

First: Create a TODO Checklist

Create a checklist of all prep steps, print it, then continue and execute the commands.

Setup: Use a Worktree

Use an isolated worktree for all prep work.

repo_root=$(git rev-parse --show-toplevel)
cd "$repo_root"
gh auth status

WORKTREE_DIR=".worktrees/pr-<PR>"
if [ ! -d "$WORKTREE_DIR" ]; then
  git fetch origin main
  git worktree add "$WORKTREE_DIR" -b temp/pr-<PR> origin/main
fi
cd "$WORKTREE_DIR"
mkdir -p .local

Run all commands inside the worktree directory.

Load Review Artifacts (Mandatory)

if [ ! -f .local/review.md ]; then
  echo "Missing .local/review.md. Run /review-pr first and save findings."
  exit 1
fi

if [ ! -f .local/pr-meta.env ]; then
  echo "Missing .local/pr-meta.env. Run /review-pr first and save metadata."
  exit 1
fi

sed -n '1,220p' .local/review.md
source .local/pr-meta.env

Steps

Identify PR meta with one API call

pr_meta_json=$(gh pr view <PR> --json number,title,author,headRefName,headRefOid,baseRefName,headRepository,headRepositoryOwner,body)
printf '%s\n' "$pr_meta_json" | jq '{number,title,author:.author.login,head:.headRefName,headSha:.headRefOid,base:.baseRefName,headRepo:.headRepository.nameWithOwner,headRepoOwner:.headRepositoryOwner.login,headRepoName:.headRepository.name,body}'

pr_number=$(printf '%s\n' "$pr_meta_json" | jq -r .number)
contrib=$(printf '%s\n' "$pr_meta_json" | jq -r .author.login)
head=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefName)
pr_head_sha_before=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefOid)
head_owner=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepositoryOwner.login // empty')
head_repo_name=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepository.name // empty')
head_repo_url=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepository.url // empty')

if [ -n "${PR_HEAD:-}" ] && [ "$head" != "$PR_HEAD" ]; then
  echo "ERROR: PR head branch changed from $PR_HEAD to $head. Re-run /review-pr."
  exit 1
fi

Fetch PR head and rebase on latest
```
origin/main
```

git fetch origin pull/<PR>/head:pr-<PR> --force
git checkout -B pr-<PR>-prep pr-<PR>
git fetch origin main
git rebase origin/main

If conflicts happen:

Resolve each conflicted file.
Run
```
git add <resolved_file>
```
for each file.
Run
```
git rebase --continue
```
.

If the rebase gets confusing or you resolve conflicts 3 or more times, stop and report.

Fix issues from
```
.local/review.md
```

Fix all BLOCKER and IMPORTANT items.
NITs are optional.
Keep scope tight.

Keep a running log in

.local/prep.md

List which review items you fixed.
List which files you touched.
Note behavior changes.

Optional quick feedback tests before full gates

Targeted tests are optional quick feedback, not a substitute for full gates.

If running targeted tests in a fresh worktree:

if [ ! -x node_modules/.bin/vitest ]; then
  pnpm install --frozen-lockfile
fi

Commit prep fixes with required subject format

Use

scripts/committer

with explicit file paths.

Required subject format:

fix: <summary> (openclaw#<PR>) thanks @<author>

commit_msg="fix: <summary> (openclaw#$pr_number) thanks @$contrib"
scripts/committer "$commit_msg" <changed file 1> <changed file 2> ...

If there are no local changes, do not create a no-op commit.

Post-commit validation (mandatory):

subject=$(git log -1 --pretty=%s)
echo "$subject" | rg -q "openclaw#$pr_number" || { echo "ERROR: commit subject missing openclaw#$pr_number"; exit 1; }
echo "$subject" | rg -q "thanks @$contrib" || { echo "ERROR: commit subject missing thanks @$contrib"; exit 1; }

Decide verification mode and run required gates before pushing

If you are highly confident the change is docs-only, you may skip

pnpm test

High-confidence docs-only criteria (all must be true):

Every changed file is documentation-only (

docs/**

README*.md

CHANGELOG.md

*.md

*.mdx

mintlify.json

docs.json

No code, runtime, test, dependency, or build config files changed (
```
src/**
```
,
```
extensions/**
```
,
```
apps/**
```
,
```
package.json
```
, lockfiles, TS/JS config, test files, scripts).
```
.local/review.md
```
does not call for non-doc behavior fixes.

Suggested check:

changed_files=$(git diff --name-only origin/main...HEAD)
non_docs=$(printf "%s\n" "$changed_files" | grep -Ev '^(docs/|README.*\.md$|CHANGELOG\.md$|.*\.md$|.*\.mdx$|mintlify\.json$|docs\.json$)' || true)

docs_only=false
if [ -n "$changed_files" ] && [ -z "$non_docs" ]; then
  docs_only=true
fi

echo "docs_only=$docs_only"

Bootstrap dependencies in a fresh worktree before gates:

if [ ! -d node_modules ]; then
  pnpm install --frozen-lockfile
fi

Run required gates:

pnpm build
pnpm check

if [ "$docs_only" = "true" ]; then
  echo "Docs-only change detected with high confidence; skipping pnpm test." | tee -a .local/prep.md
else
  pnpm test
fi

Require all required gates to pass. If something fails, fix, commit, and rerun. Allow at most 3 fix-and-rerun cycles.

Push safely to the PR head branch

Build

prhead

from owner/name first, then validate remote branch SHA before push.

if [ -n "$head_owner" ] && [ -n "$head_repo_name" ]; then
  head_repo_push_url="https://github.com/$head_owner/$head_repo_name.git"
elif [ -n "$head_repo_url" ] && [ "$head_repo_url" != "null" ]; then
  case "$head_repo_url" in
    *.git) head_repo_push_url="$head_repo_url" ;;
    *) head_repo_push_url="$head_repo_url.git" ;;
  esac
else
  echo "ERROR: unable to determine PR head repo push URL"
  exit 1
fi

git remote add prhead "$head_repo_push_url" 2>/dev/null || git remote set-url prhead "$head_repo_push_url"

echo "Pushing to branch: $head"
if [ "$head" = "main" ] || [ "$head" = "master" ]; then
  echo "ERROR: head branch is main/master. This is wrong. Stopping."
  exit 1
fi

remote_sha=$(git ls-remote prhead "refs/heads/$head" | awk '{print $1}')
if [ -z "$remote_sha" ]; then
  echo "ERROR: remote branch refs/heads/$head not found on prhead"
  exit 1
fi
if [ "$remote_sha" != "$pr_head_sha_before" ]; then
  echo "ERROR: expected remote SHA $pr_head_sha_before, got $remote_sha. Re-fetch metadata and rebase first."
  exit 1
fi

git push --force-with-lease=refs/heads/$head:$pr_head_sha_before prhead HEAD:$head || push_failed=1

If lease push fails because head moved, perform one automatic retry:

if [ "${push_failed:-0}" = "1" ]; then
  echo "Lease push failed, retrying once with fresh PR head..."

  pr_head_sha_before=$(gh pr view <PR> --json headRefOid --jq .headRefOid)
  git fetch origin pull/<PR>/head:pr-<PR>-latest --force
  git rebase pr-<PR>-latest

  pnpm build
  pnpm check
  if [ "$docs_only" != "true" ]; then
    pnpm test
  fi

  git push --force-with-lease=refs/heads/$head:$pr_head_sha_before prhead HEAD:$head
fi

Verify PR head and base relation (Mandatory)

prep_head_sha=$(git rev-parse HEAD)
pr_head_sha_after=$(gh pr view <PR> --json headRefOid --jq .headRefOid)

if [ "$prep_head_sha" != "$pr_head_sha_after" ]; then
  echo "ERROR: pushed head SHA does not match PR head SHA."
  exit 1
fi

git fetch origin main
git fetch origin pull/<PR>/head:pr-<PR>-verify --force
git merge-base --is-ancestor origin/main pr-<PR>-verify && echo "PR is up to date with main" || (echo "ERROR: PR is still behind main, rebase again" && exit 1)
git branch -D pr-<PR>-verify 2>/dev/null || true

Write prep summary artifacts (Mandatory)

Write

.local/prep.md

and

.local/prep.env

for merge handoff.

contrib_id=$(gh api users/$contrib --jq .id)
coauthor_email="${contrib_id}+${contrib}@users.noreply.github.com"

cat > .local/prep.env <<EOF_ENV
PR_NUMBER=$pr_number
PR_AUTHOR=$contrib
PR_HEAD=$head
PR_HEAD_SHA_BEFORE=$pr_head_sha_before
PREP_HEAD_SHA=$prep_head_sha
COAUTHOR_EMAIL=$coauthor_email
EOF_ENV

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

Output

Include a diff stat summary:

git diff --stat origin/main..HEAD
git diff --shortstat origin/main..HEAD

Report totals: X files changed, Y insertions(+), Z deletions(-).

If gates passed and push succeeded, print exactly:

PR is ready for /mergepr

Otherwise, list remaining failures and stop.

Guardrails

Worktree only.
Do not delete the worktree on success.
```
/mergepr
```
may reuse it.
Do not run
```
gh pr merge
```
.
Never push to main. Only push to the PR head branch.
Run and pass all required gates before pushing.
```
pnpm test
```
may be skipped only for high-confidence docs-only changes, and the skip must be explicitly recorded in
```
.local/prep.md
```
.

prepare-pr

NPX Install

Tags

SKILL.md Content