Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions src/skills/github-pr-workflow/skill.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading