From abd8357bfbb94c0a727a6990c35fa6269fc04ed3 Mon Sep 17 00:00:00 2001 From: Iuri Oksuzian Date: Fri, 14 Aug 2026 11:27:36 -0500 Subject: [PATCH] skills: tighten the review draft before it is posted Both review skills state that length is not thoroughness, but neither had a step where that rule fires. It did not fire on Offline#1933: the review shipped a full three-part Evidence/Impact/Suggested-fix block on a S3 nit and a residual-risk bullet caveating a hand analysis that duplicated a check CI had already run and passed. Add a tightening pass to reviewing-pull-requests, run after findings are recorded and before the publish gates, and reference it from post-pr-review step 5 so a draft staged in an earlier session gets the same pass. The pass edits the staged file; the existing "post the body verbatim" rule is unchanged, since tightening finishes the draft rather than rewriting it at gh invocation time. The prose bullet also settles a question that came up directly: a compressed conversational style in effect during a session does not carry into a review body, which goes to collaborators who never opted into it. Co-Authored-By: Claude Opus 5 (1M context) --- skills/post-pr-review/SKILL.md | 19 +++++++++++--- skills/reviewing-pull-requests/SKILL.md | 33 +++++++++++++++++++++++-- 2 files changed, 46 insertions(+), 6 deletions(-) diff --git a/skills/post-pr-review/SKILL.md b/skills/post-pr-review/SKILL.md index 7c8267c..1d3deed 100644 --- a/skills/post-pr-review/SKILL.md +++ b/skills/post-pr-review/SKILL.md @@ -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 @@ -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 --repo / -- --body-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 diff --git a/skills/reviewing-pull-requests/SKILL.md b/skills/reviewing-pull-requests/SKILL.md index faf04e5..3c4d4a3 100644 --- a/skills/reviewing-pull-requests/SKILL.md +++ b/skills/reviewing-pull-requests/SKILL.md @@ -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. --- @@ -684,6 +685,34 @@ and tell the user `/post-pr-review ` 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