Skip to content

Commit efe342c

Browse files
steveruizoksteveruizok
authored
feat(skills): add shepherd-pr skill for autonomous PR review (tldraw#8211)
In order to automate routine PR maintenance tasks like resolving review comments and fixing build failures, this PR adds a new Claude Code skill called `shepherd-pr`. The skill autonomously triages unresolved PR review threads into three categories: false positives (already resolved in code), trivial fixes (>=80% confidence mechanical changes), and items needing human input. It also investigates build failures (lint, type errors, test failures, e2e snapshot mismatches) and takes appropriate action for each category. ### Change type - [x] `other` ### Test plan - [ ] Invoke the skill on a PR with review comments and verify it correctly triages and resolves threads - [ ] Invoke the skill on a PR with build failures and verify it correctly diagnoses issues ### Code changes | Section | LOC change | | -------------- | ---------- | | Config/tooling | +161 / -0 | <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Adds documentation/config for a new Claude skill but does not change runtime application code or production behavior. > > **Overview** > Introduces a new Claude Code skill definition `shepherd-pr` (`.claude/skills/shepherd-pr/SKILL.md`) to guide autonomous PR maintenance. > > The skill documents a workflow to fetch PR review threads via `gh` GraphQL, triage unresolved comments (false positive vs trivial fix vs needs human input), resolve threads with replies, and diagnose common CI failures (lint/type/test/snapshot) with conservative guardrails and a required end-of-session summary. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 410c930. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY -->
1 parent 84ac7a3 commit efe342c

1 file changed

Lines changed: 161 additions & 0 deletions

File tree

‎.claude/skills/shepherd-pr/SKILL.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
name: shepherd-pr
3+
description: Keep an eye on this PR. Review and resolve pull request comments and fix build failures autonomously. Use when asked to review PR feedback, address reviewer comments, fix CI failures, resolve PR threads, or handle PR maintenance tasks like "review PR comments", "fix the build", "address PR feedback", "clean up PR", or "resolve comments". Handles comment triage (resolve false positives, fix trivial issues, flag complex ones), build/lint/type errors, and e2e snapshot updates.
4+
---
5+
6+
# Review PR
7+
8+
Autonomously review PR comments and build status, resolving what can be done with high confidence (>=80%) and flagging the rest for human review.
9+
10+
## Workflow
11+
12+
Note: this repository requires that you be using node 24. Use `nvm` to switch to node 24 before running any commands:
13+
14+
```bash
15+
nvm use 24
16+
```
17+
18+
### 1. Gather context
19+
20+
```bash
21+
# Get PR number for current branch
22+
gh pr view --json number,headRefName,url
23+
24+
# Get review threads with resolution status
25+
gh api graphql -f query='
26+
query($owner: String!, $repo: String!, $number: Int!) {
27+
repository(owner: $owner, name: $repo) {
28+
pullRequest(number: $number) {
29+
reviewThreads(first: 100) {
30+
nodes {
31+
id
32+
isResolved
33+
comments(first: 50) {
34+
nodes {
35+
body
36+
path
37+
line
38+
author { login }
39+
createdAt
40+
databaseId
41+
}
42+
}
43+
}
44+
}
45+
}
46+
}
47+
}
48+
'
49+
```
50+
51+
Filter to unresolved threads only.
52+
53+
### 2. Triage each unresolved comment
54+
55+
Read the referenced code and investigate. Classify into:
56+
57+
**A. False positive / already resolved** — The issue no longer exists in current code.
58+
59+
- Reply explaining why, citing specific code or commit.
60+
- Resolve the thread.
61+
62+
**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.
63+
64+
- Make the fix.
65+
- Reply describing what was changed.
66+
- Resolve the thread.
67+
68+
**C. Needs human input (<80% confidence)** — Design question, significant refactor, or ambiguous fix.
69+
70+
- Do NOT resolve.
71+
- Add to end-of-session summary.
72+
73+
### 3. Reply and resolve threads
74+
75+
Reply to a comment:
76+
77+
```bash
78+
gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies \
79+
-f body="<your reply>"
80+
```
81+
82+
Resolve a thread:
83+
84+
```bash
85+
gh api graphql -f query='
86+
mutation($threadId: ID!) {
87+
resolveReviewThread(input: {threadId: $threadId}) {
88+
thread { isResolved }
89+
}
90+
}
91+
' -f threadId="$THREAD_ID"
92+
```
93+
94+
Always push fixes, then reply, then resolve related threads (in that order).
95+
96+
### 4. Check build status
97+
98+
```bash
99+
gh pr checks --json name,status,conclusion
100+
```
101+
102+
Investigate failures by category:
103+
104+
**Lint errors** — Run `yarn lint-current`. Fix if mechanical (formatting, import order, unused vars). Flag if the lint rule itself is questionable.
105+
106+
**Type errors** — Run `yarn typecheck` from repo root. Fix straightforward type mismatches. Flag if fix requires architectural decisions.
107+
108+
**Unit test failures** — Run `yarn test run` in relevant workspace. Fix if test expectation is clearly outdated due to intentional code changes. Flag if failure reveals actual bug or design concern.
109+
110+
**E2E snapshot failures** — Determine whether the PR's code changes _should_ cause visual differences:
111+
112+
- If yes (UI changes, style updates): add the `update-snapshots` label to trigger the automated update workflow:
113+
```bash
114+
gh pr edit --add-label "update-snapshots"
115+
```
116+
- If no: flag as unintended regression for human review.
117+
118+
**Mysterious/unexpected failures** — Do not attempt to fix. Flag for human review with error output.
119+
120+
### 5. Commit and push fixes
121+
122+
```bash
123+
git add <specific files>
124+
git commit -m "Address PR review feedback
125+
126+
- <summary of changes>"
127+
git push
128+
```
129+
130+
Stage specific files only. Never force push. Never use `git add -A`.
131+
132+
### 6. End-of-session summary
133+
134+
Always end with:
135+
136+
```
137+
## PR review summary
138+
139+
### Resolved
140+
- <thread>: <what was done>
141+
142+
### Fixed
143+
- <description of fix>
144+
145+
### Needs your input
146+
- <thread>: <why it needs human judgment>
147+
148+
### Build status
149+
- <status of each check, any actions taken>
150+
```
151+
152+
Omit empty sections.
153+
154+
## Guidelines
155+
156+
- Conservative threshold: only act when >=80% confident the fix is correct and uncontroversial.
157+
- Never resolve comments raising design questions or matters of opinion.
158+
- Never resolve without replying first.
159+
- Read actual code before concluding a comment is a false positive.
160+
- Verify fixes don't break types (`yarn typecheck`) or lint (`yarn lint-current`).
161+
- Do not modify test expectations unless change is clearly intentional.

0 commit comments

Comments
 (0)