Skip to content

fix(pr-craft): open with impact, and tighten body rewrites - #10

Merged
galligan merged 5 commits into
mainfrom
fix/skills/pr-craft-opening-and-rewrites
Nov 11, 2026
Merged

galligan merged 5 commits into
mainfrom
fix/skills/pr-craft-opening-and-rewrites

Conversation

@galligan

@galligan galligan commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

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

  • The description opens with a paragraph of up to three sentences that starts with a verb, such as "Adds" or "Fixes", and ends with what the change affects, in .skillset/skills/pr-craft/SKILL.md.
    • "Addresses" replaces "Fixes" when the change reduces a problem without fully fixing it.
    • Line and file counts are left out unless a number is the point of the change.
  • A rewrite of an existing body restates each verification claim as a command and its result, states each fact once, never mentions itself, and does not outgrow the original.
  • A tracker issue named in a rewritten body moves to the link line, with Related to when the body does not say how the PR relates to it.
  • Each Changes bullet is one sentence with the software as its subject.
  • Review history and diff size are on the leave-out list, and the status of another issue is not an open item.
  • American English is the default, and the skill's own text now uses it.
  • references/examples.md, README.md, and docs/skills.md follow the new opening paragraph.

Verify

  • Search skills/pr-craft for "scope line" and "behaviour" → no matches.
  • Run bun run check:changes --since origin/main → "change check passed".
  • Ran: bun run build, bun run check, bun run check:changes --since origin/main, bun run skillset check --only outputs, and git diff --check, all pass. Not verified: a second rewrite of a real PR body under the new rules.
  • A scoped Redliner review of the diff against 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.

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.
devin-ai-integration[bot]

This comment was marked as resolved.

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.
@galligan
galligan marked this pull request as ready for review November 11, 2026 18:06
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-11T18:08:28.108840Z 35b3bff Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

devin-ai-integration[bot]

This comment was marked as resolved.

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".
devin-ai-integration[bot]

This comment was marked as resolved.

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.

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 new potential issue.

Devin Review

- 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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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.

Devin Review


Was this helpful? React with 👍 or 👎 to provide feedback.

@galligan
galligan merged commit 6c18dc3 into main Nov 11, 2026
3 checks passed
@galligan
galligan deleted the fix/skills/pr-craft-opening-and-rewrites branch November 11, 2026 18:18
@linear-code

linear-code Bot commented Nov 11, 2026

Copy link
Copy Markdown

SET-836

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant