summarize-commits

name	summarize-commits
description	Summarizes commits into a PR description, changelog, or sprint summary. Use when the user says summarize these commits, write a PR description, what changed in this branch, write release notes, or sprint summary. Apply when the user shares a git log and wants a human-readable summary.

Summarize Commits

When to Use

Invoke when the user wants a plain-language summary of what changed across a set of commits, for a PR description, release note, sprint summary, or changelog entry.

Project contract

Summarizing a range of commits is mostly project-agnostic, but a few touch points are project-specific. Read them from .agents/project-contract.md (shared contract), then layer .agents/project-contract.personal.md on top if it exists (personal entries win where they overlap):

• ## Tracker → Issue ref format: how to cite tickets/issues in the summary (e.g. PROJ-123 for Jira, #NNNN for GitHub). Use this format wherever the summary references an issue.
• ## Tracker → Output wrapping / markup: where a PR description or summary lands (a Jira comment, a GitHub PR body, a standup post) and how to mark it up. Wrap copyable output per the project contract (e.g. a code block for Jira ticket output, fenced blocks on GitHub).
• ## Stack / ## Environments: what counts as a deploy-affecting or compliance-relevant change worth flagging (see Project Context below).
• ## Attribution marker: the marker wording (if the project contract defines one) and whether it applies to the destination surface.
• ## Voice: the voice config path for all generated prose.

If no project contract is present, fall back to generic behavior: cite issues however the user references them, plain Markdown output, no attribution marker.

Approach

1. Get the commit range, ask for git log --oneline [range] output or a list of commits
2. Group by theme, bug fixes, features, refactors, tests, config, docs
3. Write in plain language, what changed and why it matters, not just what files were touched
4. Calibrate detail level, PR description needs more detail than a changelog entry

Output Format

For a PR Description

Hard cap: 1–4 sentences total (excluding the marker and "how" line). PR descriptions exist to be skimmed; the diff carries the detail. One sentence on what the PR fixes/adds, one or two on anything a reviewer actually needs to know before reading the diff. If there's nothing a reviewer needs to know beyond the subject line, one sentence is enough. Resist the pull to list every file or explain every decision; that belongs in code comments and the plan file. Use plain language; avoid developer shorthand (e.g. "no-ops", "gates", "shims") that a reviewer outside the immediate team might not parse.

Wrap the output in a code block per the project contract's Tracker output-wrapping convention so the user can copy and paste directly.

[1–4 sentences total. State what the PR fixes/adds and any one or two facts a reviewer needs to know.]

[attribution marker, if the project contract defines one and a commit was AI-assisted]
[Honest "how" line]

See ## Attribution below for full rules.

For a Changelog / Release Note

## [Version or Sprint], [Date]

### Fixed
- [Bug description]

### Added
- [Feature description]

### Changed
- [Refactor or improvement]

For a Sprint Summary

Plain prose grouped by ticket, 1–2 sentences per ticket.

Voice

Apply the voice config from the project contract's ## Voice section (e.g. .agents/style/voice.md) to all generated prose. Run the result through tone-check before publishing.

Project Context

• Reference issue numbers where known, using the project contract's Tracker issue-ref format.
• Note if any change requires a deployment step beyond the project's normal release (per the project contract's ## Environments / ## Stack, e.g. a cache clear, config import, or migration).
• Flag if any change has accessibility, security, or compliance implications (per the project contract's a11y baseline and priority guide).

Attribution

Attribution depends on whether the active project contract defines a marker (the project contract's ## Attribution marker section). If it does not (e.g. a public OSS project where a marker reads oddly), skip everything below: human-review the output before posting. The rest of this section applies when the project contract does define a marker.

When the output is used as a PR description, the marker is mandatory whenever any commit being summarized was AI-assisted; the PR description is the disclosure surface for AI-assisted code. PR descriptions are also capped at 1–4 sentences total.

• Marker placement: at the bottom of the PR description as the very last block.
• Marker wording: use the exact wording from the project contract's ## Attribution marker section (a team convention, not policy text verbatim; see security-check for context).
• "How" line: include a one-sentence "how" line accompanying the marker. Disclosure asks for "if/how," not just "if." Be honest about what AI actually did, no boilerplate.
• Don't name the AI tool: the marker is intentionally tool-agnostic.

When the output is a changelog, release note, or sprint summary, the marker is conditional: apply it if the artifact gets shared (chat, team wiki, customer-facing notes); skip it if it's for your own review.

"How" line, pick the one that matches reality

What AI actually did	"How" line
Wrote only this PR description	AI drafted only the description; production code is human-written.
Wrote tests, not the code	AI drafted the tests; production code is human-written.
Co-authored, both AI and human edited	AI co-authored the code ([files/scope]); human-edited and reviewed line by line.
Wrote most/all of the code, you reviewed	AI authored the code; human-reviewed and edited.
Wrote everything in an agent loop	AI authored end-to-end (code, tests, description) under human supervision; human-reviewed before submission.

A canned "AI drafted the description" line on a PR where AI actually wrote the code understates involvement. The "how" should describe what actually happened.

Example (whole PR description, 1–4 sentences, AI co-authored the code)

The issue ref (PROJ-123) and marker below follow a Jira-style project contract. Substitute the active project contract's issue-ref format and attribution marker.

Fixes PROJ-123 by restoring focus to the active filter after the result list re-renders. Retries kick in only after the async update completes; existing keyboard handlers are unchanged.

_AI-assisted draft, reviewed before submission._
AI co-authored the code (filter-button.js + regression test); human-edited and reviewed line by line.

Example

You ask: use the summarize-commits skill on branch fix/PROJ-1234-facet-scroll

You get:

PROJ-1234: Clear overflow lock after facet deselect; add regression test.

Fixes the page-scroll lock that persisted after deselecting any facet.
Root cause: overflow:hidden set on body during ajaxSend was not cleared in the
no-results branch of ajaxComplete. Cleared unconditionally; regression added.

[attribution marker, per project contract]
AI co-authored the patch and test scaffold; human-edited and reviewed line by line.

Related Skills

• Upstream: organize-commits or squash-commits (summary is easier when commits are clean)
• Sibling: issue-closure-notes (closure notes are ticket-scoped; summarize-commits is range-scoped, for PR descriptions, sprint summaries, release notes)
• Downstream: tone-check (run summary prose through tone check before publishing)