commit-message-writer

name	Commit Message Writer
description	Generate commit messages following Conventional Commits spec, including subject/body/breaking-change footer.
category	dev-tools
tags	["ai","api","backend","deployment","documentation"]
source	null
license	MIT
author	badhope
version	1.0.0
needs_review	false
slug	commit-message-writer
created	2026-06-12
updated	2026-06-19
inputs	[{"name":"diff","type":"string","required":true,"description":"The git diff to generate a commit message for"},{"name":"scope_hint","type":"string","required":false,"description":"Override for auto-detected scope"},{"name":"breaking","type":"boolean","required":false,"description":"Set true if diff includes API breaks"},{"name":"max_subject","type":"integer","required":false,"description":"Max subject line length (default 72)"}]
output	{"format":"markdown","description":"Generated content based on the user request"}
quality	stable

When to use

The user staged a diff and wants a commit message. They will run git commit -F <your message> themselves. The diff is what's actually going in the commit; the message describes it, not the world.

Inputs

diff is mandatory. scope_hint overrides the auto-detected scope. breaking is set when the diff includes API breaks (signature change, removed export, schema migration). max_subject is the line length budget — 72 is conventional, push past it and git log --oneline gets ugly.

Output

Plain text:

1. Subject line: <type>(<scope>): <subject> ≤ max_subject chars
2. Blank line
3. Body: 1-3 short paragraphs (≤ 72 chars/line) explaining why
4. Blank line
5. BREAKING CHANGE: footer if breaking: true

Prompt

You write conventional commit messages. The user gave you a diff;
you describe what it does. The message is the public changelog
of intent, not a transcript of the diff.

Workflow:
  1. Read the diff. Find the single most important change. Most
     diffs do one thing; if yours does three, you write three
     commits, not one.
  2. Pick a type:
       feat     = new user-visible capability
       fix      = bug fix
       refactor = no behaviour change, internal cleanup
       perf     = performance only
       docs     = docs only
       test     = tests only
       chore    = build/CI/dependencies
       style    = whitespace/formatting
  3. Pick a scope. Lowercase, short. Default to the top-level
     directory touched. Use `scope_hint` if given.
  4. Subject line: imperative mood, no period, ≤ max_subject.
       Bad:  "fixed the bug where the login button didn't work"
       Good: "fix(auth): preserve redirect after session timeout"
  5. Body: explain the WHY, not the what. The diff is the what.
     Reference the issue/ticket if one was mentioned.
  6. If breaking: add a "BREAKING CHANGE:" footer that tells
     users how to migrate.

Rules:
- Never invent motivation. If the diff doesn't show why, say
  "no commit body needed" and emit just the subject.
- Don't end the subject with a period.
- Don't capitalise the first word after the colon.
- Don't write "WIP", "draft", "initial commit" in the subject.
  Those go in PR descriptions, not commit history.
- If the diff is a merge, rebase, or auto-generated (deps, lock),
  emit a single-line subject. No body.

When NOT to use

• The user wants a PR description. Different format, different audience.
• The user wants a release note. That's a changelog entry, not a commit.
• The diff is a WIP / experiment. Don't pretend it has a clean message.
• The user wants the message in a non-conventional format (e.g. gitmoji). Use a different skill.
• The user has not shared a diff. Ask for git diff --staged output.

Example

Input:

diff: |
  diff --git a/src/auth/session.py b/src/auth/session.py
  -def login(user):
  +def login(user, redirect_to: str | None = None):
       ...
  -    return session_cookie
  +    if redirect_to:
  +        session.set("post_login_redirect", redirect_to)
  +    return session_cookie
breaking: false
scope_hint: auth

Output:

feat(auth): accept post-login redirect target

The login endpoint now accepts an optional `redirect_to` parameter so
deep links can resume after a session timeout. The value is stashed in
the session and consumed by the next navigation. Defaults to None,
preserving the previous behaviour.

Footguns

These are the bugs that bite every new user. Check them before shipping:

• Subject line is a diff: "Added fix to bug where login didn't redirect" instead of what the code does.

  • how to detect: commit history is unreadable
  • how to fix: subject should describe the change, not the process

• No body when body needed: Complex changes without explanation of why.

  • how to detect: future developers can't understand intent
  • how to fix: add context when the why isn't obvious from the diff

• Scope too broad: feat: everything makes commit history useless.

  • how to detect: commits touch many unrelated files
  • how to fix: one logical change per commit

• Breaking change not marked: API changes that break consumers without BREAKING CHANGE footer.

  • how to detect: CI fails after merge because consumers aren't warned
  • how to fix: always add BREAKING CHANGE footer when changing APIs

• Max subject exceeded: Commit messages that wrap in git log --oneline.

  • how to detect: git log output is hard to scan
  • how to fix: enforce 72-char limit, shorter is better