diff --git a/.skillset/changes/5124e78bc3c1.md b/.skillset/changes/5124e78bc3c1.md new file mode 100644 index 0000000..ebcd6ea --- /dev/null +++ b/.skillset/changes/5124e78bc3c1.md @@ -0,0 +1,4 @@ +Replace the scope line with an opening paragraph that states what the change does and what it affects, without diff counts. Tighten the rules for rewriting an existing PR body, and write American English by default. + +Bump: patch +Scope: skill:pr-craft diff --git a/.skillset/changes/ledger.jsonl b/.skillset/changes/ledger.jsonl index d97e796..30f777a 100644 --- a/.skillset/changes/ledger.jsonl +++ b/.skillset/changes/ledger.jsonl @@ -87,3 +87,12 @@ {"createdAt":"2026-11-11T17:20:27.713Z","id":"evt-24a1aab7e6267a2c","payload":{"reasonId":"c70cafeb3a81","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:5b872e98bed8fa0beabe2af45a5d17a06f168dc5644b5bab237e3e8b8fed955f"}]},"schemaVersion":1,"type":"change.covered"} {"createdAt":"2026-11-11T17:23:13.592Z","id":"evt-1c804f5a82d2f763","payload":{"reasonId":"c70cafeb3a81","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:edc547a6b55da7e235b26a2aaf942f0010e09ee6b9533037c56f0d94ca8a5826"}]},"schemaVersion":1,"type":"change.covered"} {"createdAt":"2026-11-11T17:25:30.068Z","id":"evt-6c77f4ec69dd57f6","payload":{"reasonId":"c70cafeb3a81","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:90e0b884cc4b7a3c23b29f6564867d28d26980039bdb6736061e49c8496b28a8"}]},"schemaVersion":1,"type":"change.covered"} +{"createdAt":"2026-11-11T18:03:38.511Z","id":"evt-f9faadfafef44d08","payload":{"bump":"patch","path":".skillset/changes/5124e78bc3c1.md","reason":"Replace the scope line with an opening paragraph that states what the change does and what it affects, without diff counts. Tighten the rules for rewriting an existing PR body, and write American English by default.","reasonId":"5124e78bc3c1","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:f03238392df15dc677970fb5d76c90426b62667327e5db85941203294b987716"}]},"schemaVersion":1,"type":"reason.created"} +{"createdAt":"2026-11-11T18:03:38.511Z","id":"evt-916504c1591cdcbb","payload":{"reasonId":"5124e78bc3c1","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:f03238392df15dc677970fb5d76c90426b62667327e5db85941203294b987716"}]},"schemaVersion":1,"type":"change.covered"} +{"createdAt":"2026-11-11T18:03:50.971Z","id":"evt-d56e04aa8f7ab0c7","payload":{"reasonId":"c70cafeb3a81","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:f03238392df15dc677970fb5d76c90426b62667327e5db85941203294b987716"}]},"schemaVersion":1,"type":"change.covered"} +{"createdAt":"2026-11-11T18:06:00.019Z","id":"evt-6d7c8f9b131ad687","payload":{"reasonId":"5124e78bc3c1","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:0c532660c216f70a7a66f78e15df6fd7c62b5ef3f8506e3ccc50f903fb6e682e"}]},"schemaVersion":1,"type":"change.covered"} +{"createdAt":"2026-11-11T18:06:00.019Z","id":"evt-7b7c551864d6b4d7","payload":{"reasonId":"c70cafeb3a81","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:0c532660c216f70a7a66f78e15df6fd7c62b5ef3f8506e3ccc50f903fb6e682e"}]},"schemaVersion":1,"type":"change.covered"} +{"createdAt":"2026-11-11T18:12:11.116Z","id":"evt-55ce661afe97a770","payload":{"reasonId":"5124e78bc3c1","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:0aa43efa9ec684aac54c0b57337388874068d6e3845cfb0113bc19aa53a917a7"}]},"schemaVersion":1,"type":"change.covered"} +{"createdAt":"2026-11-11T18:12:11.116Z","id":"evt-cfee1a781660b715","payload":{"reasonId":"c70cafeb3a81","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:0aa43efa9ec684aac54c0b57337388874068d6e3845cfb0113bc19aa53a917a7"}]},"schemaVersion":1,"type":"change.covered"} +{"createdAt":"2026-11-11T18:13:46.213Z","id":"evt-52199bd60a936df6","payload":{"reasonId":"5124e78bc3c1","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:fdeea6de72c14be93d2ba9555133af51bf7378321b3459d1c20124db2fb607c8"}]},"schemaVersion":1,"type":"change.covered"} +{"createdAt":"2026-11-11T18:13:46.213Z","id":"evt-773b76bd44b73d0b","payload":{"reasonId":"c70cafeb3a81","sourceUnits":[{"hashSchema":"skillset-source-unit-v3","selector":"skill:pr-craft","sourceHash":"sha256:fdeea6de72c14be93d2ba9555133af51bf7378321b3459d1c20124db2fb607c8"}]},"schemaVersion":1,"type":"change.covered"} diff --git a/.skillset/skills/pr-craft/SKILL.md b/.skillset/skills/pr-craft/SKILL.md index c8bbf6b..ab49a91 100644 --- a/.skillset/skills/pr-craft/SKILL.md +++ b/.skillset/skills/pr-craft/SKILL.md @@ -5,7 +5,7 @@ description: Write or rewrite a pull request's title and description so a review # PR Craft -Write the PR title and description for a reader who has not seen the session. A description has a one-line scope statement and three sections: Context, Changes, and Verify. Four more sections appear only when the change calls for them. +Write the PR title and description for a reader who has not seen the session. A description has an opening paragraph and three sections: Context, Changes, and Verify. Four more sections appear only when the change calls for them. This skill governs the text of a PR. It does not decide whether to open, push, or merge. Follow the task and the repository's instructions for those decisions. @@ -24,11 +24,11 @@ This skill governs the text of a PR. It does not decide whether to open, push, o ## Shape -Sections appear in this order. Delete every optional part the change does not need. Most descriptions keep only the scope line, Context, Changes, and Verify. +Sections appear in this order. Delete every optional part the change does not need. Most descriptions keep only the opening paragraph, Context, Changes, and Verify. | Part | When | Holds | | --- | --- | --- | -| Scope line (no heading) | Always | Kind of change, size, whether behaviour changes | +| Opening paragraph (no heading) | Always | What the change does and what it affects | | Link line (no heading) | The PR has an issue | A keyword and each issue it applies to | | Callout | Rarely | The one thing the reader must see first | | Context | Always | What happens today, and when | @@ -40,7 +40,7 @@ Sections appear in this order. Delete every optional part the change does not ne | Open items | Something is unfinished after merge | Questions, decisions, follow-ups, what was left out | ```markdown - + /issue/ENG-123)> @@ -81,9 +81,17 @@ Weak and strong versions of each part, and one whole description, are in [exampl ## Core sections -### Scope line +### Opening paragraph -One unheaded line: the kind of change, its size, and whether behaviour changes. Example: `Docs only, 11 lines in one file, no behaviour change.` The reviewer uses it to decide when to look. +One unheaded paragraph of up to three sentences. Say what the change does and what it means for someone using or running the software. + +- Start with a verb that carries the kind of change: "Adds", "Fixes", "Removes", "Renames", "Moves". Do not lead with a label such as "Feature" or "Fix:". +- If the change reduces a problem without fully fixing it, use "Addresses" in place of "Fixes". +- If it is known, end with what the change affects, leaves alone, or does not yet fix: "Nothing existing changes.", "Docs only." +- Do not state line or file counts. GitHub shows them, and a count in the body goes stale on the next push. +- If a number is the point of the change, state it: a benchmark result, or "all 40 call sites". + +Example: `Fixes search for queries that end in a space, which returned no results. Results for every other query are unchanged.` ### Context @@ -97,11 +105,13 @@ Leave out how the problem was found. If a fact is in the linked issue, link the ### Changes -What happens now, one bullet per change. Put the behaviour first, then the file or function in backticks. +What happens now, one bullet per change. Put the behavior first, then the file or function in backticks. + +- Write each bullet as one sentence with the software as its subject: "A query is trimmed before it is split", not "Trim the query". +- Put the cases or details of one change in sub-bullets, one level deep. - Name a file only where the reviewer needs it to find the change. The diff holds the inventory. -- If the reason for the approach is not obvious, give it here in one sentence. -- Use one level of sub-bullets where detail belongs to one item. +- If the reason for the approach is not obvious, give it in a sub-bullet. ### Verify @@ -140,6 +150,7 @@ Use it when something is still unfinished after merge: a question for the review - Start each bullet with its kind and who acts on it: `Question (reviewer):`, `Follow-up (author):`, `Not included:`. - What was not tested goes on the last line of Verify, not here. +- The status of another issue or PR is not an open item. If the reviewer must act on it, use a callout. Otherwise link it on the link line with `Related to`, or leave it out. Do not list stack siblings. ## Callouts @@ -151,14 +162,14 @@ A callout shows something the reader must see before anything else. Use three ty | `[!IMPORTANT]` | The reviewer must do or decide something before merge | "Merge after #12." | | `[!NOTE]` | Context that changes how to read the PR | "Part of a stack." | -- Place a callout directly under the scope line and link line, never inside a section. +- Place a callout directly under the opening paragraph and link line, never inside a section. - Most descriptions have no callout. Two is the limit. - Keep it to one or two sentences. If a section holds the detail, point to that section. - Do not use a callout for emphasis on ordinary content. ## Linking issues -Put issue links on one line directly under the scope line. The keyword decides what happens to the issue when the PR merges, in GitHub and in Linear alike. +Put issue links on one line directly under the opening paragraph. The keyword decides what happens to the issue when the PR merges, in GitHub and in Linear alike. ```text Closes #351, closes [ENG-123](https://linear.app/acme/issue/ENG-123), part of [OPS-45](https://linear.app/acme/issue/OPS-45) @@ -213,7 +224,7 @@ gh pr create --title "" --body-file body.md \ ## Repositories the user does not own - Follow the project's PR template, title convention, and contribution guide before anything here. -- Add an opener of one or two sentences above the scope line: who the contributor is and why they made the change. Draft it from what the user has said. Do not invent a motive. +- Add an introduction of one or two sentences above the opening paragraph: who the contributor is and why they made the change. Draft it from what the user has said. Do not invent a motive. - Reference only that project's own issues. Do not add a link to the user's tracker, do not put a tracker ID in the title, and do not use `<TEAM>-NEW`. - If the change is breaking or has several workable designs, tell the user that an issue or discussion on the project comes before the PR. - Expect `--attach` to fail without push access. Use the fallback in `## Media`. @@ -227,8 +238,14 @@ If all of the following hold, rewrite the PR body into this shape: 3. The body follows neither this shape nor the repository's PR template. 4. The agent's access allows editing the PR. -- Keep every fact a reviewer needs, and move each to the section that owns it. Drop only what `### Leave out` lists. -- 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. +- Do not mention the rewrite, the previous body, or what was not re-run. +- Do not make the body longer than the original. Exception: if the original has no content for the opening paragraph, Context, Changes, or Verify, add only that content. +- If the body names a tracker issue, move the issue to the link line. If the body does not say how the PR relates to the issue, use `Related to`. Do not guess `Closes`. +- If the repository is not the user's and the body names an issue in the user's tracker, drop that reference. +- Do not add `<TEAM>-NEW` in a rewrite. - Leave any block a tool manages as that tool wrote it, such as a stack list or a session link. - Do not search for other PRs to rewrite. - Do not rewrite a PR that someone else authored. @@ -239,16 +256,17 @@ Agents write most descriptions, and both people and agents read them. Keep the t ### Order -- Put the bottom line first. The scope line, link line, and callout tell a reader who stops there what the PR is, how big it is, and what it needs from them. +- Put the bottom line first. The opening paragraph, link line, and callout tell a reader who stops there what the PR does, what it affects, and what it needs from them. - Make the first sentence of each section that section's point. - Do not label the bottom line with "Summary:" or "TL;DR". - Do not end with a closing summary. ### Sentences -- Describe the software, not the author. The subject is the product, the user, or the file. It is not "I", "we", or "this PR". +- Describe the software, not the author. The subject is the product, the user, or the file. It is not "I", "we", or "this PR". Exception: the opening paragraph starts with its verb. - Use the present tense. Context says what happens today. Changes says what happens with the PR merged: "The guide says", not "Updated the guide to say". -- Give the number, not the adjective: "nine times", "11 lines", "40 ms". +- For a fact about the software, give the number, not the adjective: "nine times", "40 ms". This does not apply to the size of the diff; see `### Opening paragraph`. +- Write American English, unless the repository's own text uses another variety. - Use the exact name. Identifiers, commands, and paths go in backticks, as written in the code. Interface labels go in quotes, as they appear on screen. - Repeat the noun when "it" or "this" could point at two things. - Refer to a section by name: "See Upgrading", not "see below". @@ -268,6 +286,8 @@ A description is as long as its reader needs. Say each thing once, in the fewest ### Leave out - How the work was done: the order of attempts, the dead ends, the tools used. +- Review history: which findings were addressed, in which commit, and which threads were resolved. +- The size of the diff: line counts and file counts. - A file-by-file or function-by-function inventory. - Text repeated from the title or the commit messages. - Test totals, pass counts, and terminal output. Name the command and its result. @@ -284,16 +304,16 @@ The headings stay the same for every kind of PR. What goes under them shifts. | --- | --- | --- | --- | --- | | Fix | What breaks, for whom, how to see it | The fix, and the test that fails without it | The repro steps, now passing | Comparison, when the bug is visible | | Docs | What the docs say against what is true | The lines corrected | A search command, or a page to look at | Comparison, as text | -| Feature | What someone cannot do today | The new behaviour, then the files | A click path with the expected result | Comparison; Alternatives if the design was a choice | -| Refactor | What the current shape makes hard | What moved where, stated as move-only | The suite passes with no behaviour change | Open items, for the moves still to come | +| Feature | What someone cannot do today | The new behavior, then the files | A click path with the expected result | Comparison; Alternatives if the design was a choice | +| Refactor | What the current shape makes hard | What moved where, stated as move-only | The suite passes with no behavior change | Open items, for the moves still to come | | Performance | What is slow, with a number | The change | The benchmark command | Comparison, as numbers | -| Breaking | What the current behaviour costs | The new behaviour | Steps on an existing install | Upgrading, and a `[!WARNING]` callout | +| Breaking | What the current behavior costs | The new behavior | Steps on an existing install | Upgrading, and a `[!WARNING]` callout | ## Before requesting review Read the draft once as the reviewer, without the diff. It must answer three questions: what happens today, what changes, and how to check. In that one read, confirm: -- No heading is empty and no section restates another. +- No heading is empty and no section restates another. The opening paragraph may summarize what the sections detail. - Every Verify step has an expected result, and the "Ran" line lists only what ran. - Every identifier and interface label is written as it appeared in the code or on screen during the work. diff --git a/.skillset/skills/pr-craft/references/examples.md b/.skillset/skills/pr-craft/references/examples.md index 068c91b..85a951e 100644 --- a/.skillset/skills/pr-craft/references/examples.md +++ b/.skillset/skills/pr-craft/references/examples.md @@ -20,7 +20,7 @@ fix(search): trim the query before splitting it The strong title names the area and says what the software does now. With one issue that identifies the PR, the ID goes at the end: `fix(search): trim the query before splitting it ENG-140`. -### Scope line +### Opening paragraph Weak: @@ -28,13 +28,25 @@ Weak: This PR introduces a comprehensive fix for an important search issue and significantly improves the overall user experience. ``` -Strong: +Also weak: ```text Fix, 14 lines in two files; search results change for queries that end in a space. ``` -The strong line gives the kind, the size, and the behaviour as facts. Nothing in the weak line can be checked. +Strong: + +```text +Fixes search for queries that end in a space, which returned no results. Results for every other query are unchanged. +``` + +The strong paragraph says what the change does and what it leaves alone. Nothing in the first weak version can be checked. The second leads with a label and with counts that GitHub already shows and that go stale on the next push. + +A change that reduces a problem without fully fixing it says so: + +```text +Addresses slow search on large catalogs by caching parsed queries. Queries over 200 terms are still slow. +``` ### Link line @@ -198,11 +210,11 @@ Each strong item is one thing still open, with who acts on it. The weak version | Phrase | Problem | Write instead | | --- | --- | --- | -| "This PR adds", "This PR fixes" | The subject is the PR, not the software | Start with the software: "Search trims the query" | -| "Updated X to", "Refactored Y" | Describes the edit, not the behaviour | "X now does" | +| "This PR adds", "This PR fixes" | The subject is the PR, not the software | In a section, start with the software: "Search trims the query". In the opening paragraph, start with the verb: "Fixes search" | +| "Updated X to", "Refactored Y" | Describes the edit, not the behavior | "X now does" | | comprehensive, robust, seamless, clean | Cannot be checked | The number, or nothing | -| minor, small, quick | The reviewer decides that | Lines and files | -| various, several, some files | Names nothing | The count, or the names | +| minor, small, quick | The reviewer decides that | What the change affects | +| various, several, some files | Names nothing | The names, or what they share | | "should now work", "hopefully fixes" | Hedges something that can be checked | What was run and what it showed, or "Not verified" | | "works as expected" | States no expectation | The step and its result | | "All tests pass" with a tick | No command and no scope | "`pnpm test` passes" | @@ -223,7 +235,7 @@ fix(search): trim the query before splitting it Body: ```markdown -Fix, 14 lines in two files; search results change for queries that end in a space. +Fixes search for queries that end in a space, which returned no results. Results for every other query are unchanged. Closes #208, closes [ENG-140](https://linear.app/acme/issue/ENG-140) @@ -252,16 +264,16 @@ A search that ends in a space returns no results. `parseQuery` reads the trailin - Follow-up (author): the API docs still say trailing spaces are significant. Separate PR. ``` -This description uses three optional sections because the fix has a visible before and after, a real alternative, and two things still open. A docs fix usually keeps only the scope line, Context, Changes, and Verify. +This description uses three optional sections because the fix has a visible before and after, a real alternative, and two things still open. A docs fix usually keeps only the opening paragraph, Context, Changes, and Verify. ## A contribution to someone else's project -The same fix, sent to a project the contributor does not maintain. The opener comes first, the link line references only that project's issue, and the Comparison is text because attaching media needs push access. +The same fix, sent to a project the contributor does not maintain. The introduction comes first, the link line references only that project's issue, and the Comparison is text because attaching media needs push access. ```markdown -I run this for a small tea shop's catalogue, and customers on phones kept reporting empty searches. +I run this for a small tea shop's catalog, and customers on phones kept reporting empty searches. -Fix, 14 lines in two files; search results change for queries that end in a space. +Fixes search for queries that end in a space, which returned no results. Results for every other query are unchanged. Closes #208 diff --git a/README.md b/README.md index 6e5416c..c4753c2 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ When every detail is "load-bearing" and every insight is "hiding in plain sight, ### [`/pr-craft`](skills/pr-craft/SKILL.md) -Pull request titles and descriptions a reviewer can act on: how big the change is, what happens today, what changes, and how to check it. Covers issue links for GitHub and Linear, before-and-after media, and everything that should stay out. +Pull request titles and descriptions a reviewer can act on: what the change does, what happens today, what changes, and how to check it. Covers issue links for GitHub and Linear, before-and-after media, and everything that should stay out. 📬 **Try:** Before your agent opens a PR, tell it to use `/pr-craft` for the title and description. diff --git a/docs/skills.md b/docs/skills.md index 13feaa7..efc33b9 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -75,7 +75,7 @@ The aim is to preserve what matters while improving how it's expressed. A detail Agents open a lot of pull requests now, and most of the descriptions are longer than the change deserves. They narrate how the work went, list every file, and finish with a row of green ticks. The reviewer still has to open the diff to learn what the PR does and whether anyone checked it. -`pr-craft` gives the description a fixed shape. One line says what kind of change it is, how big, and whether behaviour changes. Then come three sections: Context for what happens today, Changes for what happens now, and Verify for steps the reviewer can run and what was run already. Upgrading, Comparison, Alternatives, and Open items appear only when the change calls for them. +`pr-craft` gives the description a fixed shape. A short opening paragraph says what the change does and what it affects. Then come three sections: Context for what happens today, Changes for what happens now, and Verify for steps the reviewer can run and what was run already. Upgrading, Comparison, Alternatives, and Open items appear only when the change calls for them. Use it when: @@ -88,6 +88,6 @@ For example: > Use pr-craft to write the title and description for this branch, then open the PR as a draft. -Titles default to Conventional Commits, and a repository's own template and conventions come first. When an agent is already working on a PR that you or one of your agents opened, and the body follows neither this shape nor the repository's template, it rewrites the body without being asked. On a project you don't maintain, the skill adds a short opener, sticks to that project's issues, and leaves your tracker out of it. +Titles default to Conventional Commits, and a repository's own template and conventions come first. When an agent is already working on a PR that you or one of your agents opened, and the body follows neither this shape nor the repository's template, it rewrites the body without being asked. On a project you don't maintain, the skill adds a short introduction, sticks to that project's issues, and leaves your tracker out of it. [The skill](../skills/pr-craft/SKILL.md) covers the text of a PR. Whether to open, push, or merge is still decided by the task and the repository's instructions. Attaching media uses the GitHub CLI, version 2.99.0 or later, and Linear links need Linear's GitHub integration on the repository. diff --git a/skills/pr-craft/SKILL.md b/skills/pr-craft/SKILL.md index 0b27b7f..c41b7cb 100644 --- a/skills/pr-craft/SKILL.md +++ b/skills/pr-craft/SKILL.md @@ -8,7 +8,7 @@ name: pr-craft # PR Craft -Write the PR title and description for a reader who has not seen the session. A description has a one-line scope statement and three sections: Context, Changes, and Verify. Four more sections appear only when the change calls for them. +Write the PR title and description for a reader who has not seen the session. A description has an opening paragraph and three sections: Context, Changes, and Verify. Four more sections appear only when the change calls for them. This skill governs the text of a PR. It does not decide whether to open, push, or merge. Follow the task and the repository's instructions for those decisions. @@ -27,11 +27,11 @@ This skill governs the text of a PR. It does not decide whether to open, push, o ## Shape -Sections appear in this order. Delete every optional part the change does not need. Most descriptions keep only the scope line, Context, Changes, and Verify. +Sections appear in this order. Delete every optional part the change does not need. Most descriptions keep only the opening paragraph, Context, Changes, and Verify. | Part | When | Holds | | --- | --- | --- | -| Scope line (no heading) | Always | Kind of change, size, whether behaviour changes | +| Opening paragraph (no heading) | Always | What the change does and what it affects | | Link line (no heading) | The PR has an issue | A keyword and each issue it applies to | | Callout | Rarely | The one thing the reader must see first | | Context | Always | What happens today, and when | @@ -43,7 +43,7 @@ Sections appear in this order. Delete every optional part the change does not ne | Open items | Something is unfinished after merge | Questions, decisions, follow-ups, what was left out | ```markdown -<scope line: kind of change, size, whether behaviour changes> +<opening paragraph: what the change does and what it affects; up to three sentences> <link line: Closes #12, closes [ENG-123](https://linear.app/<workspace>/issue/ENG-123)> @@ -84,9 +84,17 @@ Weak and strong versions of each part, and one whole description, are in [exampl ## Core sections -### Scope line +### Opening paragraph -One unheaded line: the kind of change, its size, and whether behaviour changes. Example: `Docs only, 11 lines in one file, no behaviour change.` The reviewer uses it to decide when to look. +One unheaded paragraph of up to three sentences. Say what the change does and what it means for someone using or running the software. + +- Start with a verb that carries the kind of change: "Adds", "Fixes", "Removes", "Renames", "Moves". Do not lead with a label such as "Feature" or "Fix:". +- If the change reduces a problem without fully fixing it, use "Addresses" in place of "Fixes". +- If it is known, end with what the change affects, leaves alone, or does not yet fix: "Nothing existing changes.", "Docs only." +- Do not state line or file counts. GitHub shows them, and a count in the body goes stale on the next push. +- If a number is the point of the change, state it: a benchmark result, or "all 40 call sites". + +Example: `Fixes search for queries that end in a space, which returned no results. Results for every other query are unchanged.` ### Context @@ -100,11 +108,13 @@ Leave out how the problem was found. If a fact is in the linked issue, link the ### Changes -What happens now, one bullet per change. Put the behaviour first, then the file or function in backticks. +What happens now, one bullet per change. Put the behavior first, then the file or function in backticks. + +- Write each bullet as one sentence with the software as its subject: "A query is trimmed before it is split", not "Trim the query". +- Put the cases or details of one change in sub-bullets, one level deep. - Name a file only where the reviewer needs it to find the change. The diff holds the inventory. -- If the reason for the approach is not obvious, give it here in one sentence. -- Use one level of sub-bullets where detail belongs to one item. +- If the reason for the approach is not obvious, give it in a sub-bullet. ### Verify @@ -143,6 +153,7 @@ Use it when something is still unfinished after merge: a question for the review - Start each bullet with its kind and who acts on it: `Question (reviewer):`, `Follow-up (author):`, `Not included:`. - What was not tested goes on the last line of Verify, not here. +- The status of another issue or PR is not an open item. If the reviewer must act on it, use a callout. Otherwise link it on the link line with `Related to`, or leave it out. Do not list stack siblings. ## Callouts @@ -154,14 +165,14 @@ A callout shows something the reader must see before anything else. Use three ty | `[!IMPORTANT]` | The reviewer must do or decide something before merge | "Merge after #12." | | `[!NOTE]` | Context that changes how to read the PR | "Part of a stack." | -- Place a callout directly under the scope line and link line, never inside a section. +- Place a callout directly under the opening paragraph and link line, never inside a section. - Most descriptions have no callout. Two is the limit. - Keep it to one or two sentences. If a section holds the detail, point to that section. - Do not use a callout for emphasis on ordinary content. ## Linking issues -Put issue links on one line directly under the scope line. The keyword decides what happens to the issue when the PR merges, in GitHub and in Linear alike. +Put issue links on one line directly under the opening paragraph. The keyword decides what happens to the issue when the PR merges, in GitHub and in Linear alike. ```text Closes #351, closes [ENG-123](https://linear.app/acme/issue/ENG-123), part of [OPS-45](https://linear.app/acme/issue/OPS-45) @@ -216,7 +227,7 @@ gh pr create --title "<title>" --body-file body.md \ ## Repositories the user does not own - Follow the project's PR template, title convention, and contribution guide before anything here. -- Add an opener of one or two sentences above the scope line: who the contributor is and why they made the change. Draft it from what the user has said. Do not invent a motive. +- Add an introduction of one or two sentences above the opening paragraph: who the contributor is and why they made the change. Draft it from what the user has said. Do not invent a motive. - Reference only that project's own issues. Do not add a link to the user's tracker, do not put a tracker ID in the title, and do not use `<TEAM>-NEW`. - If the change is breaking or has several workable designs, tell the user that an issue or discussion on the project comes before the PR. - Expect `--attach` to fail without push access. Use the fallback in `## Media`. @@ -230,8 +241,14 @@ If all of the following hold, rewrite the PR body into this shape: 3. The body follows neither this shape nor the repository's PR template. 4. The agent's access allows editing the PR. -- Keep every fact a reviewer needs, and move each to the section that owns it. Drop only what `### Leave out` lists. -- 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. +- Do not mention the rewrite, the previous body, or what was not re-run. +- Do not make the body longer than the original. Exception: if the original has no content for the opening paragraph, Context, Changes, or Verify, add only that content. +- If the body names a tracker issue, move the issue to the link line. If the body does not say how the PR relates to the issue, use `Related to`. Do not guess `Closes`. +- If the repository is not the user's and the body names an issue in the user's tracker, drop that reference. +- Do not add `<TEAM>-NEW` in a rewrite. - Leave any block a tool manages as that tool wrote it, such as a stack list or a session link. - Do not search for other PRs to rewrite. - Do not rewrite a PR that someone else authored. @@ -242,16 +259,17 @@ Agents write most descriptions, and both people and agents read them. Keep the t ### Order -- Put the bottom line first. The scope line, link line, and callout tell a reader who stops there what the PR is, how big it is, and what it needs from them. +- Put the bottom line first. The opening paragraph, link line, and callout tell a reader who stops there what the PR does, what it affects, and what it needs from them. - Make the first sentence of each section that section's point. - Do not label the bottom line with "Summary:" or "TL;DR". - Do not end with a closing summary. ### Sentences -- Describe the software, not the author. The subject is the product, the user, or the file. It is not "I", "we", or "this PR". +- Describe the software, not the author. The subject is the product, the user, or the file. It is not "I", "we", or "this PR". Exception: the opening paragraph starts with its verb. - Use the present tense. Context says what happens today. Changes says what happens with the PR merged: "The guide says", not "Updated the guide to say". -- Give the number, not the adjective: "nine times", "11 lines", "40 ms". +- For a fact about the software, give the number, not the adjective: "nine times", "40 ms". This does not apply to the size of the diff; see `### Opening paragraph`. +- Write American English, unless the repository's own text uses another variety. - Use the exact name. Identifiers, commands, and paths go in backticks, as written in the code. Interface labels go in quotes, as they appear on screen. - Repeat the noun when "it" or "this" could point at two things. - Refer to a section by name: "See Upgrading", not "see below". @@ -271,6 +289,8 @@ A description is as long as its reader needs. Say each thing once, in the fewest ### Leave out - How the work was done: the order of attempts, the dead ends, the tools used. +- Review history: which findings were addressed, in which commit, and which threads were resolved. +- The size of the diff: line counts and file counts. - A file-by-file or function-by-function inventory. - Text repeated from the title or the commit messages. - Test totals, pass counts, and terminal output. Name the command and its result. @@ -287,16 +307,16 @@ The headings stay the same for every kind of PR. What goes under them shifts. | --- | --- | --- | --- | --- | | Fix | What breaks, for whom, how to see it | The fix, and the test that fails without it | The repro steps, now passing | Comparison, when the bug is visible | | Docs | What the docs say against what is true | The lines corrected | A search command, or a page to look at | Comparison, as text | -| Feature | What someone cannot do today | The new behaviour, then the files | A click path with the expected result | Comparison; Alternatives if the design was a choice | -| Refactor | What the current shape makes hard | What moved where, stated as move-only | The suite passes with no behaviour change | Open items, for the moves still to come | +| Feature | What someone cannot do today | The new behavior, then the files | A click path with the expected result | Comparison; Alternatives if the design was a choice | +| Refactor | What the current shape makes hard | What moved where, stated as move-only | The suite passes with no behavior change | Open items, for the moves still to come | | Performance | What is slow, with a number | The change | The benchmark command | Comparison, as numbers | -| Breaking | What the current behaviour costs | The new behaviour | Steps on an existing install | Upgrading, and a `[!WARNING]` callout | +| Breaking | What the current behavior costs | The new behavior | Steps on an existing install | Upgrading, and a `[!WARNING]` callout | ## Before requesting review Read the draft once as the reviewer, without the diff. It must answer three questions: what happens today, what changes, and how to check. In that one read, confirm: -- No heading is empty and no section restates another. +- No heading is empty and no section restates another. The opening paragraph may summarize what the sections detail. - Every Verify step has an expected result, and the "Ran" line lists only what ran. - Every identifier and interface label is written as it appeared in the code or on screen during the work. diff --git a/skills/pr-craft/references/examples.md b/skills/pr-craft/references/examples.md index 068c91b..85a951e 100644 --- a/skills/pr-craft/references/examples.md +++ b/skills/pr-craft/references/examples.md @@ -20,7 +20,7 @@ fix(search): trim the query before splitting it The strong title names the area and says what the software does now. With one issue that identifies the PR, the ID goes at the end: `fix(search): trim the query before splitting it ENG-140`. -### Scope line +### Opening paragraph Weak: @@ -28,13 +28,25 @@ Weak: This PR introduces a comprehensive fix for an important search issue and significantly improves the overall user experience. ``` -Strong: +Also weak: ```text Fix, 14 lines in two files; search results change for queries that end in a space. ``` -The strong line gives the kind, the size, and the behaviour as facts. Nothing in the weak line can be checked. +Strong: + +```text +Fixes search for queries that end in a space, which returned no results. Results for every other query are unchanged. +``` + +The strong paragraph says what the change does and what it leaves alone. Nothing in the first weak version can be checked. The second leads with a label and with counts that GitHub already shows and that go stale on the next push. + +A change that reduces a problem without fully fixing it says so: + +```text +Addresses slow search on large catalogs by caching parsed queries. Queries over 200 terms are still slow. +``` ### Link line @@ -198,11 +210,11 @@ Each strong item is one thing still open, with who acts on it. The weak version | Phrase | Problem | Write instead | | --- | --- | --- | -| "This PR adds", "This PR fixes" | The subject is the PR, not the software | Start with the software: "Search trims the query" | -| "Updated X to", "Refactored Y" | Describes the edit, not the behaviour | "X now does" | +| "This PR adds", "This PR fixes" | The subject is the PR, not the software | In a section, start with the software: "Search trims the query". In the opening paragraph, start with the verb: "Fixes search" | +| "Updated X to", "Refactored Y" | Describes the edit, not the behavior | "X now does" | | comprehensive, robust, seamless, clean | Cannot be checked | The number, or nothing | -| minor, small, quick | The reviewer decides that | Lines and files | -| various, several, some files | Names nothing | The count, or the names | +| minor, small, quick | The reviewer decides that | What the change affects | +| various, several, some files | Names nothing | The names, or what they share | | "should now work", "hopefully fixes" | Hedges something that can be checked | What was run and what it showed, or "Not verified" | | "works as expected" | States no expectation | The step and its result | | "All tests pass" with a tick | No command and no scope | "`pnpm test` passes" | @@ -223,7 +235,7 @@ fix(search): trim the query before splitting it Body: ```markdown -Fix, 14 lines in two files; search results change for queries that end in a space. +Fixes search for queries that end in a space, which returned no results. Results for every other query are unchanged. Closes #208, closes [ENG-140](https://linear.app/acme/issue/ENG-140) @@ -252,16 +264,16 @@ A search that ends in a space returns no results. `parseQuery` reads the trailin - Follow-up (author): the API docs still say trailing spaces are significant. Separate PR. ``` -This description uses three optional sections because the fix has a visible before and after, a real alternative, and two things still open. A docs fix usually keeps only the scope line, Context, Changes, and Verify. +This description uses three optional sections because the fix has a visible before and after, a real alternative, and two things still open. A docs fix usually keeps only the opening paragraph, Context, Changes, and Verify. ## A contribution to someone else's project -The same fix, sent to a project the contributor does not maintain. The opener comes first, the link line references only that project's issue, and the Comparison is text because attaching media needs push access. +The same fix, sent to a project the contributor does not maintain. The introduction comes first, the link line references only that project's issue, and the Comparison is text because attaching media needs push access. ```markdown -I run this for a small tea shop's catalogue, and customers on phones kept reporting empty searches. +I run this for a small tea shop's catalog, and customers on phones kept reporting empty searches. -Fix, 14 lines in two files; search results change for queries that end in a space. +Fixes search for queries that end in a space, which returned no results. Results for every other query are unchanged. Closes #208 diff --git a/skills/skillset.lock b/skills/skillset.lock index 1505581..88e2ce6 100644 --- a/skills/skillset.lock +++ b/skills/skillset.lock @@ -64,9 +64,9 @@ ], "kind": "standalone-skill", "name": "pr-craft", - "outputHash": "sha256:f8a435bbad29853594f927057babd45e565d5989088591298395265e5ad92afb", + "outputHash": "sha256:b02e85bb2df1fe2d88cc627ab3cddf9c0fbda194d4c63ea78dd4333a3b32deec", "outputPath": "pr-craft/SKILL.md", - "sourceHash": "sha256:bf7c5096e183ed65e3625058e4019f02c585e47b9638cef3a82c6b4ff88978bf", + "sourceHash": "sha256:6edc627855c0b6650175d67b485330a0ca69a1569d958ea0c1719fc8d85b939b", "sourcePath": ".skillset/skills/pr-craft/SKILL.md", "version": "0.1.0" }, @@ -137,7 +137,7 @@ } ], "outputRoot": "skills", - "provenanceHash": "sha256:ea0442242fc52b6665306c4b55c364fb2167f4c5aac1e04fa0d4e8f2c4a41395", + "provenanceHash": "sha256:aeb9de9d1f893b937c2053bd0b9b55d068dfad1cffa30e74b52f6428cef473e9", "renderResults": [ { "destination": "skill",