Commit message storyteller
Transforms git diffs, staged files, modified file lists, or plain descriptions into copyable Conventional Commits messages with a clear subject, an optional story-driven body, and issue or breaking-change footers.
When to invoke
- "Write a commit message for this diff."
- "What should I commit this as?"
- "Summarize my staged changes as a Conventional Commit."
- "Help me commit with a message that explains why."
- "Generate multiple commit messages if this diff should be split."
Prerequisites and context
Have at least one source of change context:
git diff for unstaged working tree changes.git diff --staged or git diff --cached for staged files.- A plain-language description of what changed and why.
- A list of modified files, functions, symbols, or issue numbers.
Use https://www.conventionalcommits.org/ as the specification source. Read references/conventional-commits-guide.md when examples or scope guidance are needed.
Procedure
- Gather the change context: what changed, why it changed, and who or what triggered it.
- Infer or confirm whether the diff is one logical change or several unrelated changes.
- Select the Conventional Commits type from the table below.
- Write the subject in imperative mood, with an optional scope only when it clarifies the affected area.
- Add a body only when it tells the story: the previous problem, the reason for the change, or the impact.
- Add footers for issues and breaking changes.
- Return copyable messages and a one-line explanation of the story told.
Commit type selection
| Type |
Use when the change primarily |
feat |
Adds a new feature or capability. |
fix |
Corrects a bug or incorrect behavior. |
refactor |
Restructures code without changing behavior. |
perf |
Improves performance. |
docs |
Changes documentation only. |
style |
Changes formatting, whitespace, or semicolons with no logic change. |
test |
Adds or updates tests. |
chore |
Changes build process, dependencies, generated files, or routine config. |
ci |
Changes CI/CD pipelines or automation. |
revert |
Reverts a previous commit. |
Message construction
<type>(<optional scope>): <short imperative summary>
<body — the story: why this change was made, what problem it solves>
<footer — issue refs, breaking change notices>
| Part |
Rule |
| Subject |
Keep it under 72 characters, lowercase after the colon, no final period. |
| Verb |
Use imperative mood: add, fix, remove; not added, fixes, or removed. |
| Body |
Explain the why, because the diff already shows the what. Keep lines under 100 characters. |
| Footer |
Use Closes #123, Fixes #456, Refs #789, and BREAKING CHANGE: <description> when applicable. |
Split heuristics
| Situation |
Action |
| Different files with unrelated purposes |
Suggest multiple commits. |
| Same file but distinct concerns, such as bug fix plus refactor |
Suggest splitting unless the refactor enables the fix. |
| Everything is tightly coupled |
Produce one message. |
User says keep it short |
Omit the body and produce a strong subject line. |
| No issue number exists |
Omit the footer entirely. |
Gotchas
- Do not write update-only subjects: replace
update file.js with the specific intent and impact.
- Do not invent why: infer from the diff when possible; otherwise mark the reason as missing or keep the body neutral.
- Do not bury breaking changes: add
BREAKING CHANGE: even when the subject already uses !.
- Do not ask when context is enough: only ask whether one diff is one logical change or multiple when the split is genuinely ambiguous.
Progressive disclosure and bundled resources
references/conventional-commits-guide.md: detailed examples, type choices, and scope guidelines.
Commit context vocabulary
Preserve issue and audience context when present: Who/what triggered the change, whether it affects open-source maintainers, and runtime details such as mid-request failures.
Output template
### Commit message storyteller result
**Status:** message ready | split recommended | blocked
**Source reviewed:** `git diff` | `git diff --staged` | `git diff --cached` | description | file list
**Commit message**
```text
<type>(<scope>): <imperative summary>
<body explaining why, omitted when not needed>
<footer such as Closes #123 or BREAKING CHANGE: details>
```
**Story told:** <one sentence explaining the problem, decision, and impact>
**Split guidance:** <one commit is fine | suggested commit boundaries>
Quality gate
1---2name: commit-message-storyteller-23description: Analyze git diffs, staged changes, or plain change descriptions and generate narrative Conventional Commits messages that explain why the change matters. Use when asked to "write a commit message", "generate a commit", "describe my changes", "what should I commit this as", "commit this", "summarize my diff", or "help me commit".4---56# Commit message storyteller78Transforms git diffs, staged files, modified file lists, or plain descriptions into copyable Conventional Commits messages with a clear subject, an optional story-driven body, and issue or breaking-change footers.910## When to invoke1112- "Write a commit message for this diff."13- "What should I commit this as?"14- "Summarize my staged changes as a Conventional Commit."15- "Help me commit with a message that explains why."16- "Generate multiple commit messages if this diff should be split."1718## Prerequisites and context1920Have at least one source of change context:2122- `git diff` for unstaged working tree changes.23- `git diff --staged` or `git diff --cached` for staged files.24- A plain-language description of what changed and why.25- A list of modified files, functions, symbols, or issue numbers.2627Use https://www.conventionalcommits.org/ as the specification source. Read `references/conventional-commits-guide.md` when examples or scope guidance are needed.2829## Procedure30311. Gather the change context: what changed, why it changed, and who or what triggered it.322. Infer or confirm whether the diff is one logical change or several unrelated changes.333. Select the Conventional Commits type from the table below.344. Write the subject in imperative mood, with an optional scope only when it clarifies the affected area.355. Add a body only when it tells the story: the previous problem, the reason for the change, or the impact.366. Add footers for issues and breaking changes.377. Return copyable messages and a one-line explanation of the story told.3839## Commit type selection4041| Type | Use when the change primarily |42| --- | --- |43| `feat` | Adds a new feature or capability. |44| `fix` | Corrects a bug or incorrect behavior. |45| `refactor` | Restructures code without changing behavior. |46| `perf` | Improves performance. |47| `docs` | Changes documentation only. |48| `style` | Changes formatting, whitespace, or semicolons with no logic change. |49| `test` | Adds or updates tests. |50| `chore` | Changes build process, dependencies, generated files, or routine config. |51| `ci` | Changes CI/CD pipelines or automation. |52| `revert` | Reverts a previous commit. |5354## Message construction5556```text57<type>(<optional scope>): <short imperative summary>5859<body — the story: why this change was made, what problem it solves>6061<footer — issue refs, breaking change notices>62```6364| Part | Rule |65| --- | --- |66| Subject | Keep it under 72 characters, lowercase after the colon, no final period. |67| Verb | Use imperative mood: `add`, `fix`, `remove`; not `added`, `fixes`, or `removed`. |68| Body | Explain the why, because the diff already shows the what. Keep lines under 100 characters. |69| Footer | Use `Closes #123`, `Fixes #456`, `Refs #789`, and `BREAKING CHANGE: <description>` when applicable. |7071## Split heuristics7273| Situation | Action |74| --- | --- |75| Different files with unrelated purposes | Suggest multiple commits. |76| Same file but distinct concerns, such as bug fix plus refactor | Suggest splitting unless the refactor enables the fix. |77| Everything is tightly coupled | Produce one message. |78| User says `keep it short` | Omit the body and produce a strong subject line. |79| No issue number exists | Omit the footer entirely. |8081## Gotchas8283- **Do not write update-only subjects**: replace `update file.js` with the specific intent and impact.84- **Do not invent why**: infer from the diff when possible; otherwise mark the reason as missing or keep the body neutral.85- **Do not bury breaking changes**: add `BREAKING CHANGE:` even when the subject already uses `!`.86- **Do not ask when context is enough**: only ask whether one diff is one logical change or multiple when the split is genuinely ambiguous.8788## Progressive disclosure and bundled resources8990- `references/conventional-commits-guide.md`: detailed examples, type choices, and scope guidelines.9192## Commit context vocabulary9394Preserve issue and audience context when present: `Who/what` triggered the change, whether it affects `open-source` maintainers, and runtime details such as `mid-request` failures.9596## Output template9798````markdown99### Commit message storyteller result100101**Status:** message ready | split recommended | blocked102**Source reviewed:** `git diff` | `git diff --staged` | `git diff --cached` | description | file list103104**Commit message**105```text106<type>(<scope>): <imperative summary>107108<body explaining why, omitted when not needed>109110<footer such as Closes #123 or BREAKING CHANGE: details>111```112113**Story told:** <one sentence explaining the problem, decision, and impact>114115**Split guidance:** <one commit is fine | suggested commit boundaries>116````117118## Quality gate119120- [ ] The message follows Conventional Commits type and subject rules.121- [ ] The subject is imperative, non-empty, lowercased after the colon, and under 72 characters.122- [ ] The body explains why, not just what files changed.123- [ ] Breaking changes use a `BREAKING CHANGE:` footer.124- [ ] Issue references use `Closes #123`, `Fixes #456`, or `Refs #789` only when known.125- [ ] Logically unrelated changes are split or explicitly called out.126- [ ] `references/conventional-commits-guide.md` is used when detailed examples are needed.
paulasilvatech