Skip to content

skills: tighten the review draft before it is posted #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
oksuzian wants to merge 1 commit into
base: main
Choose a base branch
from
Open

skills: tighten the review draft before it is posted #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
19 changes: 15 additions & 4 deletions skills/post-pr-review/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ name: post-pr-review
description: Publish a locally drafted PR review to GitHub as a formal review or comment. Use after /reviewing-pull-requests has staged a draft and the user asks to post it. Enforces a staleness gate, decision-to-event mapping, and a duplicate check before anything is sent.
compatibility: Requires gh CLI authenticated with review permission on the target repo
metadata:
version: "1.2.0"
last-updated: "2026-08-07"
version: "1.3.0"
last-updated: "2026-08-14"
---

# Post PR Review
Expand Down Expand Up @@ -70,14 +70,25 @@ moved head, duplicate hit).
suggest posting only the delta (edit the file first) or
re-invoking with `--allow-duplicate`.

5. **Post.**
5. **Tightening pass.** Reread the draft against "Tightening pass" in
`reviewing-pull-requests` and edit the file wherever it fails:
findings that restate instead of prove, ⚪/🟡 carrying a full
three-part block, residual-risk bullets caveating work CI already
covers, 🟢s naming no file or command, telegraphic prose in place of
sentences. A draft staged in an earlier session or hand-edited since
has not necessarily had this pass — run it here regardless.

Editing the file at this point is expected; rewriting the text at
`gh` invocation time is not. Finish the file, then post it verbatim.

6. **Post.**
```
gh pr review <N> --repo <owner>/<repo> --<event> --body-file <file>
```
The body is posted verbatim — never rewrite it at post time. If the
file needs changes, edit and re-stage first, then re-invoke.

6. **Report** the posted review URL, the event used, and which gates
7. **Report** the posted review URL, the event used, and which gates
were overridden (if any).

## Why a local draft at all
Expand Down
33 changes: 31 additions & 2 deletions skills/reviewing-pull-requests/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,8 +86,9 @@ spend the effort.
one per "Triggering a CI Build".
5. **Record findings** with severity and evidence, and summarize residual
risk — per Severity Levels, Evidence Rules and the Output Template above.
6. **Publish** per "Publishing the Review": posted where auto-post is
enabled, staged and reported where it is not.
6. **Tighten, then publish** per "Publishing the Review": cut the draft
against the tightening pass, then post it where auto-post is enabled,
or stage it and report the path where it is not.

---

Expand Down Expand Up @@ -684,6 +685,34 @@ and tell the user `/post-pr-review <N>` publishes it.
To opt in permanently, `export PR_REVIEW_AUTOPOST=1` in your shell
profile. To opt in for one review, ask for "review and post".

### Tightening pass — before the gates

A draft is finished when it has been cut, not when it has been written.
Reread it once against this list and edit the file. This is a drafting
step: by the time the gates run the file is final, and the body posts
verbatim.

- **Cut any finding that restates rather than proves.** If the Evidence
line only rephrases the title, there is no finding — delete it, or go
get the evidence.
- **Collapse ⚪ and 🟡 to one or two lines** — the evidence and the
concrete fix. Drop the Impact paragraph unless the impact is
non-obvious. The full three-part shape is for 🔴 and 🟠, where someone
has to be convinced to act.
- **Delete residual-risk bullets describing work you should not have
done.** Caveating your own substitute for a check the project already
runs advertises the mistake instead of removing it. Cut the analysis,
not just the caveat.
- **Cut 🟢s that restate the PR description.** A 🟢 is a check you ran; if
it names no file, number or command, it is a summary, not a claim.
- **Length tracks blast radius, not effort spent.** A seven-file geometry
PR does not earn a longer review than a subsystem rewrite because you
happened to spend longer on it.
- **Write ordinary prose.** A review body goes to collaborators who did
not opt into whatever compressed conversational style is in effect in
your session — full sentences, no telegraphic fragments. Same rule as
commit messages and documentation.

### Gates

Posting is **fail-closed**: every gate below must pass before `gh` is
Expand Down