From 61cdc118ea3ab13b1d0e6cfd9bbc5809ca4b3a85 Mon Sep 17 00:00:00 2001 From: William Bezuidenhout Date: Mon, 4 May 2026 10:56:47 +0200 Subject: [PATCH] chore/dev: add the pr commit writing skill from sourcegraph --- .../skills/writing-prs-and-commits/SKILL.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 .agents/skills/writing-prs-and-commits/SKILL.md diff --git a/.agents/skills/writing-prs-and-commits/SKILL.md b/.agents/skills/writing-prs-and-commits/SKILL.md new file mode 100644 index 0000000000..a722b1b0d2 --- /dev/null +++ b/.agents/skills/writing-prs-and-commits/SKILL.md @@ -0,0 +1,58 @@ +--- +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. + +## PR titles + +- Keep titles short, specific, and verb-first. +- Prefer Sourcegraph's changelog-friendly shape when it fits the change: `type/domain: title`. +- Use conventional prefixes like `feat`, `fix`, `remove`, and `chore` when they match the change. +- Make the title describe the improvement or behavior change, not just the bug report. +- If the PR is user-visible and likely to feed the changelog, choose a domain that reflects the product or feature area rather than an implementation detail. + +## PR descriptions + +- Write the opening prose in this order: + 1. Why this change is needed. + 2. What changed. + 3. Any important tradeoffs, rollout notes, or follow-up context. +- When relevant, reference linked Linear issues or related Slack threads. +- If docs or handbook follow-up is needed, mention it in the prose before the verification section. +- Include `## Test Plan` near the end when there is meaningful validation to report. +- The test plan should mention intentional verification such as focused tests, manual flows, or reproduction steps. Do not pad it with routine formatting or CI work the repository already expects. +- Include `## Changelog` only for end-user-visible changes worth communicating outside the PR. Keep it as the last section. Omit it for refactors, tooling, internal cleanup, or other changes with no user-facing impact. + +## Commit messages for single-PR changes + +Treat a single commit that is intended to become one PR as a PR. GitHub by default will use the title and body from the commit. + +## Workflow + +1. Inspect the diff, linked context, and any existing PR title, body, or commit message. +2. Decide whether you are creating a new PR, editing an existing PR, or writing a stand-alone commit message. +3. Draft the title and body so the motivation is clear before the implementation details. +4. Check that the text matches the net change, preserves important existing content, and follows Sourcegraph conventions for `Test Plan` and `Changelog`. +5. Apply the final text with `gh pr create`, `gh pr edit`, or `git commit` as requested.