writing-prs-and-commits

name	writing-prs-and-commits
description	Writes and revises Sourcegraph pull request titles, descriptions, and single-PR commit messages. Use when creating or updating a pull request, or when preparing a commit that should stand on its own as the eventual PR.

Writing PRs and commits

Use this skill when the user asks to create a PR, update an existing PR title or body, or write a commit message for a change that maps cleanly to one PR.

Resolve the target

• If the user names a PR number or URL, use that.
• Otherwise, inspect the current branch and use gh pr view --json number,title,body,baseRefName,headRefName,url to find the associated PR.
• If no PR exists and the user wants one created, use gh pr create, then immediately verify or adjust the title and body.
• If the user wants text only, provide the draft without mutating GitHub.
• When a PR is part of a stack, describe only the net change between the PR head and its base branch. Do not describe the full stack relative to main.

Core writing rules

• Lead with why. The first paragraph or sentence should explain the problem, motivation, or user impact.
• Follow with what changed. Once the reader understands why the change exists, describe the solution and any important constraints or tradeoffs.
• Write the net change only. Do not document abandoned experiments, reverted approaches, or temporary dead ends.
• Prefer natural prose over rigid Summary / Problem / Solution headings unless the user explicitly asks for that format.
• Keep references repo-relative. Do not mention absolute local filesystem paths.
• Preserve valuable existing PR content such as screenshots, images, rollout notes, and manually written context unless the user asks to remove it.
• Use Markdown cleanly: inline code in backticks, fenced blocks when needed, and GitHub permalinks when citing specific code.