Describe changes

Ask what a pull request did and you usually get its title back, reworded. The
title is the author's intent at the moment they opened it, which is frequently not
what the diff ended up doing. This skill produces a description that is checkable:
every claim in it points at a hunk.

It writes three registers of the same change — one line, one paragraph, one page —
so the consumer picks the length rather than truncating prose written for another
purpose. And it classifies, from a fixed set, so the descriptions sort.

It composes with two companions in the same pack: release-ledger orchestrates
a since-you-were-away ledger and consumes these descriptions as its entries, and
github-webhooks captures the merge events that feed it. Install either with
npx skills add crissmoldovan/agent-skills.

When to Use

• A commit, pull request, merge, or release range needs a description for people
  who did not write it.
• A ledger, changelog, or release note needs a per-change entry with a
  classification.
• A ticket needs a resolution note that states what actually shipped.
• Someone asks "what changed between these two tags" and needs more than a
  commit list.

Do not use it to review a change — it describes what happened, it does not judge
whether it should have. Do not use it to cut a release: a version's notes are a
different artefact, and the semver call, the version bump, the changelog heading,
the tag and the destinations belong to release-notes, in this pack, which takes
a description like this one as the what. Do not use it to write a commit message before the work is done; it
reads a completed diff. Do not use it as a summariser for a body of
text with no diff behind it; the entire value here is that claims are anchored,
and with nothing to anchor to you have a paraphrase.

Prerequisites

1. A named operation. One commit, one pull request, one merge, or one range
   A..B. Ambiguity here produces a description of the wrong thing.
   Complete when: you can state the operation as an identifier a tool accepts.
2. Read access to the diff. git show, git diff A..B, or the forge's diff
   endpoint.
   Complete when: you have the diff, or have established that you cannot get
   it and will therefore write only the short and medium registers.
3. The surrounding context, where it exists. The pull request body, linked
   tickets or support requests, the reporter, the review outcome.
   Complete when: each of those is either in hand or recorded as absent.
   Absent is a normal answer.
4. A decided output shape. Single digest for the whole operation, or an
   itemized array plus a summary. Ask; do not choose silently.
   Complete when: the user has answered, or the caller passed the shape in.

Procedure

1. Gather the evidence, in this order. Diff first — file list, then hunks,
   then the test changes. Then the pull request title and body. Then linked
   tickets and the reporter. Then the review and check outcomes. Reading the
   description before the diff anchors you to the author's framing, which is the
   thing you are here to check.
2. Establish what the change is, mechanically. Which files, how many lines,
   which subsystems, whether tests moved, whether a schema or an interface
   changed, whether anything was deleted. This paragraph of facts is the input to
   classification; do it before choosing a kind, not to justify one.
3. Classify into exactly one kind from feature, bug_fix, improvement,
   security, ops, docs, breaking. The rubric and its edge cases —
   a bug fix that adds a flag, a pure performance change, a revert, a dependency
   bump that fixes a vulnerability — are in
   the classification guide. One kind. If
   two genuinely apply, that is a signal the operation should be itemized rather
   than digested.
4. Write the three registers.
   • short — one line, at most 140 characters, no markdown syntax beyond
     inline code, no trailing period needed. It answers "what changed" for
     someone scanning a list.
   • medium — one paragraph. What changed, who it affects, and what they will
     notice. No file paths, no function names; this register is for users.
   • detail — a full markdown page: what changed, why, and the specific
     evidence. File paths with line ranges, hunk citations, before/after
     fragments where a fragment is clearer than a sentence. This register is for
     someone who will open the code.
5. Anchor every claim in the detail register. A sentence that asserts
   behaviour must be followed by, or adjacent to, the reference that shows it. If
   you cannot point at the hunk, delete the sentence.
6. Record relations, cited or omitted. Ticket, request, reporter. A relation
   is included only when the evidence names it — a reference in the body, a
   linked issue, a trailer. Do not infer a reporter from an assignee, or a ticket
   from a branch name that resembles one, without saying that is what you did.
7. Emit the agreed shape. The JSON envelope in
   the output contract, single or array. Markdown
   lives inside the JSON string fields; the envelope itself is data.

Honesty rules

These are not style preferences. Each one exists because the opposite behaviour
produces a description that reads well and is false.

• Never claim a change does something the diff does not show. "Improves
  performance" requires either a measurement in the change or a mechanical reason
  visible in the hunk. Otherwise write what the code now does and stop.
• A revert says it is a revert, names what it reverts, and does not describe
  the reverted change's benefits in the present tense.
• A partial change is described as partial. Scaffolding behind a disabled flag
  is not a shipped feature; say the flag is off.
• Deletions are changes. A removed endpoint, option, or column belongs in the
  description even when nothing was added.
• Absent evidence is stated, not filled. No reporter is null, not a guess
  and not an empty string that renders as a dangling label.
• The title is evidence, not a conclusion. When the diff contradicts it,
  describe the diff and note the discrepancy in the detail register.

Usage Examples

Describe this merge for a release ledger. Read the diff first, classify it from
the fixed kind set, and give me short, medium, and detailed registers with the
detail register citing file and line ranges. Return the single-digest JSON shape.

Describe the range v2.3.0..v2.4.0. Ask me first whether I want one digest or an
itemized array — I think itemized, with a generic summary on top. Anything you
cannot anchor in a diff, leave out.

This PR says it is a performance fix. Check that against the diff before you
classify it, and if the diff does not show a performance change, say so in the
detail register and classify what it actually is.

Pitfalls

• Describing the title. The most common failure, and the hardest to see,
  because the output is fluent and plausible. Read the diff first, every time.
• Merging two changes into one description. A pull request that fixes a bug
  and refactors a module has two facts in it. One kind and one description will
  misrepresent one of them. Offer the itemized shape.
• Detail that is a file list. "Changed router.ts, handler.ts, and
  types.ts" is not detail; it is the diff's table of contents. Detail says what
  the change to each file does.
• Line references that rot immediately. Anchor to the post-change line
  numbers and pair them with the commit SHA, so the reference stays resolvable
  after the next merge.
• A medium register full of identifiers. It is the register users read.
  Function names there mean it was written for the wrong audience.
• Claiming a security fix without evidence. Only classify security when the
  change closes an actual exposure the diff shows, or an advisory names it.
  Calling routine hardening a security fix devalues the label the one time it
  matters.
• Silent inference of relations. A branch named fix/1234 is not a citation.
  Either the evidence names the ticket or the relation is null.
• Describing generated or vendored churn. A lockfile update and a regenerated
  client are volume, not content. Say what the regeneration was for.
• Losing the breaking signal in prose. If callers must change, breaking
  is the kind and the first line of the detail register says what to change.

Verification

• The diff was read before the pull request body or title.
• Exactly one kind was assigned, from the fixed set.
• The short register is at most 140 characters and readable on its own.
• The medium register names no file paths or function names.
• Every behavioural claim in the detail register has an adjacent reference.
• References carry a path, a post-change line range, and a commit SHA.
• Relations are cited or null; none were inferred without saying so.
• A revert, a partial change, or a disabled flag is described as such.
• The output shape matches what the user chose.
• The JSON envelope validates against the output contract.
• Nothing in the description asserts a benefit the diff does not demonstrate.

Deeper reading

• Output contract: the JSON envelope, both
  shapes, field-by-field rules, and complete worked examples.
• Classification guide: the seven kinds
  with their boundaries, a decision order that resolves overlaps, and the edge
  cases that get classified wrong most often.