From 1f6e09abe269ba306750164c1f5541728df9e5fa Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 5 Oct 2026 11:30:39 +0000 Subject: [PATCH] Add optional sketches and merge notes to PR drafts Pull request and change-summary guidance can include the smallest useful sketch, observed before-and-after behavior, and whether the change is easy to revert. The notes stay in the existing change-communication reference and are skipped when they do not help. Adapted from Matt Pocock's /pr skill and Humanlayer's show-me skill. Co-authored-by: Dennis Geldmacher --- CHANGELOG.md | 4 ++++ docs/usage.md | 2 +- .../efficiency/references/change-communication.md | 6 ++++++ tests/policy.test.mjs | 13 +++++++++++++ 4 files changed, 24 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0cb19f4..5381d48 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to this project are documented in this file. ## Unreleased +### Changed + +- Pull request and change-summary drafts may add the smallest useful sketch (a short diff, tree, or before/after), the observed before and after of a behavior change, and a merge note for revert difficulty (a one-way or two-way door) and blast radius. These stay optional in the existing change-communication guidance. Adapted from [Matt Pocock's `/pr` skill](https://github.com/mattpocock/skills/blob/main/skills/engineering/pr/SKILL.md), which builds on [Humanlayer's `show-me` skill](https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md) by Dex Horthy. + ## 3.8.1 ### Changed diff --git a/docs/usage.md b/docs/usage.md index f8f8fea..369afcc 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -136,7 +136,7 @@ Use Efficiency to prepare a commit message, pull request description, release no /efficiency Draft a pull request description from this diff and the checks we ran. Explain the user-visible change and any remaining verification gaps. ``` -The summary follows project conventions and leads with the result. It distinguishes what the diff changes, what checks actually passed, and what is still unverified. This request drafts text; it does not start a code review or an RTK inspection. +The summary follows project conventions and leads with the result. It distinguishes what the diff changes, what checks actually passed, and what is still unverified. When it helps the reviewer decide, a pull request draft may also include the smallest sketch of the change, the observed before and after of a behavior change, and a short note on how hard the change is to revert and how far a bad merge would reach. This request drafts text; it does not start a code review or an RTK inspection. **Example:** “Invalid dates now show a validation message. The parser tests pass; the browser display has not been checked yet.” This tells a reviewer both what changed and the limit of the evidence. diff --git a/skills/efficiency/references/change-communication.md b/skills/efficiency/references/change-communication.md index 3d91afa..f8a3b3a 100644 --- a/skills/efficiency/references/change-communication.md +++ b/skills/efficiency/references/change-communication.md @@ -18,4 +18,10 @@ Identify whether the intended reader must act, decide, or understand. Use exact - Make every material claim traceable to a diff, check, other evidence, or a clearly labelled assumption. - Keep verified behavior, intended behavior, and open work distinct. +For a pull request or change summary, add any of these when it helps the reader decide faster than the prose already required above. Skip an item when it would repeat that prose, guess at an unknown fact, or crowd the decision. + +- When a short diff, a shallow tree, or a compact before/after sketch shows the change faster than prose, include the smallest one beside the point it supports. +- When behavior changes, show the observed before and after: the check, command output, or screenshot that demonstrates it. Call a side unverified when it was not observed. +- For a pull request, name the door and the blast radius when they affect the merge. A two-way door is straightforward to revert. A one-way door is hard to undo, such as a destructive data change or a published contract. The blast radius is who or what a bad merge would affect. A few words are enough unless that consequence is not obvious. + Do not score style, assess whether text appears AI-written, or trade necessary evidence for brevity. diff --git a/tests/policy.test.mjs b/tests/policy.test.mjs index b5d91ab..52e49c4 100644 --- a/tests/policy.test.mjs +++ b/tests/policy.test.mjs @@ -85,6 +85,19 @@ test("review and delegation preserve user authority", () => { } }); +test("change communication keeps sketches and merge notes optional", () => { + const communication = read("skills/efficiency/references/change-communication.md"); + assert.match(communication, /add any of these when it helps/i); + assert.match(communication, /short diff/); + assert.match(communication, /shallow tree/); + assert.match(communication, /observed before and after/); + assert.match(communication, /two-way door/); + assert.match(communication, /one-way door/); + assert.match(communication, /blast radius/i); + assert.match(communication, /unverified/); + assert.doesNotMatch(read("rules/response-simplicity.mdc"), /one-way door|blast radius|change-communication/); +}); + test("advisory branches do not independently authorize execution", () => { for (const name of ["verification-economy", "repeatable-work-economy", "debugging-feedback-economy"]) { assert.match(read(`skills/efficiency/references/${name}.md`), /does not authorize/i, name);