shepherd-pr

Review PR

Autonomously review PR comments and build status, resolving what can be done with high confidence (>=80%) and flagging the rest for human review.

Workflow

Note: this repository requires that you be using node 24. Use nvm to switch to node 24 before running any commands:

nvm use 24

1. Gather context

# Get PR number for current branch
gh pr view --json number,headRefName,url

# Get review threads with resolution status
gh api graphql -f query='
  query($owner: String!, $repo: String!, $number: Int!) {
    repository(owner: $owner, name: $repo) {
      pullRequest(number: $number) {
        reviewThreads(first: 100) {
          nodes {
            id
            isResolved
            comments(first: 50) {
              nodes {
                body
                path
                line
                author { login }
                createdAt
                databaseId
              }
            }
          }
        }
      }
    }
  }
'

Filter to unresolved threads only.

2. Triage each unresolved comment

Read the referenced code and investigate. Classify into:

A. False positive / already resolved — The issue no longer exists in current code.

• Reply explaining why, citing specific code or commit.

B. Trivial fix (>=80% confidence) — Obvious, mechanical fix. No design decisions or matters of opinion. Examples: typos, missing null checks, wrong variable names, off-by-one, missing imports.

• Make the fix.
• Reply describing what was changed.
• Resolve the thread.

C. Needs human input (<80% confidence) — Design question, significant refactor, or ambiguous fix.

• Do NOT resolve.
• Add to end-of-session summary.

3. Reply and resolve threads

Reply to a comment:

gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies \
  -f body="<your reply>"

Resolve a thread:

gh api graphql -f query='
  mutation($threadId: ID!) {
    resolveReviewThread(input: {threadId: $threadId}) {
      thread { isResolved }
    }
  }
' -f threadId="$THREAD_ID"

Always push fixes, then reply, then resolve related threads (in that order).

4. Check build status

gh pr checks --json name,status,conclusion

Investigate failures by category:

Lint errors — Run pnpm lint-current. Fix if mechanical (formatting, import order, unused vars). Flag if the lint rule itself is questionable.

Type errors — Run pnpm typecheck from repo root. Fix straightforward type mismatches. Flag if fix requires architectural decisions.

Unit test failures — Run pnpm test run in relevant workspace. Flag if failure reveals actual bug or design concern.

E2E snapshot failures — Determine whether the PR's code changes should cause visual differences:

• If yes (UI changes, style updates): add the update-snapshots label to trigger the automated update workflow:

  gh pr edit --add-label "update-snapshots"

• If no: flag as unintended regression for human review.

Mysterious/unexpected failures — Do not attempt to fix. Flag for human review with error output.

5. Commit and push fixes

git add <specific files>
git commit -m "Address PR review feedback

- <summary of changes>"
git push

Stage specific files only. Never force push. Never use git add -A.

6. End-of-session summary

Always end with:

## PR review summary

### Resolved
- <thread>: <what was done>

### Fixed
- <description of fix>

### Needs your input
- <thread>: <why it needs human judgment>

### Build status
- <status of each check, any actions taken>

Omit empty sections.

Guidelines

• Conservative threshold: only act when >=80% confident the fix is correct and uncontroversial.
• Never resolve comments raising design questions or matters of opinion.
• Never resolve without replying first.
• Read actual code before concluding a comment is a false positive.
• Verify fixes don't break types (pnpm typecheck) or lint (pnpm lint-current).
• Do not modify test expectations.