pr-watch

Files (2)

• SKILL.md
• fetch_comments.py · scripts/

SKILL.md (first lines)

# PR Watch

Drive a GitHub PR to a fully green, fully addressed state — or exit with a
concrete blocker and a precise list of decisions only the user can make.

This skill has two phases:

- **Phase A — Get checks green.** Repair the CI/status checks for the latest
  head SHA.
- **Phase B — Work the review conversations.** Triage every unresolved review
  thread. Auto-resolve the mechanical and low-risk ones; surface the rest as
  explicit decisions for the user.

Run **Phase A first**, then Phase B. Phase B fixes add commits, so after Phase B
pushes anything, return to Phase A on the new head SHA until both phases are
clean against the same SHA. Stop and escalate the moment a blocker or a genuine
user decision appears — do not keep looping.

A PR can have no checks at all (path-filtered changes, repos without CI, or a
review-comment-only invocation). Treat "no expected checks for the latest SHA"
as a **green Phase A**, not a blocker, and continue to Phase B — otherwise the
skill cannot do the review-comment work it was invoked for. Only escalate a
missing check when a check is genuinely *expected* and absent (see Step 4).

## Scope

- GitHub PRs only. If the repo is GitLab, stop and say so.
- Always work against the latest PR head SHA, not old commits.
- Phase A is about CI/status checks. Phase B is about review threads, review
  bodies, and conversation comments.
- This skill **does** make GitHub writes in Phase B (replies and thread
  resolution) — but only for threads it can address without a real decision.
  Anything that needs the user's judgment is escalated, never silently resolved.

## Inputs

- **PR number** (optional): If not provided, detect the PR for the current branch.
- **Max iterations**: default `5`.

## Worktree safety — run before any commit

Both phases make commits on an existing PR (Phase A fixes, Phase B B3/B5
follow-ups). Before the *first* commit in either phase, check the worktree so a
review-fix commit never sweeps in unrelated local work:

```bash
git status --short --branch
```

If there are uncommitted or untracked files, inspect enough diff/file context to
classify each as **related** to the PR-watch fix or **unrelated**.

If unrelated changes exist, stop and ask the user what to do with them before
staging, committing, stashing, or deleting anything. Offer concrete choices:

- leave them untouched and only stage the PR-watch fix files
- include specific files in this PR
- stash specific files
- commit them separately

Never use `git add -A`, `git add .`, `git commit -a`, `git stash`, `git
restore`, or `rm` in a mixed worktree without explicit user direction. Stage
only the specific files your fix changed (`git add <path> …`) so every commit
this skill makes contains exactly the review fix and nothing else.

## Phase A — Get checks green

### 1. Identify the PR

If no PR number is provided, detect it from the current branch:

```bash
gh pr view --json number,headRefName,headRefOid,url,isDraft
```

If needed, switch to the PR branch before making changes.

Stop early if:

- `gh` is not authenticated
- there is no PR for the branch
- the repo is not hosted on GitHub

### 2. Track the latest head SHA

Always work against the current PR head SHA:

```bash
PR_JSON=$(gh pr view "$PR_NUMBER" --json number,headRefName,headRefOid,url)
HEAD_SHA=$(echo "$PR_JSON" | jq -r .headRefOid)
PR_URL=$(echo "$PR_JSON" | jq -r .url)
```

Ignore failing checks from older SHAs. After every push, refresh `HEAD_SHA` and
restart the inspection loop.

### 3. Inventory checks for that SHA

Fetch both GitHub check runs and legacy commit status contexts:

```bash
gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/check-runs?per_page=100"
gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/status"
```

For a compact PR-level view, this GraphQL payload is useful:

```bash
gh api graphql -f query='
query($owner:String!, $repo:String!, $pr:Int!) {
  repository(owner:$owner, name:$repo) {
    pullRequest(number:$pr) {
      headRefOid
      url
      statusCheckRollup {
        contexts(first:100) {
          nodes {
            __typename
            ... on CheckRun { name status conclusion detailsUrl workflowName }

From Kotivskyi/skills, MIT.

More from Kotivskyi/skills