pr-shepherd

Files (1)

• SKILL.md

SKILL.md (first lines)

# PR shepherd

Start after the first implementation is complete and checked locally. Finish
when the PR has no unresolved review threads, no unanswered comments, and green
CI on the latest head commit, and it is merged or set to auto-merge.

Open the PR first. Review bots and teammates comment while the rest of the work
runs, so an early PR gets more feedback in each round.

## 1. Open the PR

1. Make sure the branch is committed with `git commit -s` and that commits are
   signed (see [`AGENTS.md`](../../../AGENTS.md)). Add a changeset if the change
   touches the published `eve` package.
2. Run the fast checks from `AGENTS.md`: `pnpm fmt`, `pnpm lint`,
   `pnpm typecheck`, plus the narrowest relevant unit tests.
3. Push the branch, then open the PR. Use the
   [`gh-pr-description`](../gh-pr-description/SKILL.md) skill for the body and
   pass it with `--body-file`. Open it ready for review, not as a draft, unless
   the user asks for a draft.
4. Record the PR number. Every later step uses it.

If a PR already exists for the branch (`gh pr view --json number,url`), reuse it.

## 2. Fresh-context review

Spawn one reviewer subagent with no conversation history. Give it the PR number
and the branch, not your reasoning. A fresh reviewer catches what the author
explains away. Use a prompt like this one:

> Review PR #<n> in this repository (`gh pr view <n>`, `gh pr diff <n>`). Read
> `AGENTS.md` first and apply its coding, security, testing, docs, and changeset
> rules. Read surrounding code as needed to verify behavior. Do not edit files.
> Report findings ordered by severity (critical, important, minor). For each
> finding, give the file and line, the concrete failure or risk, and a suggested
> fix. Say plainly when you find nothing critical.

While the reviewer runs, you can already collect PR comments (step 3).

Triage the findings yourself. Verify each one against the code before you act.

- Fix: correctness bugs, races, security or data-loss risks, broken public
  behavior or docs, missing tests for changed behavior, a missing changeset,
  and invariant violations.
- Skip: style nits, speculative refactors, and scope creep. Mention notable
  skipped items to the user in the final report.

## 3. Address PR comments

Collect all feedback.

Unresolved inline review threads, with the IDs you need to reply and resolve:

```sh
gh api graphql -F owner='{owner}' -F repo='{repo}' -F number=<n> -f query='
query($owner: String!, $repo: String!, $number: Int!) {
  repository(owner: $owner, name: $repo) {
    pullRequest(number: $number) {
      reviewThreads(first: 100) {
        nodes {
          id isResolved isOutdated path line
          comments(first: 50) { nodes { author { login } body url } }
        }
      }
    }
  }
}' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved | not)'
```

Top-level comments and review summaries (these cannot be resolved):

```sh
gh pr view <n> --json comments,reviews \
  --jq '.comments[], .reviews[] | select(.body != "") | {author: .author.login, body}'
```

Expect two review bots:

- `roboeve[bot]` reviews once, on the commit that opened the PR, usually within
  2–15 minutes. It does not review later pushes.
- Vercel Agent Review (`vercel[bot]`) runs as a check on every push and can post
  new threads on later commits. It re-checks its own threads after a fix and
  resolves them itself, so skip threads it already resolved.

Ignore informational bot posts such as Vercel deployment and bundle analysis
comments, unless they report a problem this PR caused.

For each thread, decide: fix, decline with a reason, or defer to a follow-up.
Apply the same triage bar as step 2. Bot suggestions get the same scrutiny as
human ones; confirm the problem is real before you change code. If a comment
needs a product or design decision only the user can make, ask the user.

## 4. Commit, push, reply, resolve

1. Combine the fixes from steps 2 and 3. Rerun the fast checks and the
   narrowest tests that cover the fixes.
2. Commit with `git commit -s` and push. Add new commits instead of amending or
   force-pushing, so reply SHAs stay valid. PRs are squash-merged and `main`
   does not require branches to be up to date, so do not rebase only to catch
   up. If `gh pr view <n> --json mergeable` reports `CONFLICTING`, merge
   `origin/main` into the branch with `git merge --signoff origin/main`. Rebase
   or force-push only when the user asks or to repair signing or DCO.
3. If the fixes changed behavior that the PR body describes, update the body
   with `gh-pr-description`.
4. Reply in each thread after the fix is on the remote. Keep replies short and
   specific, in the style already used on eve PRs:
   - `Fixed in <sha>. <What changed, in one or two sentences.>`
   - `Not changing this: <reason grounded in the code or a repo rule>.`
   - `Agreed, this is a real gap. Tracking it in a follow-up: <scope>.`

   Reply by thread ID. The REST replies endpoint accepts only a thread's first
   comment, so it fails on later rounds.

   ```sh
   gh api graphql -f id='<thread id>' -f body='Fixed in abc1234. ...' -f query='
   mutation($id: ID!, $body: String!) { addPullRequestReviewThreadReply(input: { pullRequestReviewThreadId: $id, body: $body }) { comment { url } } }'
   ```

5. Resolve threads that are fixed and pushed. Also resolve bot threads that

From vercel/eve, Apache-2.0.

More from vercel/eve