# SkillPatch skill: pr-writer This skill guides an agent in creating, refreshing, and rewriting pull request titles and descriptions following Sentry conventions. It provides detailed rules for classifying PR types, structuring PR bodies, writing plain-language titles, and using optional reviewer aids like before/after comparisons, Mermaid diagrams, and schema snapshots. The skill ensures PRs are written as reviewer-facing cover notes rather than changelogs or file-by-file summaries. You (the agent) were given this URL and asked to use this skill. This is a **public** skill — no SkillPatch account, API key, or prior setup is required. Two ways to use it: **1. Use it right now** — the skill's complete file tree (SKILL.md + all reference files) is inlined below; read `SKILL.md` first, then follow it, consulting the other files as it directs. **2. Install the exact package onto disk** (recommended if you can run a shell — this reproduces the skill byte-for-byte, including any binary assets that can't be inlined): ```bash mkdir -p .claude/skills/pr-writer curl -sSL https://skillpatch.dev/install_skill/pr-writer | tar -xz -C .claude/skills/ ``` (`.claude/skills/` is Claude Code's convention; use whatever directory your agent loads skills from.) --- ## Skill files (2) - `SKILL.md` - `SPEC.md` ### `SKILL.md` `````markdown --- name: pr-writer description: Create, refresh, and rewrite PR titles and descriptions following Sentry conventions. Use when opening a PR, writing or updating a PR title/body/description, refreshing an existing PR after material changes, or preparing branch changes for review. --- # PR Writer Create or refresh PRs with reviewer-facing titles and bodies. The body is a cover note, not a changelog, template, validation log, or file-by-file summary. ## Output Priorities 1. Match the full branch diff against the base branch, not the latest commit or stale PR text. 2. Describe the shape and effect of the change before implementation detail. 3. Explain why, risk, tradeoff, migration, or review focus only when useful. 4. Use the smallest structure that makes review easier. 5. Omit routine validation, unverified issue refs, customer data, PII, placeholders, and tool traces. ## Plain-Language Pass Before creating or updating the PR, reread the title and body as a reviewer. - Name changed behavior, affected surface, and reviewer impact. - Avoid prompt/process words: `decision model`, `expanded contract`, `runtime guidance`, `validation results`, `this PR updates`. - Replace generic sentences with specifics, or delete them. ## Body Shape Classify the PR, then write the minimum useful body. | Shape | Use | |-------|-----| | Small obvious | One concise paragraph; no headings. | | Bug fix | Problem/root cause/fix, plus regression coverage if relevant. | | Feature | New behavior, user/developer effect, and non-obvious approach. | | Refactor | What moved, what behavior stays unchanged, and why it helps. | | API/schema/payload/config/permission/event/storage/CLI | Changed contract plus compact before/after, schema, or interface if clearer than prose. | | Breaking/removal/deprecation | Affected surface, compatibility impact, and migration/rollout guidance when known. | | Performance/reliability | Expected impact, measured numbers when known, and tradeoffs or failure modes. | | UI | User-visible effect; mention screenshots/recordings only when available and useful. | | Workflow/queue/async/state/multi-service | Flow summary; use a small Mermaid diagram only if prose is harder to follow. | | Broad/generated/cross-cutting | Organizing principle, why it is broad, and where reviewers should start. | | Review-feedback update | Fresh description of the whole PR diff; no review-history narration. | Default: ```markdown ``` ## Optional Reviewer Aids Use only when they reduce reviewer reconstruction work: - `before/after`: contracts, payloads, config, CLI, or behavior comparisons. - `schema/interface`: new or changed API response, type, event, storage record, config, or payload surface. - `mermaid`: async flows, queues, retries, lifecycle, state transitions, or multi-component interaction. - `screenshot/recording note`: visual UI changes when evidence exists. - `review order`: broad, generated, mechanical, or layered diffs. - `rollout/migration/compatibility/deprecation note`: adopters or operators must adjust or watch risk. - `risk/tradeoff callout`: known limits, chosen cost, or changed failure mode. Avoid aids that duplicate obvious code, decorate the body, or make prose less clear. Put one sentence before an artifact telling reviewers what to notice. ## Titles Format: `(): ` or `: `. For breaking changes, use `()!: ` or `!: ` and explain the affected surface in the body. Allowed types: `feat`, `fix`, `ref`, `perf`, `docs`, `test`, `build`, `ci`, `chore`, `style`, `meta`, `license`, `revert`. Rules: - Describe the dominant change, not the latest commit. - Use the narrowest accurate type and scope. - Use `!` only for breaking contract, migration, removal, or compatibility changes that reviewers and adopters need to notice. - No bracketed labels: `[codex]`, `[claude]`, `[ai]`, `[bot]`, `[wip]`. - No agent, tool, or automation attribution. - No vague titles: `update`, `cleanup`, `misc`, `fix stuff`, `address feedback`. - No trailing period. Examples: ```text fix(replay): Paginate recording segment downloads feat(api)!: Emit chunk-level run log records ``` When updating a PR, keep the current title only if a reviewer reading it alone would expect the whole branch diff against the base branch. ## Hard Negatives - No default `Summary`, `Changes`, or `Test Plan` template. - No empty headings, placeholders, `TODO`, `XXXXX`, or ``. - No pasted command transcripts, CI logs, or validation dumps. - No "tests passed" or validator summary unless it changes reviewer risk assessment or explains coverage for changed behavior. - No copied commit log. - No file-by-file narration unless needed for review order. - No agent trace links or "action taken on behalf" lines. - No customer/org names, user emails, support ticket contents, secrets, or PII. For docs, skill, copy, config, or other non-runtime changes, default to omitting validation entirely. ## Examples ### Small ```markdown The AI Customizations section in the sessions sidebar now starts collapsed so it does not consume space before users need it. Expanding the section keeps the same persisted preference behavior as before. ``` ### Bug Fix ```markdown Inactive authenticated users now go through account reactivation before the login view honors a `next` URL. The GET login path previously redirected authenticated users without checking `is_active`, which could bounce an inactive user between `/auth/login/` and a protected view. The POST path already handled this case, so this applies the same guard to GET and covers the loop with a regression test. ``` ### Breaking Contract ````markdown Run logs now emit chunk-level records instead of one skill-level record with all findings. Consumers that read top-level `findings` need to iterate over `chunk.findings` for each record instead. Before: ```jsonc {"skill": "security-review", "findings": [...], "files": [...]} ``` After: ```jsonc {"schemaVersion": 1, "chunk": {"index": 1, "total": 2, "findings": [...]}} ``` ```` ### Workflow ````markdown Replay export now retries failed segment uploads without restarting the whole export. Successful segments stay committed, and the worker only requeues the failed segment with the existing retry limit. The changed flow is: ```mermaid sequenceDiagram participant Worker participant Storage participant Queue Worker->>Storage: upload segment Storage-->>Worker: transient failure Worker->>Queue: requeue segment retry ``` ```` ### Broad Or Generated ```markdown The TypeScript API fixtures were regenerated from the updated OpenAPI schema so client tests match the current response shapes. The generated files stay in this PR because the schema and fixture updates are easiest to review together. Review the schema diff first, then treat the fixture changes as generated output from that contract change. ``` ### Docs Or Skill Change ```markdown The `pr-writer` skill now steers PR descriptions toward the full branch diff instead of the latest commit or a generated template. Small changes should stay short, while breaking changes, schema updates, generated diffs, and workflow changes get the extra context reviewers need. Schemas, before/after examples, Mermaid diagrams, rollout notes, and review order are treated as optional reviewer aids, not default sections. Routine validation stays out of PR bodies unless it changes review risk. ``` ### Anti-Pattern: Validation Dump ```markdown ## Summary - Updated files - Added tests ## Test Plan - pnpm test - pnpm lint ``` Corrected: ```markdown Project creation now rejects duplicate slugs before writing the project row, which prevents the follow-up task from enqueueing work for a project that will roll back. The regression test covers the duplicate-slug path that previously raised after the task was already scheduled. ``` ## Workflow Requires authenticated `gh`. Inspect branch, status, base branch, commits, and diff. For existing PRs, set `BASE` from `baseRefName`; for new PRs, use the repo default branch: ```bash git branch --show-current git status --porcelain BASE=$(gh pr view --json baseRefName --jq '.baseRefName' 2>/dev/null || gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name') git log BASE..HEAD --oneline git diff BASE...HEAD ``` If on `main` or `master`, create a feature branch first. Ensure intended changes are committed and the diff is reviewable as one PR. For existing PRs, inspect current text and use `baseRefName` as `BASE`: ```bash gh pr view PR_NUMBER --json number,title,body,url,baseRefName,headRefName ``` Refresh when follow-up commits change scope, implementation approach, breaking behavior, risk, or final review expectations. Skip typo-only, formatting-only, or rename-only follow-ups. Rewrite the body around the whole PR diff; do not append review-history notes. Create draft PR: ```bash gh pr create --draft --title "(): " --body "$(cat <<'EOF' EOF )" ``` Update existing PR: ```bash gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \ -f title='fix(scope): Preserve replay segment cursor' \ -f body="$(cat <<'EOF' EOF )" ``` Use `gh api` for PR updates. ## Issue References Use only when verified from user input, branch name, commits, PR comments, or tracker output. | Syntax | Effect | |--------|--------| | `Fixes #1234` | Closes GitHub issue on merge | | `Fixes SENTRY-1234` | Closes Sentry issue | | `Refs GH-1234` | Links without closing | | `Refs LINEAR-ABC-123` | Links Linear issue | These are syntax examples. Do not copy example IDs into a real PR body. ## Final Check - Title matches the dominant full-branch change and uses `!` for breaking changes. - Body length and structure match change size/risk. - Optional artifacts reduce reviewer effort. - Breaking changes name affected surface and migration/compatibility context. - Routine validation is omitted unless it changes reviewer risk assessment. - Issue references are verified or omitted. - Customer data, PII, tool attribution, and placeholders are absent. ````` ### `SPEC.md` ```markdown # PR Writer Specification ## Intent The `pr-writer` skill creates and updates pull requests with concise, review-oriented titles and descriptions that match Sentry conventions. Its main job is to turn branch changes into a reviewer-facing cover note that explains what changed, why it changed, and the few details reviewers need before reading the diff. The output should adapt to the size, risk, and shape of the change: simple PRs should stay terse, while broad, risky, breaking, API/schema, migration, generated, or workflow-heavy PRs should include only the extra structure that makes review easier. The skill should offer the agent a small menu of optional reviewer aids, such as before/after examples, schemas, interfaces, Mermaid diagrams, screenshots, rollout notes, migration notes, review order, or risk callouts. These are decision tools, not required sections. The agent should choose them with simple heuristics and its own judgment, then omit anything that does not materially improve reviewer understanding. ## Scope In scope: - Creating draft pull requests from committed feature branches. - Updating existing PRs by re-evaluating both title and body against the full branch diff against the base branch. - Producing natural PR bodies that default to short paragraphs and use structure only when the change shape needs it. - Choosing optional reviewer aids based on the actual diff shape, including code snippets, payload examples, schemas/interfaces, diagrams, screenshots, review-order notes, rollout notes, migration notes, or risk/tradeoff callouts. - Producing titles that accurately describe the dominant change in the PR. - Rejecting bracketed agent, bot, or tool prefixes in PR titles. - Including issue references, breaking-change context, and review focus when useful and supported by known evidence. Out of scope: - Writing commits or deciding commit history policy. - Running full CI or iterating on failing checks. - Producing release notes, changelogs, or customer-facing announcements. - Including mechanical test-plan checklists in PR bodies. - Mirroring repository PR templates, including empty headings, placeholder checklists, rote "Summary / Test Plan" sections, or validation logs that do not help reviewers understand the change. - Creating decorative diagrams, exhaustive file-by-file walkthroughs, or copied diffs that make the body longer without reducing reviewer effort. ## Users And Trigger Context - Primary users: engineers and coding agents preparing Sentry pull requests. - Common user requests: open a PR, update a PR, refresh a PR after scope changes, address review feedback after follow-up commits, prepare changes for review. - Should not trigger for: code review requests, commit-only requests, CI-fix loops, or generic documentation writing. ## 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 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. - 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 use bracketed agent/tool labels such as `[codex]` in PR titles, never invent issue references, generate reviewer prose rather than tool attribution, ignore repository PR templates, and prefer draft PRs for newly opened pull requests. - Expected bundled files loaded at runtime: only `SKILL.md`. ## Source And Evidence Model Authoritative sources: - Sentry engineering practices for code review. - Sentry commit message conventions. - Repository-level agent instructions. - Google Engineering Practices guidance for CL descriptions. - Git and Linux kernel patch submission guidance. - GitHub pull request reviewability guidance. - GitHub and GitLab Markdown support for Mermaid diagrams in PR/MR descriptions. - GitLab merge request template prior art for before/after visual comparisons and local validation only when useful. - Atlassian pull request guidance on using descriptions, reviewer navigation, and visuals to reduce reviewer reconstruction work. - Conventional Commits and changelog guidance for identifying and communicating breaking changes. - Observed user rejection of programmatic PR descriptions and preference for concise reviewer context. - `getsentry/warden#265` as a formatting exemplar for before/after examples on schema and output-shape changes, only when direct comparison is warranted. Useful improvement sources: - positive examples: PR descriptions that read like a human cover note and give reviewers the missing context. - positive examples: PR descriptions that use optional artifacts sparingly, such as a compact schema/interface, before/after payload, Mermaid flow, screenshot, rollout note, or review-order note when that artifact makes the diff easier to review. - positive examples: PR descriptions that use concrete behavior and reviewer impact instead of meta phrases like "decision model", "expanded contract", or "runtime guidance". - positive examples: PR titles that stay specific after follow-up commits. - negative examples: PR bodies that read like essays, repeat the diff, overuse headings, mirror a template, or leak internal agent process. - negative examples: PR bodies with rote `Test Plan` headings, pasted command output, generic validation details, decorative diagrams, oversized Mermaid blocks, unnecessary schemas, empty headings, or file-by-file narration. - negative examples: PR bodies that read like release notes for the prompt rather than a human cover note for the change. - negative examples: PR titles that are vague, process-oriented, or stale after scope changes. - negative examples: PR titles that use bracketed agent/tool labels instead of conventional commit types, such as `[codex] Paginate replay segment downloads`. - negative examples: branches with material follow-up commits where the agent pushed changes but left the PR title/body stale. - commit logs/changelogs: only as source context, not as body text to paste. - issue or PR feedback: reviewer comments about missing context or excessive detail. - eval results: prompt-based checks for title accuracy, natural reviewer prose, justified structure, verified references, and privacy boundaries. Data that must not be stored: - secrets - customer data - private customer, organization, or user identifiers - support ticket contents not needed for a public PR ## Reference Architecture - `SKILL.md` contains runtime workflow, command patterns, conditional PR body guidance, examples, and safety constraints. - `references/` contains no files currently; add focused style or evidence examples only if the runtime file becomes too long or repeated regressions show the examples need more room. - `references/evidence/` contains no files currently; use it for durable positive and negative PR body examples if iteration data accumulates. - `scripts/` contains no files currently. - `assets/` contains no files currently. ## Evaluation - Lightweight validation: compare generated titles and PR bodies against representative feature, bug-fix, schema-change, breaking-change, migration, UI, performance/reliability, broad-review, generated-change, workflow-diagram, and refactor prompts for brevity, clarity, justified structure, issue references, update-path title handling, and privacy handling. - Deeper evaluation: maintain a small prompt set with expected body shapes if regressions recur. - Holdout examples: include at least one simple PR that should be one paragraph, one bug fix that should explain root cause without file bullets, one PR with no known issue reference, and one API or input-format change that should use separate before/after fenced blocks. - Holdout examples: include at least one breaking contract change that should identify affected consumers and migration guidance, one workflow-heavy PR that should use a compact Mermaid diagram, one UI PR that should mention screenshots or visual evidence only if available, one broad generated PR that should explain generation/review order, and one small PR that must not grow a `Test Plan` or template headings. - Holdout examples: include at least one PR update where the old title no longer matches the whole PR diff and must be rewritten. - Holdout examples: include at least one review-feedback or follow-up-commit scenario where the skill should refresh an open PR without an explicit PR-update request. - Acceptance gates: output title uses an allowed Sentry conventional commit type, uses `!` when the dominant change is breaking, contains no bracketed agent/tool prefix, matches the dominant change, update flows explicitly re-evaluate whether the existing title still fits, material follow-up commits to an open PR trigger a refresh even without an explicit PR-update request, output reads like natural reviewer-facing prose, default body uses paragraphs instead of generic headings, structure is present only when justified by the change shape, optional artifacts are used only when they reduce reviewer effort, body language describes concrete behavior and reviewer impact instead of internal process, breaking changes include affected surface and migration/compatibility context when known, before/after examples appear only when direct comparison is the clearest explanation, unknown issue references are omitted instead of invented, routine validation is omitted unless it changes reviewer risk assessment or explains coverage for changed behavior, generated tool attribution is absent, and customer data is excluded. ## Known Limitations - The skill cannot guarantee that issue references are correct unless the branch, commits, or user provide them. It must omit references rather than invent placeholders. - It relies on the agent's judgment to decide when a heading, bullet list, or before/after block helps reviewers more than plain paragraphs. - It relies on the agent's judgment to decide whether optional reviewer aids, such as schemas, diagrams, screenshots, migration notes, or review-order notes, reduce reviewer effort enough to justify their length. - Mermaid rendering support and syntax differ by platform/version, so diagrams must stay simple and should be omitted when uncertain or not essential. - It relies on the agent's judgment to decide when a title is still accurate enough to keep versus rewrite. - Very large PRs may still need more context than the default body shape encourages. ## Maintenance Notes - Update `SKILL.md` when PR creation workflow, title rules, body template, examples, or safety constraints change. - Update `SPEC.md` when intent, scope, evaluation gates, or evidence policy changes. - Add focused reference files only when examples or guidance would make `SKILL.md` noisy. - Keep public inventories pointed at the canonical `skills/pr-writer` skill, not mirrors. ```