pr-worktree

name	pr-worktree
description	Use when any GitHub PR workflow needs to checkout, inspect, review, test, or modify a PR locally without disturbing the current workspace; drive isolated review/fix worktree preparation, status checks, and safe cleanup through the bundled deterministic helper

PR Worktree

Use the bundled script as the source of truth. It resolves PR metadata, selects the base remote, fetches current base/PR refs, chooses an ignored or sibling path, creates or safely reuses the worktree, and returns a machine-readable manifest. Do not make the LLM reconstruct that lifecycle with ad hoc shell commands.

Non-negotiables

• Never run gh pr checkout or switch branches in the user's current workspace.
• Use review mode for read/test/review work and fix mode only when the user authorized commits and pushes.
• Refuse to reuse a path with tracked changes, or a foreign or unregistered path. Untracked files do not make a worktree dirty; report and preserve them without stashing, cleaning, or overwriting them.
• Review mode must be detached at the fetched PR head. Fix mode must be attached to the PR head branch with upstream information.
• Run all subsequent commands with workdir set to the manifest's worktree path.
• Keep worktrees after triage/review for follow-up. Clean up only when the user asks.
• Never force-push or force-remove through this skill.

Prepare

From any path inside the base repository:

python3 <this-skill>/scripts/pr_worktree.py prepare <PR-number-or-URL> --repo <OWNER/REPO> --mode review --format markdown

For maintainer edits:

python3 <this-skill>/scripts/pr_worktree.py prepare <PR-number-or-URL> --repo <OWNER/REPO> --mode fix --format markdown

Omit --repo when the current GitHub repository context is unambiguous. Useful overrides:

• --repo-dir <path> when invoking outside the base repository root;
• --path <path> when an established worktree location is required;
• --remote <name> when remote URL auto-detection cannot select the base repository remote;
• --format json for orchestration.

Read the manifest once. It provides:

• PR/base/head repositories and refs;
• selected remote and worktree path;
• branch/detached/upstream/tracked-clean state and separately reported untracked entries;
• the checked-out head's relation to PR metadata (match, local ahead, behind, or diverged);
• ready-to-run diff/status/push commands.

In review mode, the helper refuses a stale, behind, or diverged checkout. In fix mode it preserves a branch that is locally ahead of GitHub metadata, but refuses behind or diverged state so existing maintainer commits are never reset implicitly. For cross-repository fixes, treat maintainerCanModify: false as a warning that the eventual push may be rejected; do not change remotes or invent a replacement branch without user direction.

Work from the manifest

Set the tool workdir to the returned path. Use the returned base tracking ref for the three-dot diff. Do not fetch or rediscover metadata again unless the PR head changes while the task is active.

Before edits in fix mode, confirm:

git branch --show-current
git status --short --branch
git remote -v

The branch must be attached and tracked-clean. Untracked files may remain and must not be altered.

Status

Use the helper instead of manually combining branch/head/dirty checks:

python3 <this-skill>/scripts/pr_worktree.py status --path <worktree-path> --format markdown

Cleanup

Only when the user requests cleanup:

python3 <this-skill>/scripts/pr_worktree.py cleanup --repo-dir <base-repository> --path <worktree-path> --format markdown

Cleanup refuses tracked changes, untracked files, attached branches without upstreams, and branches with unpushed commits. Prepare/reuse ignores untracked files, but cleanup preserves them rather than deleting them. Report the refusal; do not bypass it with --force or manual deletion.

Failure handling

• Tracked-dirty reused path: preserve it and report the status preview. Untracked-only paths are reusable; leave those files untouched.
• Foreign/unregistered path: choose a new explicit path or ask the user; never delete it.
• PR ref fetch fails: verify repository/remote/permissions, then report the exact command error.
• Fix checkout is detached or branch is already checked out elsewhere: stop; do not force checkout.
• Contributor fork is unwritable: report that direct maintainer push is unavailable and request direction.
• Helper unavailable: only then use a manual worktree fallback, preserving every non-negotiable above.