stale-pr-revival

Files (2)

• SKILL.md
• bot-dependency-prs.md · references/

SKILL.md (first lines)

# stale-pr-revival

## Overview

An open PR that sat for weeks is rarely blocked by its own diff. It is blocked
by everything around it: a base that moved, a review that asked for one more
thing in its body rather than in a thread, conventions that changed since it
was opened, and a merge gate nobody re-ran. Reviving it is a different job
from writing it — the goal is to bring it current, apply its reviews, and
ready the merge **without rewriting its history**.

This skill is that procedure for any open PR, yours or someone else's, plus
two variants: bot dependency PRs
([`references/bot-dependency-prs.md`](references/bot-dependency-prs.md)) and
moving a PR to a different base branch (Step 9).

**Core principle:** the instruction to revive a PR covers pushing to its
branch — it does not cover rewriting that branch's history or deleting it.

## When to Use

- The user asks to "fix", finish, or update an existing open PR — often an
  approved one that is now conflicting and many commits behind its base.
- Several old dependabot / renovate version-bump PRs need re-review, revival,
  or closing as superseded.
- A PR has to move to a different base branch (for example `dev` → `main`).

For many stale PRs across several repositories, run this procedure once per
repository — one delegated worker per repository, each following the steps
below — rather than interleaving them in one context. This holds for a
cross-repo PR set serving one issue too: give each repo's PR its own worker
and keep the cross-repo contract check (names one side writes, the other
reads) and the deploy order for the orchestrator. One worker carrying three
large revivals runs out of iterations mid-way and leaves an unpushed merge
plus uncommitted fixes for someone else to reconstruct.

Order a batch by the stale clock: a PR carrying a stale-bot label closes
(and on many repos loses its head branch) a fixed number of days after the
label, and any push or comment resets it — revive or at least comment on
those first.

Every status line, briefing, and final report goes out in the user's working
language from their rule set — long tool chains (merge, tests, gate retries)
are exactly where replies drift into English and the user has to ask again.

## The Iron Law

- **Merge the base in; never rebase, never force-push.** The branch may belong
  to someone else, and its review history anchors on its commits.
- **Never delete a branch you did not create.** Merge without
  `--delete-branch` when the head belongs to another author.
- **No merge without the briefing.** Merging goes through
  [`merge-briefing`](../merge-briefing/SKILL.md), one PR per approval.

## Process

### Step 1: Read every review surface before touching code

Requested changes usually live in review **bodies**, not in inline threads.
Read all three surfaces:

```bash
gh api repos/<owner>/<repo>/pulls/<N>/reviews --paginate     # review bodies
gh api graphql -f query='<reviewThreads query for PR N>'     # inline threads
gh pr view <N> --repo <owner>/<repo> --json body,baseRefName,headRefName,isCrossRepository
```

List each finding with its decoration. An approval that still says "update
the base first" is a requested change, not a formality.

Then resolve where the head branch lives and whether you can write to it —
for a fork PR it is not on `origin`:

```bash
gh pr view <N> --repo <owner>/<repo> \
  --json isCrossRepository,headRepositoryOwner,headRepository,headRefName,maintainerCanModify
gh api repos/<head-owner>/<head-repo> --jq .permissions.push
```

The head is writable when `.permissions.push` is `true`, or for a
cross-repository PR when `maintainerCanModify` is `true` and you maintain the
base. Otherwise stop and report: never push the branch to the base repository
instead. Name the local remotes from `git remote -v`: `<head-remote>` is the
one whose URL is the head repository (add it with `git remote add` when none
is), `<base-remote>` the one for `<owner>/<repo>`; for a same-repository PR
both are usually `origin`.

Done when: every review body and every thread is listed as a finding with its
decoration, the head/base branch names are known, and the head repository,
its write access, and `<head-remote>` / `<base-remote>` are recorded — or the
revival stopped because the head is not writable.

### Step 2: Check for parallel work on the same defect

Before reviving a fix, search for an existing PR or umbrella issue on the same
mechanism — `gh search issues` and `gh search prs` with the mechanism's
keywords (function name, config key), plus `git worktree list` for a local
attempt. A stalled PR is often one of two parallel fixes for the same defect.

Include **merged** PRs, not only open ones (`gh pr list --state merged
--search "<file or mechanism>"`, `git log <base-remote>/<deploy-branch> -- <files
the PR touches>`): the goal often shipped through a different PR while this one
waited. Then read the deploy branch's version of the touched files and compare
it to the PR's intent line by line — a flag the PR adds may now be the
operator's default, so the PR's remaining delta can shrink to a tuning value.

Also check whether the base grew a **house-standard mechanism for the whole
class of change** while the PR waited (a shared operator, builder, or tier
table now used by several siblings: `git grep -l <ClassName> <base-remote>/<base>`).
When it did, narrowing the old diff keeps a one-off path whose original
justification may now be handled by that mechanism (re-read the PR body's
"why not X" against the new code's docstring). Offer the user the choice
before Step 3 — narrow the residual, or rewrite the PR onto the standard on
the same branch (new commits, retitled body, no force-push) — with the
trade-off in one table (path, resource cost per account, precedent count).
A rewrite follows the two closest siblings' wiring rather than inventing
constants, and the change comment names them with file:line.
Re-run the PR's reproduction against the **current** base build and live
vendor before porting anything (a control run: the base binary, the same

From devseunggwan/praxis, MIT.

More from devseunggwan/praxis