ref(pr-writer): Rebuild the guidance around the cover note

README.md

@@ -59,7 +59,7 @@ Works with Claude Code, Cursor, Cline, GitHub Copilot, and other compatible agen
 | [iterate-pr](skills/iterate-pr/SKILL.md) | Iterate on a PR until CI passes and actionable review feedback is addressed. |
 | [presentation-creator](skills/presentation-creator/SKILL.md) | Create data-driven presentation slides using React, Vite, and Recharts with Sentry branding. |
 | [pr-link-issue](skills/pr-link-issue/SKILL.md) | Append a GitHub issue link and its Linear ticket to the current PR's description. |
-| [pr-writer](skills/pr-writer/SKILL.md) | Create, refresh, and rewrite pull request titles and descriptions following Sentry conventions. |
+| [pr-writer](skills/pr-writer/SKILL.md) | Write a pull request title and body as a cover note for reviewers. |
 | [prompt-optimizer](skills/prompt-optimizer/SKILL.md) | Optimize prompts with evals, model-family adapters, and exact external context references. |
 | [replay-ux-research](skills/replay-ux-research/SKILL.md) | Analyze Sentry session replays to surface UX patterns, pain points, and user journeys for a given product area. |
 | [security-review](skills/security-review/SKILL.md) | Security code review for vulnerabilities. |

skills/pr-writer/EVAL.md

@@ -58,3 +58,4 @@ Adopt a `pr-writer` change only when:
 3. output title uses an allowed conventional type.
 4. output body avoids default `Summary` / `Test Plan` templates.
 5. validation is omitted unless it changes reviewer risk.
+6. output body paragraphs are single unwrapped lines.

skills/pr-writer/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: pr-writer
-description: Create or refresh reviewer-facing PR titles and descriptions. Use when opening a PR, updating its title or body, or preparing branch changes for review.
+description: Write a PR title and body as a cover note for reviewers. Use when opening a PR or refreshing an existing one's title or body.
 ---
 
 # PR Writer
 
-Write the PR body as a cover note for reviewers, not a changelog, template,
-validation log, or file-by-file summary.
+A PR body is a cover note for reviewers: what changed, what it affects, and
+where to look.
 
 ## Inspect the Change
 
@@ -26,23 +26,30 @@ repository default branch. Set `BASE`, then inspect:
 
 ```bash
 git log "$BASE"..HEAD --oneline
+git diff --stat "$BASE"...HEAD
 git diff "$BASE"...HEAD
 ```
 
-If on `main` or `master`, create a feature branch first. Ensure intended
-changes are committed and review the whole branch diff, not only the latest
-commit or existing PR text.
+If on `main` or `master`, create a feature branch first. Commit the intended
+changes, then read the whole branch diff. The `--stat` total is the budget the
+cover note is written against.
 
 ## Core Rules
 
-- Describe concrete changed behavior, affected surfaces, and reviewer impact
-  before implementation detail.
-- Explain motivation, risk, tradeoffs, migration, or review focus only when
-  useful.
+- Lead with concrete changed behavior, affected surfaces, and reviewer impact;
+  implementation detail comes after, if at all.
 - Use the smallest structure that makes the change easier to review.
+- Match length to the diff: a body that takes longer to read than the diff
+  takes to review has failed. Every paragraph carries something the diff does
+  not show — root cause, rationale, risk, migration, or where to start. Cut
+  the ones that restate what the reviewer is about to read.
+- Write each body paragraph as one long line, with a blank line between
+  paragraphs. GitHub renders an intra-paragraph newline as a line break, so a
+  hard-wrapped body breaks raggedly at the source column. Fenced code blocks
+  keep their newlines.
 - Replace internal prompt or process terminology with specific behavior.
-- When refreshing a PR, rewrite around the current full diff without narrating
-  review history.
+- When refreshing, rewrite around the current full diff: the cover note
+  describes the PR as it now stands, not the revisions that got it there.
 
 ## Titles
 
@@ -55,8 +62,8 @@ Allowed types: `feat`, `fix`, `ref`, `perf`, `docs`, `test`, `build`,
   and scope.
 - Use `!` only when the change breaks an external contract, and explain the
   affected surface in the body.
-- Avoid vague subjects such as `update`, `cleanup`, `misc`, `fix stuff`,
-  or `address feedback`. Do not add a trailing period.
+- Name the specific behavior that changed in the subject, with no trailing
+  period.
 - Keep an existing title only when it still describes the whole diff.
 
 ## Body Shape
@@ -79,9 +86,6 @@ Default:
 <Why the approach, risk, migration, or review focus matters, if not obvious.>
 ```
 
-For review-feedback updates, describe the resulting PR as a whole rather than
-the sequence of revisions.
-
 ## Reviewer Aids
 
 Use an aid only when it reduces reviewer reconstruction work:
@@ -93,16 +97,15 @@ Use an aid only when it reduces reviewer reconstruction work:
   adopters need it.
 
 Introduce an artifact with one sentence explaining what reviewers should
-notice. Omit it when prose is clearer.
+notice.
 
 ## Boundaries
 
-- Do not add default `Summary`, `Changes`, or `Test Plan` sections.
-- Omit routine validation unless it changes risk assessment or explains
-  meaningful regression coverage. For docs, skills, copy, or config changes,
-  omit it by default.
-- Do not paste commands, CI logs, validation dumps, commit logs, placeholders,
-  or exhaustive file lists.
+- The cover note carries prose plus, when earned, one aid. Command output, CI
+  logs, commit logs, placeholders, and file lists stay out; include validation
+  only when it changes risk assessment or shows meaningful regression coverage.
+- Write the body from the diff, ignoring any repository PR template, and skip
+  default `Summary`, `Changes`, and `Test Plan` headings.
 - Never include customer or organization names, user emails, support ticket
   contents, secrets, or PII.
 - Use issue references only when verified from user input, branch names,
@@ -134,17 +137,13 @@ typo-only, formatting-only, and rename-only follow-ups.
 Small change:
 
 ```markdown
-The AI Customizations section now starts collapsed so it does not consume
-sidebar space before users need it. Expanding it preserves the existing saved
-preference behavior.
+The AI Customizations section now starts collapsed so it does not consume sidebar space before users need it. Expanding it preserves the existing saved preference behavior.
 ```
 
 Breaking contract:
 
 ````markdown
-Run logs now emit chunk-level records instead of one skill-level record.
-Consumers that read top-level `findings` must iterate over
-`chunk.findings` for each record.
+Run logs now emit chunk-level records instead of one skill-level record. Consumers that read top-level `findings` must iterate over `chunk.findings` for each record.
 
 Before:
 

skills/pr-writer/SPEC.md

@@ -36,11 +36,13 @@ Out of scope:
 
 ## Runtime Contract
 
-- Required first actions: verify the current branch, committed state, base branch, and diff scope before writing or updating a PR; when updating, use the PR's `baseRefName` as the base branch and inspect the current PR title and body before deciding what to keep.
+- Required first actions: verify the current branch, committed state, base branch, and diff scope before writing or updating a PR; read `git diff --stat` for the branch, since the diff total is the budget body length is calibrated against; when updating, use the PR's `baseRefName` as the base branch and inspect the current PR title and body before deciding what to keep.
 - Required outputs: a conventional PR title and a concise, natural PR body suitable for `gh pr create` or GitHub API update commands; on updates, include an explicit keep-or-rewrite decision for the title.
 - Required body-shape decision: decide whether the change is small/obvious, bug fix, feature, refactor, API/schema/payload/config/CLI change, breaking change, migration, performance/reliability change, broad/generated/cross-cutting change, UI change, workflow/architecture change, or review-feedback update. Use the decision to select the minimum useful structure.
 - Required update behavior: if an open PR exists and follow-up commits materially change reviewer expectations, refresh the PR even when the user did not explicitly ask for a PR edit.
 - Optional reviewer aids: use before/after blocks for contract or behavior comparisons; schemas or interface snippets for API, payload, type, config, event, or storage changes; Mermaid sequence/flow/state diagrams for async flows, queues, state transitions, lifecycle changes, or multi-component interactions; screenshots or recordings for UI behavior; review-order notes for broad or generated PRs; rollout, migration, compatibility, feature-flag, or deprecation notes for changes that affect adopters or operations.
+- Required output formatting: emit each body paragraph as one unwrapped line separated by blank lines, since GitHub renders an intra-paragraph newline as a line break; fenced code blocks are exempt.
+- Required length calibration: a body that takes longer to read than the diff takes to review is a defect; every paragraph must carry something the diff does not show (root cause, rationale, risk, migration, review order), and paragraphs that restate the diff are cut.
 - Hard negatives: do not add a `Test Plan` section by default, do not paste command transcripts, do not list routine validation as its own heading unless it changes risk assessment, do not add empty template headings, do not narrate every file, do not include Mermaid when prose is clearer, and do not include schemas or examples that merely duplicate obvious code.
 - Non-negotiable constraints: never include customer data or PII, never invent issue references, ignore repository PR templates, and prefer draft PRs for newly opened pull requests.
 - Expected bundled files loaded at runtime: only `SKILL.md`.

skills/pr-writer/evals/scenarios/concise-docs-pr.json

@@ -4,19 +4,23 @@
   "judge": [
     {
       "check": "The title uses an allowed conventional commit type, preferably docs, and accurately describes the docs-only skill guidance change.",
-      "weight": 0.3
+      "weight": 0.25
     },
     {
       "check": "The body is concise reviewer-facing prose that explains the behavior impact of the guidance without file-by-file narration.",
-      "weight": 0.3
+      "weight": 0.25
     },
     {
-      "check": "The body does not include default template headings such as Summary or Test Plan.",
+      "check": "Each body paragraph outside a fenced code block is a single unwrapped line, with no hard wrapping at a fixed column.",
       "weight": 0.2
     },
+    {
+      "check": "The body does not include default template headings such as Summary or Test Plan.",
+      "weight": 0.15
+    },
     {
       "check": "The body does not include validation command dumps unless tied to reviewer risk.",
-      "weight": 0.2
+      "weight": 0.15
     }
   ],
   "setup": [