/change-brief

name: change-brief
description: Explain a change that already exists — a pull request, a merged commit, a closed issue's fix, or an uncommitted diff — in terms of the FEATURE it touches and how someone actually uses that feature, then the bug or gap it addresses. Always states who wrote it (Claude in an earlier session, an outside contributor, or the maintainer), right after the opening model and before any mechanism. Use when the user pastes a PR link or number, says explain this PR / what does this PR do / what is 331 / what's this commit / explain these changes / what did you change, asks "in simple words" or "explain the scenario", or wants to understand work they did not write themselves. Always opens with a concrete everyday analogy and a one-sentence plain statement of the defect; plain language is the DEFAULT output, never a mode the user has to ask for. Read-only: it reads the diff, the surrounding code and git history, and never runs the app, never checks out a branch, never edits. NOT for deciding whether to build something not yet written (use /issue-brief) and NOT for finding defects (use /code-review).

change-brief — explain a change that already exists

`/issue-brief` explains something **not yet built**, to decide whether to build it. This skill explains something **already written**, so the reader understands what it does and whether to merge or trust it.

The reader did not write this code. Often nobody they can ask wrote it — it may be an outside contributor's PR, or something Claude produced in a session they have since forgotten. Assume no memory of the change and no file layout in their head.

1. Resolve the target

| They said | Fetch with | |---|---| | PR number or URL | `gh pr view <n> --json number,title,author,body,files,additions,deletions,mergeable,mergeStateStatus,commits` | | "what is 331" (bare number) | Try `gh pr view <n>` first; fall back to `gh issue view <n>` | | commit SHA | `git show --stat <sha>` | | "these changes" / "what did you change" | `git status --short` and `git diff` (plus `git diff --staged`) | | merged issue | `gh issue view <n>`, then find the PR that closed it |

Get the **real** diff, not the description. A PR opened weeks ago is measured against today's base:

git fetch origin main pull/<n>/head:pr<n>
git diff origin/main...pr<n> --stat

A `git diff main...` against a stale local `main` reports hundreds of unrelated files. If the stat looks absurdly large for the PR's description, that is the cause — fetch `origin/main` and re-diff before believing it.

2. Establish authorship — this is not optional

The user asked for this explicitly: **never explain a change without saying who wrote it.** They need to know whether they are reading their own past decision, a contributor's proposal, or Claude's output from a session they don't recall.

It lands in position 2, immediately after the opening model (§3 step 1) and before any mechanism. That is a deliberate change: it used to go first, and a brief that opened with a username, three PR numbers and a timestamp got "explain it clearly, I still didn't understand" in reply. A name means nothing until the reader knows what the thing does. Two lines, still never skipped.

• **The change itself:** `gh pr view <n> --json author`, or

`git log -1 --format='%an <%ae>' <sha>`.

• **Claude's fingerprint:** commits Claude wrote carry a

`Co-Authored-By: Claude` trailer and a `Generated with Claude Code` line. `git log --format='%H %an %s' -- <file> | head` shows who has been touching the area.

• **The underlying feature is usually older than the change.** A PR fixing a

bug in a feature did not create that feature. Attribute them separately: who wrote the feature, who wrote this fix.

State it plainly and without hedging: "Not me — this is <contributor>'s PR. The feature it touches is pre-existing project code, yours." If Claude did write it, say so in the same breath, and in which session or PR.

Never claim authorship you have not checked, and never let "we" blur it.

3. Answer in this order

The first thing on screen is a mental model the reader can hold without knowing the codebase. Not the authorship, not the file, not the constant. If they read only the first six lines, they should be able to state the bug back to you in their own words.

1. **The model and the thesis.** Open with a concrete, everyday analogy for the subsystem, then state the entire defect in ONE bolded sentence of plain words. Then write "That's the whole thing. Everything below is just why."

**Hard budget for this section: zero `file:line`, zero constant names, zero PR numbers, zero usernames, every sentence under 15 words.** If you cannot write the thesis without an identifier in it, you do not yet understand the change well enough to explain it. Go back to the diff.

Where the system has a small set of possible behaviours, enumerate the whole set first, then say which one is wrong. Three rows of a table beats three paragraphs:

> You ask: "how much of my quota is left?" > There are only three honest answers: > > | Answer | Means | > |---|---| > | "You're at 95%" | Here's your data | > | "You have no agents set up" | Nothing to report | > | "I couldn't check just now" | Something went wrong | > > **The bug: it gives answer 2 when the truth is answer 3.**

2. **Who wrote what.** Two or three lines. Still never skipped and never hedged (§2), it just does not go first. A name and a PR number mean nothing until the reader knows what the thing does. 3. **The feature, and how someone actually uses it.** What is this capability *for*? Give the real reason a person reaches for it ("your home drive is small and you want the store on an external SSD"), not a restatement of its name. One `file:line` anchor, at the end of the paragraph, not the start. 4. **What you actually see.** Pure symptom, numbered, in the order the perso