Add optional review aids to change drafts

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 include compact sketches and existing before/after evidence. Pull request drafts may also describe rollback difficulty and affected people or systems, distinguishing code reverts from data changes or external effects. These additions remain 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.9.0
 
 ### Changed

docs/usage.md

@@ -142,7 +142,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 useful, a pull request or change summary may include a compact sketch or existing before/after evidence. A pull request may also describe rollback difficulty and affected people or systems. 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.
 

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, these additions are optional. Include them only when they help the reader decide faster. Skip repetition and speculation.
+
+- Include the smallest useful diff, tree, or before/after sketch beside the point it supports.
+- For behavior changes, use existing evidence from authorized work to show the observed before and after. Mark any unobserved side as unverified. Additional checks need a reason within the authorized task.
+- For a pull request, describe rollback difficulty and who or what could be affected when this matters to the merge. Distinguish reverting code from undoing data changes or external effects.
+
 Do not score style, assess whether text appears AI-written, or trade necessary evidence for brevity.

tests/policy.test.mjs

@@ -85,6 +85,13 @@ test("review and delegation preserve user authority", () => {
   }
 });
 
+test("change communication keeps review aids optional and uses existing evidence", () => {
+  const communication = read("skills/efficiency/references/change-communication.md");
+  assert.match(communication, /these additions are optional/i);
+  assert.match(communication, /use existing evidence from authorized work/i);
+  assert.doesNotMatch(read("rules/response-simplicity.mdc"), /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);