[opieter-aws]

Description

The pr-writer skill was producing PR descriptions that ran long and restated the diff instead of explaining the change — heavy on the "what," light on the "why." A reviewer flagged exactly this on #3131. The skill already said "focus on why" and "be concise," but that guidance was abstract and buried among many rules, so it didn't reliably shape the output.

Related Issues

Prompted by review feedback on #3131.

Documentation PR

None

Type of Change

Other (please describe): Updates the pr-writer contributor skill (agent tooling guidance). No product code or site docs.

Testing

Ran the updated skill against the diff from #3131 — the PR that triggered the feedback — across 10 independent generations. Descriptions came out consistently why-first and concise, averaging ~100 words versus ~370 in the original. The first pass surfaced one leak: fixture/mock narration was relocating into the Testing section rather than disappearing. The rule was broadened to cover the whole PR, which is the state here.

(No hatch run prepare — this is a skill-doc change with no Python surface, so that gate doesn't apply.)

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Assessment: Approve

Focused, low-risk change to the pr-writer skill that turns abstract "be concise / focus on why" guidance into concrete, actionable rules, backed by empirical testing (10 generations, ~100 vs ~370 words). Correctly scoped as a docs/skill change with no product surface, so no API review is needed.

Review Categories

• Scope & structure: Small (+8/-2), well-contained; new step 5 numbering and section placement are consistent with the existing Process flow.
• Content quality: The new What/Keep-it-short/Trim-Pass rules are specific and reviewer-oriented. One suggestion inline about the anti-narration rule being repeated across three sections — consolidate or keep intentionally as a reliability lever.
• API bar raising: N/A — no public API surface touched.
• Testing: N/A for a skill-doc change; author's iteration-based validation and the fixture-leak fix are reasonable evidence the guidance behaves as intended.

Nice job pairing the wording change with actual before/after generation data rather than just asserting it reads better.