Repository navigation
fix(pr-craft): open with impact, and tighten body rewrites - #10
Conversation
The scope line led with a label and diff counts, which read as mechanical and go stale on the next push. It becomes an opening paragraph of up to three sentences that says what the change does and what it affects. A first real rewrite showed the existing-PR rules making a body longer: it annotated itself, copied test totals, and repeated facts. A rewrite now restates verification claims in the skill's form, states each fact once, never mentions itself, and does not outgrow the original. Changes bullets are one sentence with the software as subject. Review history and diff size join the leave-out list. American English is the default.
The pending record from the skill's first release pointed at the previous source hash, so the change check failed.
A Redliner pass on the diff found eight wording conflicts: the fact-once rule against the opening paragraph, verification claims with no command, a length exception that always applied, the subject rule against a verb-led opening, leftover count advice, and Related to reaching into callouts, stacks, and other people's projects.
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
A rewrite kept a commandless claim such as "all tests pass" as worded, which read like a repeatable check. The claim now stays on the Ran line with "command not stated".
A manual check that names its action is repeatable, so a rewrite carries it over as a step. Only a claim with neither a command nor a repeatable action is marked.
| - Carry over the body's existing verification claims as written. Do not re-run them. | ||
| - Keep every fact a reviewer needs. Below the opening paragraph, state each fact once, in the section that owns it. Drop only what `### Leave out` lists. | ||
| - Restate each verification claim in this skill's form: the command or check, and its result. Treat the original's claims as observed, and do not re-run the checks. | ||
| - If a verification claim names neither a command nor an action a reviewer could repeat, keep the claim on the `Ran:` line and add "command not stated". Do not invent a command. A manual check that names its action is carried over as a step. |
There was a problem hiding this comment.
🟡 Completed manual checks become reviewer instructions
When a body says someone clicked Save and saw success, pr-craft moves that observed check to a reviewer step. The Ran: line then omits the manual check, so readers cannot tell it was performed.
Learn more
The Verify section distinguishes repeatable reviewer steps from checks the author already performed. This instruction moves a reported manual check into a step, where its result becomes an expectation instead of an observed result. The Verify format assigns performed checks and results to Ran:. The body template makes the same distinction.
Example: An existing body says, "Clicked Save and confirmed a success toast appeared." The rewrite lists "Click Save → success toast appears" as a step, but does not list the completed check under Ran:. A reviewer loses evidence that Save was already checked.
Recommended fix: Preserve performed manual checks and their observed results on Ran: while also giving the reviewer a repeatable step when useful. Clarify how to avoid duplicating the same fact across the two lines.
Was this helpful? React with 👍 or 👎 to provide feedback.
Replaces
pr-craft's scope line with an opening paragraph that says what a change does and what it affects, and tightens the rules for rewriting an existing PR body. Only the skill's guidance changes.Related to #9
Context
A description written to the skill opens with a label and diff counts, such as "Feature, 22 files in
plugins/bbots". GitHub already shows the counts, and they go stale on the next push. The first real rewrite of an existing body also came out 68% longer than the original: it noted what it had not re-run, copied test totals, and stated one fact twice.Changes
.skillset/skills/pr-craft/SKILL.md.Related towhen the body does not say how the PR relates to it.references/examples.md,README.md, anddocs/skills.mdfollow the new opening paragraph.Verify
skills/pr-craftfor "scope line" and "behaviour" → no matches.bun run check:changes --since origin/main→ "change check passed".bun run build,bun run check,bun run check:changes --since origin/main,bun run skillset check --only outputs, andgit diff --check, all pass. Not verified: a second rewrite of a real PR body under the new rules.review-rubric.md→ no blockers and eight wording conflicts, all fixed in 35b3bff. Not included in that review: the discovery and render pipeline, JSON output, and model profiles.