home / skills / openclaw / openclaw / prepare-pr

prepare-pr skill

safe

/.agents/skills/prepare-pr

This skill prepares a PR head for merge by validating findings, updating changelog, and safely gating and pushing to the PR head.

npx playbooks add skill openclaw/openclaw --skill prepare-pr

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.7 KB

---
name: prepare-pr
description: Script-first PR preparation with structured findings resolution, deterministic push safety, and explicit gate execution.
---

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

```sh
scripts/pr-prepare init <PR>
```

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:

```sh
scripts/pr-prepare run <PR>
```

## Steps

1. Setup and artifacts

```sh
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 required findings

List required items:

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

Fix all required findings. Keep scope tight.

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

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

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

Use explicit file list:

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

5. Run gates

```sh
scripts/pr-prepare gates <PR>
```

6. Push safely to PR head

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

7. Verify handoff artifacts

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

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

Overview

This skill prepares a pull request head branch for merge using a script-first, deterministic workflow that enforces structured findings resolution and safe push behavior. It ensures required findings are resolved, scoped commits are created, gates are executed, and the PR head is pushed with lease and verification safeguards. The output is a clear handoff confirming the PR is ready for merge.

How this skill works

The skill initializes a PR prep session, validates required artifacts, and enumerates BLOCKER and IMPORTANT findings from the structured review file. You resolve findings, update changelog/docs, and create focused commits via the committer wrapper. Gates run through the wrapper, and the push step performs pre-push SHA checks, a lease-safe force-push path with an automated rebase+retry, and post-push propagation verification, producing local handoff artifacts.

When to use it

After /review-pr has produced .local/review.json for a PR
When you must resolve all BLOCKER and IMPORTANT review findings before merging
When you need deterministic, lease-safe pushes to a PR head branch
When changelog or docs updates are required as part of PR preparation
When you want an auditable handoff and explicit gate execution before merge

Best practices

Run scripts/pr-prepare init <PR> from the repository root or PR worktree to gather artifacts
Keep fix commits tightly scoped and use concise, action-oriented commit subjects (no PR numbers/thanks)
Always fix all BLOCKER and IMPORTANT findings listed in .local/review.json before proceeding
Use the provided committer wrapper with an explicit file list to avoid accidental changes
Rely on the wrapper for gates and push; never push directly to main and avoid destructive git clean commands

Example use cases

Prepare a contributor's PR for merge after an AI-assisted review identified critical issues
Enforce a release process that requires changelog entries and docs updates as part of PR prep
Safely force-update a PR head after a targeted rebase while ensuring remote SHA verification
Produce .local/prep.md and .local/prep.env artifacts for CI or release automation handoff
Run a one-shot prep flow with scripts/pr-prepare run <PR> for small, well-scoped fixes

FAQ

What files are mandatory for this workflow?

.local/review.json is mandatory; .local/pr-meta.env and other .local artifacts are used if present.

Will this skill ever push to main?

No. It never pushes to main and only targets the PR head with --force-with-lease against a known SHA.

Can I run this from any directory?

Wrappers are cwd-agnostic but running from the repo root or the PR worktree is recommended.