Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 5 additions & 7 deletions skills/git-shipping/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,11 @@ Use the `cxg` skill for the commit message format, and pipe the message through
## Pull Request

- PR titles use Conventional Commit subject format: `type(scope): subject`.
- Prefer a repository PR template when one applies. Otherwise use only these sections, written so a reviewer grasps the change without reading the diff, and skip what they already know:
- `## Summary`: 1–3 sentences: the outcome once merged, then why it is needed now. Link the issue.
- `## Evidence`: before and after, above the level of the diff. Never copy diff lines or list changes by file. Omit when the diff reads at a glance.
- Behavior: screenshots for UI; otherwise output or a test that fails before and passes after, pasted verbatim.
- Structure: a `diff` or `text` block of a file tree, call tree, or pseudocode you write (`retry: caller → HTTP client`, not the code). Mermaid only for what text cannot show, such as sequences between parties; SVG (e.g. from D2) only when Mermaid lays it out badly.
- Draw from `git diff` and the code, not memory, and check the rendered result, on the PR page if not locally.
- `## Impact` (optional): one-way or two-way door, blast radius, and up to 3 things reviewers must know. Omit unchanged behavior and work not done.
- Prefer a repository PR template when one applies; otherwise read [the PR body format](references/pr-body.md) before writing the body.
- Create the PR with `gh pr create --draft --body-file <file>`, adding `--attach <image>` for each image the body references by that same path.
- Leave an existing PR's draft/ready state alone unless asked.
- After each push to a branch with an open PR, reread the title and body against the diff and `gh pr edit` what no longer matches.

## Review Loop

After opening a PR, read [the review loop](references/review-loop.md) and run it before reporting back.
10 changes: 10 additions & 0 deletions skills/git-shipping/references/pr-body.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# PR Body

Use only these sections, written so a reviewer grasps the change without reading the diff, and skip what they already know:

- `## Summary`: 1–3 sentences: the outcome once merged, then why it is needed now. Link the issue.
- `## Evidence`: before and after, above the level of the diff. Never copy diff lines or list changes by file. Omit when the diff reads at a glance.
- Behavior: screenshots for UI; otherwise output or a test that fails before and passes after, pasted verbatim.
- Structure: a `diff` or `text` block of a file tree, call tree, or pseudocode you write (`retry: caller → HTTP client`, not the code). Mermaid only for what text cannot show, such as sequences between parties; SVG (e.g. from D2) only when Mermaid lays it out badly.
- Draw from `git diff` and the code, not memory, and check the rendered result, on the PR page if not locally.
- `## Impact` (optional): one-way or two-way door, blast radius, and up to 3 things reviewers must know. Omit unchanged behavior and work not done.
8 changes: 8 additions & 0 deletions skills/git-shipping/references/review-loop.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Review Loop

After opening a PR, get it reviewed by Copilot code review and settle the result without waiting for the user:

1. Request a review from `@copilot`. Each review costs AI credits, so request once per push.
2. Wait until `copilot-pull-request-reviewer[bot]` has reviewed the head commit; this usually takes a few minutes. After 10 minutes, stop and report.
3. Settle every unresolved thread with the `receiving-code-review` skill, running unattended. Read the review body too: Copilot lists findings on unchanged code there without opening a thread.
4. Commit and push accepted fixes. If there were any and fewer than three reviews have run, return to step 1; otherwise stop and report, naming fixes no review has seen.
10 changes: 4 additions & 6 deletions skills/receiving-code-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,14 @@ The item is clear but nothing in reach proves or disproves it — a production-o

A suggestion that contradicts a decision the user already made outranks the table: it goes back to the user, not into the code.

Confidence in a reviewer is not evidence. Bots and agent reviewers report findings about code paths they never read, and a human may be reading an older revision; check either, and accept what holds up.
Confidence in a reviewer is not evidence. Bots and agent reviewers report findings about code paths they never read, and a human may be reading an older revision; check either, and accept what holds up. Judge an outdated thread against the current code, not the hunk it was left on.

## Clarify All Items First

Assign verdicts across every item before implementing any of them, and ask about all the unclear ones in a single reply. Hold any item sharing an assumption with an unclear one — fixing item 3 under a wrong reading of item 5 produces work that must be undone. Independent accepted items can proceed while you wait.

When the reviewer is an AI such as Copilot code review, or no user can answer mid-run, read [AI reviewers and unattended runs](references/ai-reviewers.md).

## Implement and Verify

Order accepted items: breakage and security first, then mechanical fixes, then the ones that need design. Verify each fix on its own before starting the next, and re-run the wider tests once the batch is done.
Expand All @@ -42,8 +44,4 @@ Order accepted items: breakage and security first, then mechanical fixes, then t

Report the verdict and what settled it — "Reproduced, fixed in `parser.ts`", "Checked: no caller reaches this branch". Accepting is silent work; pushing back needs the contradicting evidence quoted. If you pushed back and were wrong, say what you checked, what it showed, and that you are fixing it.

On GitHub, answer an inline comment inside its own thread:

```bash
gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies -f body='...'
```
On GitHub, reply inside the comment's own thread and resolve the thread once handled, so the next pass sees only new items.
7 changes: 7 additions & 0 deletions skills/receiving-code-review/references/ai-reviewers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# AI Reviewers and Unattended Runs

AI reviewers such as Copilot code review never read replies and re-raise items already settled. A repeat keeps its earlier verdict unless the code or evidence behind that verdict has changed; re-judging the same evidence only flips the verdict back and forth.

When no user can answer mid-run, as in a review loop, do not wait: fix independent accepted items, and for every other verdict or held item reply with your reading and evidence and leave the code unchanged. Resolved threads drop out of sight, so list each unfixed item with its verdict, or what holds it, in the final report.

Since the reviewer never reads replies, leave the question off a push back; the reply is a record for humans.