[sourcehawk]

Description

Fixes #102

When an agent wrote or reconciled a PR body, each change line named a component and what it does, such as "The scheduler checks a finished job again every 10 minutes". The reader could not tell what they would see differently, and the user had to correct the body by hand. The change guidance in both PR templates now asks for the difference that a user, an operator, or a calling system will notice, and for what it replaces. It leaves the sentence shape to the agent, so the lines do not all read as one "now X, before Y" pattern.

Changes

• A change line in a draft or ready PR body now says what a reader of the PR will see differently, and what that replaces. Before, the lines described which component changed and how, and the outcome was missing or came only in a trailing clause.
• A reconciled body no longer turns each new commit into a summary of its code change. "Match the diff" in the reconcile step now means that the body's claims hold for the branch.
• The lines in one body no longer take a single fixed shape. The templates say how each kind of change often reads best: a fix from the symptom it ends, a new capability from what it lets the reader do, a changed default from the old value to the new one.
• A new anti-pattern, "Change lines that retell the diff", carries the title's mechanic rule into the body.
• The Linux Python 3.9 test job passes again. Before, it failed at setup on every PR, because ubuntu-latest now resolves to Ubuntu 26.04 and actions/setup-python has no Python 3.9 build for it. That job now runs on ubuntu-24.04.

Testing

I used the RED → GREEN loop from superpowers:writing-skills. Each run was an isolated subagent that read only the skill, its two templates, and a scenario. The draft scenario is the reproduction from #102: reconcile a draft body after three fix commits. The ready scenario flips the same PR to ready from four commits.

• RED, the skill on main, 8 runs (5 draft, 3 ready): all 3 ready runs failed the predicate in opening-a-pull-request: PR body change lists describe code changes instead of behavior outcomes #102. They wrote lines such as "The failure path sets status.phase…" and "The scheduler checks a finished job again every 10 minutes", with no before state. 1 of 5 draft runs failed outright. The other 4 led each line with the component and its mechanism and added the outcome only as a "so…" clause.
• GREEN, first wording, 8 runs: 8 of 8 passed the predicate. But every run gave every line the same "X now does Y. Before, Z." shape, which the issue asks to avoid.
• REFACTOR, this branch, 8 runs: 8 of 8 passed the predicate, and the sentence shapes varied more ("instead of showing nothing", "no longer stays in Running forever", symptom-first lines). "now X. Before, Y." is still the most common shape.

A line about the periodic re-check still often leads with the mechanism ("A finished job is checked again every 10 minutes") and then gives the symptom that it ends. It passes the predicate, so I stopped there instead of adding more wording.

The JSON in .claude-plugin/ parses. No script changed. The workflow change is checked by this PR's own CI run.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

No active review issues are blocking approval of the PR guidance and template updates.

No open issues 🎉

What changed in this PR

Addresses #102 by updating the PR-writing skill and templates to emphasize observable outcomes rather than summaries of code changes.

Changes:

• Draft and ready PR guidance asks for what users, operators, or calling systems will notice, including the previous behavior when applicable.
• Templates encourage sentence shapes suited to each change rather than a repeated “now/before” formula.
• Reconciliation guidance clarifies that claims must match the branch without retelling the diff, reinforced by a new anti-pattern.

File	Description
skills/​opening-a-pull-request/​templates/​pull-request-ready.md	Guides ready PR bullets toward observable outcomes and relevant prior behavior.
skills/​opening-a-pull-request/​templates/​pull-request-draft.md	Applies outcome-focused guidance to planned and in-progress changes.
skills/​opening-a-pull-request/​SKILL.md	Clarifies body reconciliation and discourages mechanism-first change lines.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are blocking approval.

No open issues 🎉

_{Review effort: Balanced}