Skip to content
Merged
Show file tree
Hide file tree
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
7 changes: 7 additions & 0 deletions .github/workflows/script-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,14 @@ jobs:
matrix:
os: [ubuntu-latest, macos-latest]
python: ["3.9", "3.x"]
# actions/setup-python has no Python 3.9 build for Ubuntu 26.04, the
# image behind ubuntu-latest. 3.9 is end of life, so none will come.
exclude:
- os: ubuntu-latest
python: "3.9"
include:
- os: ubuntu-24.04
python: "3.9"
# The interpreter that ships with the developer tools of macOS.
- os: macos-latest
python: system
Expand Down
3 changes: 2 additions & 1 deletion skills/opening-a-pull-request/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,14 +101,15 @@ Opening and flipping aren't the only moments the body has to be true. Commits la

The mechanic:

1. **Rewrite the affected sections** from the template the PR already uses (draft or ready) so they match the diff. Leave the opening issue-link keyword and the title unchanged — neither the linkage nor the type/area changed. Do not flip the lifecycle state; this is a body edit, not a `gh pr ready`.
1. **Rewrite the affected sections** from the template the PR already uses (draft or ready) so they describe what the branch does now. "Match the diff" means the body's claims hold for the branch, not that the body retells the diff: each new commit's change is written as the template asks, as a difference a user or an operator will notice, with what it replaces. Leave the opening issue-link keyword and the title unchanged — neither the linkage nor the type/area changed. Do not flip the lifecycle state; this is a body edit, not a `gh pr ready`.
2. **Confirm the exact body** (§Core principle) — paste it inline under an "About to update #<num>'s body to match the diff — body only, PR stays as-is. Confirm?" line, and wait for an explicit yes. Under a standing grant for PR body edits, skip the prompt and show the new body in your reply.
3. **Run the single mutation** once confirmed: `gh pr edit <num> --body "$(cat <<'EOF' … EOF)"`.

## Anti-patterns

- **Lifecycle suffix in PR titles** (`... wip`, `... draft`, `... scaffolding`). The title outlives the state that named it. The body and GitHub's chip carry lifecycle; the title doesn't need to.
- **Mechanic-first titles** (`... move the check above the lookup`, `... reorder the gates`, `... extract the handler`). They describe the code motion, which is the one thing the diff already shows. Lead with the effect or the cause (§PR title).
- **Change lines that retell the diff** (`The handler reads the timeout from the config`, `The sync loop re-queues each entry every 10 minutes`). The title's mechanic failure, one level down: each line names a component and what it does, and the reader still cannot tell what they will see differently. Write each line as the difference a user or an operator will notice, and what it replaces (the template's guidance for `## What lands here` or `## Changes`).
- **`Challenges` as the body's overflow section.** Consequences, tradeoffs, follow-up work, and the history of review rounds all get filed there because the heading is sitting in the template. Each has a home: the Description's third part, `Related`, or the commits. The section earns its place only when the diff hides a system fact a reviewer needs — otherwise the heading gets deleted.
- **Flipping ready with the draft body unchanged.** Different shape, different audience. Rewrite from the ready template.
- **Marking ready before the Testing section is filled in.** That section is what gives the reviewer confidence the PR is shippable; leaving it blank silently drops the claim.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,9 @@ Open with ONE of these as the FIRST line of this section, depending on what shou
- `Towards #<num>` — the PR contributes to the issue but does NOT auto-close it; the issue stays open. Used for sub-PRs into a feature branch and for any other "in progress on this, not finishing it" case.
Omit the line entirely if there is no tracking issue.

Then follow with 1-3 sentences forecasting the changes this PR will introduce. Human-readable; treat it as the early-visibility surface for reviewers who might want to flag direction issues now rather than at review time.
Then follow with 1-3 sentences or bullets on the outcomes this PR delivers, or will deliver while the work is still in flight. Treat it as the early-visibility surface for reviewers who might want to flag direction issues now rather than at review time.

Each outcome is a difference that a user, an operator, or a calling system will notice: what they get with this PR and, when it replaces something they had, what that was. Write it from where they stand. The subject is what they see (a request, a record, a status, an alert), not the component or code path that does the work; the diff and the commits already carry which code changed and where. Fit each sentence to its change rather than one pattern for every line: a fix often reads best from the symptom it ends, a new capability from what it lets them do, a changed default from the old value to the new one.
-->

## Related
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,9 @@ Write it for a dev arriving without context. Lean on Changes (below) for the "wh
## Changes

<!--
Over-arching changes that affect behavior or user-visible surface. Don't list "renamed foo to bar" or file-level diffs unless they are genuinely the headline change. Bullets, one line each, lead with the biggest.
The outcomes this PR delivers. Bullets, one line each, lead with the biggest.

Each bullet is a difference that a user, an operator, or a calling system will notice: what they get with this PR and, when it replaces something they had, what that was. A new user-visible surface (a flag, an endpoint, a setting) counts: name it and what it lets them do. Write it from where they stand. The subject is what they see (a request, a record, a status, an alert), not the component or code path that does the work; the diff and the commits already carry which code changed and where. Fit each sentence to its change rather than one pattern for every bullet: a fix often reads best from the symptom it ends, a new capability from what it lets them do, a changed default from the old value to the new one.
-->

## Challenges
Expand Down
Loading