From 5944aff877758d1ccb2a74eceb94d9ae89124f21 Mon Sep 17 00:00:00 2001 From: Sameer Pashikanti Date: Mon, 25 May 2026 19:10:42 +0200 Subject: [PATCH] docs(github-pr-workflow): require system-consequence section in every PR MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every PR (Sam's repo or any work repo) now opens with a concrete account of what changes in the running system because of this PR. One line per observable change, consequence-first, artifact at end-of-line. Reviewers can decide without opening the diff; future readers searching `git log` find what each PR did in prose, not by diffing files. Ties to the README's first motivation — writing requirements at the same abstraction level as code lands HERE: the PR description is where the new requirement / capability / constraint gets stated in operator-level prose. Skip only for typo fixes and one-line doc edits. --- src/skills/github-pr-workflow/skill.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/src/skills/github-pr-workflow/skill.md b/src/skills/github-pr-workflow/skill.md index f0b3644..42b40ab 100644 --- a/src/skills/github-pr-workflow/skill.md +++ b/src/skills/github-pr-workflow/skill.md @@ -81,6 +81,28 @@ Always draft on work repos (`dembrane/echo`, etc.). PRs stay drafts until Sameer PR descriptions fit the work. A one-line typo fix gets a one-line description. A migration PR gets more. There's no required structure — write what the reader needs to understand the change. +## PR description — what changes in the system + +Every PR (Sam's repo or any work repo) opens with a concrete account of what changes in the running system because this PR merges. Not "I edited file X" — what the operator, a user, a downstream service, or future-Sam observes differently because of this code. + +Daily-maintenance-style: one line per observable change, lead with the consequence, cite the artifact at the end. + +``` +What this changes + +- operator can @sam in any member channel; reply lands in-thread (was: only #sam) — daemon.py, slack.md +- daily broadcasts still route to #sam, no hardcoded ID +- SAM_BROADCAST_CHANNEL env knob removed; one fewer config place +``` + +A reviewer should be able to read those lines alone and decide whether to approve, without opening the diff. + +If the answer is genuinely "nothing user-visible — internal refactor, behavior unchanged," write exactly that. The discipline is in writing the line either way, not in inventing consequences for refactors. + +Skip this section only for typo fixes and one-line doc edits. + +Why this rule exists: the PR description is the place where consequences get written down for future readers — anyone searching `git log` or PR history later finds *what each PR did* by reading the description, not by diffing files. Sam's first README motivation — "writing requirements is at (almost) the same abstraction level as writing code" — lands here: the PR description is where the new requirement, the new capability, the new constraint gets stated in operator-level prose so the next person (or the next Sam) can find it. + ## Labels (sam repo only) When opening a PR on `dembrane/sam`, attach a label per source area the diff touches. This is how reviewers see the tier at a glance without opening the file list.