Skip to content

Commit b65b868

Browse files
committed
docs(ai): add PR AI review workflow skill
1 parent bd06550 commit b65b868

5 files changed

Lines changed: 131 additions & 0 deletions

File tree

‎.agents/skills/ccusage-development/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,3 +87,5 @@ For package-local work, run the narrower package scripts during iteration when t
8787
## Commit and PR Names
8888

8989
Use the `commit` skill for commit structure, Conventional Commits, scope selection, and detailed commit message requirements.
90+
91+
Use the `pr-ai-review-workflow` skill after opening a PR or pushing follow-up commits so AI and human review comments are requested, inspected, answered, and incorporated through small revertable commits.

‎.agents/skills/commit/SKILL.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ You are an expert git commit architect creating fine-grained, independently reve
2929

3030
**Revertability First**: Each commit must be revertable independently without breaking other functionality. Prefer smaller, granular commits over large groupings. Split by hunks within files, not just entire files.
3131

32+
PR branches are normally squash-merged, so do not compress review work with `git commit --amend` by default. Keep review fixes as small follow-up commits that can be reverted independently. Amend only for unpublished local mistakes or when the user explicitly asks.
33+
3234
## Workflow
3335

3436
1. **Analyse the changes above**: Review the git state already provided
@@ -177,6 +179,7 @@ affecting the service itself.
177179
- Always use **English** for commit messages with **UK English spelling** (e.g. "colour", "organise", "initialise")
178180
- **Never push to main branch directly** - create a PR instead
179181
- When in doubt, prefer smaller commits (can squash later, can't easily split)
182+
- On PR branches, stack small revertable commits instead of amending away review history unless explicitly asked
180183
- Match project's established scope naming and conventions
181184
- Include issue/PR references when applicable
182185
- Each commit must pass: "If I revert this, will it break other features?"
Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
name: pr-ai-review-workflow
3+
description: 'Manage pull request AI review loops with GitHub CLI: request generic AI/code reviewers, wait for bot or human review, inspect comments, reply to inline review comments, apply fixes, push follow-up commits, and request re-review.'
4+
---
5+
6+
# PR AI Review Workflow
7+
8+
Use this after opening a PR or pushing commits to an open PR. Reviewer tools and bot names can change; treat names such as `@coderabbitai` and `@cubic-dev-ai` as current examples, not permanent assumptions.
9+
10+
## Commit Policy
11+
12+
PRs are normally squash-merged. Do not default to `git commit --amend` or force-push just to keep a PR to one commit. Prefer small, independently revertable follow-up commits for review fixes, generated skill updates, and discussion outcomes. Use the `commit` skill for atomic commit structure and messages.
13+
14+
Use amend only when the user explicitly asks, when fixing the immediately previous unpublished commit, or when correcting a local mistake before any reviewer has consumed it.
15+
16+
## Request Review
17+
18+
After creating a PR or pushing a meaningful follow-up commit, check whether reviewers are already running. If not, add a PR conversation comment that mentions the configured reviewers:
19+
20+
```sh
21+
gh pr comment <pr-number-or-url> --body '@coderabbitai review
22+
@cubic-dev-ai review'
23+
```
24+
25+
Prefer repository-local conventions when they exist. If the repo has changed reviewers, use the current reviewer mentions from recent PRs or project docs instead of the examples above.
26+
27+
## Wait and Inspect
28+
29+
Poll for reviews and comments before declaring the PR ready:
30+
31+
```sh
32+
gh pr view <pr-number-or-url> --json url,state,headRefName,comments,reviews,statusCheckRollup
33+
```
34+
35+
List top-level PR conversation comments:
36+
37+
```sh
38+
gh api repos/:owner/:repo/issues/<pr-number>/comments --paginate \
39+
--jq '.[] | {id, user: .user.login, created_at, body}'
40+
```
41+
42+
List inline review comments:
43+
44+
```sh
45+
gh api repos/:owner/:repo/pulls/<pr-number>/comments --paginate \
46+
--jq '.[] | {id, user: .user.login, path, line, original_line, body}'
47+
```
48+
49+
If thread resolution state matters, use GraphQL review threads rather than the flat REST comment list:
50+
51+
```sh
52+
gh api graphql \
53+
-F owner='OWNER' \
54+
-F repo='REPO' \
55+
-F number=<pr-number> \
56+
-f query='
57+
query($owner: String!, $repo: String!, $number: Int!) {
58+
repository(owner: $owner, name: $repo) {
59+
pullRequest(number: $number) {
60+
reviewThreads(first: 100) {
61+
nodes {
62+
id
63+
isResolved
64+
comments(first: 20) {
65+
nodes {
66+
id
67+
databaseId
68+
author { login }
69+
path
70+
body
71+
}
72+
}
73+
}
74+
}
75+
}
76+
}
77+
}'
78+
```
79+
80+
## Respond to Review
81+
82+
Classify each review item as actionable, a question, a false positive, or informational. Do not silently ignore actionable comments.
83+
84+
For actionable feedback:
85+
86+
1. Apply the smallest fix that preserves repo conventions.
87+
2. Run the relevant checks.
88+
3. Create a small follow-up commit using the `commit` skill.
89+
4. Push normally with `git push`.
90+
5. Reply to the specific comment with what changed and which validation passed.
91+
92+
Reply to an inline review comment:
93+
94+
```sh
95+
gh api -X POST repos/:owner/:repo/pulls/comments/<comment-id>/replies \
96+
-f body='Fixed in <commit-sha>. Validation: pnpm typecheck, pnpm run test.'
97+
```
98+
99+
Add a top-level PR comment:
100+
101+
```sh
102+
gh pr comment <pr-number-or-url> --body 'Addressed the review feedback in <commit-sha>.'
103+
```
104+
105+
Update an existing top-level issue comment only when correcting your own comment:
106+
107+
```sh
108+
gh api -X PATCH repos/:owner/:repo/issues/comments/<comment-id> \
109+
-f body='Updated comment body'
110+
```
111+
112+
When disagreeing with a review, reply with concrete repository context, not a vague dismissal. If discussion changes the implementation, commit the change and reply again with the result.
113+
114+
## Re-Request Review
115+
116+
After pushing fixes, request another pass if the reviewer does not automatically re-run:
117+
118+
```sh
119+
gh pr comment <pr-number-or-url> --body '@coderabbitai review
120+
@cubic-dev-ai review'
121+
```
122+
123+
Do not wait forever. If reviewers do not respond after a reasonable polling window, leave the PR with the latest commit pushed and note which reviews are still pending.
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../.agents/skills/pr-ai-review-workflow

‎CLAUDE.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Use these skills before working in this repository:
1919
- `bun-cpu-profile` - Bun CPU profiling and branch-vs-main performance comparisons.
2020
- `check-similarity-ts` - AST-based duplicate TypeScript/JavaScript detection.
2121
- `cmux-debug` - terminal UI and responsive table verification in cmux.
22+
- `pr-ai-review-workflow` - PR review loops with `gh`: request AI/code reviewers, wait for comments, reply to inline review comments, and push small follow-up commits.
2223

2324
## Monorepo Packages
2425

@@ -41,4 +42,5 @@ Check the nearest package-specific `CLAUDE.md` before editing package code:
4142
- Do not use dynamic imports anywhere, especially in Vitest blocks.
4243
- Vitest globals are enabled; use `describe`, `it`, `expect`, and `vi` without importing them.
4344
- After code changes, run `pnpm run format`, `pnpm typecheck`, and `pnpm run test`.
45+
- PR branches are squash-merged by default; prefer stacked, small, revertable follow-up commits over `git commit --amend` unless explicitly requested.
4446
- Do what has been asked, nothing more. Do not proactively create documentation files unless explicitly requested.

0 commit comments

Comments
 (0)