Commit Summary

Commit Summary

Generate accurate Conventional Commits from real git diffs.

Contract

Inputs:

• Repository root
• Staged changes, unstaged changes, or approved paths to stage
• Optional commit type, scope, and breaking-change context

Outputs:

• Commit message candidate
• Logical commit grouping when changes are mixed
• Created commit hash after approval, if requested

Creates/Modifies:

• No changes in message-only mode
• May stage files and create commits after approval

External Side Effects:

• None unless another workflow pushes the commit later

Confirmation Required:

• Before staging files
• Before creating a commit
• Before amending or squashing existing commits

Delegates To:

• gh-pr-publish when the commit should be pushed and opened as a PR
• git-safety when secrets or sensitive files appear in the diff

Workflow

1. Inspect repository state:

   git status -sb
   git log --oneline -5
   git diff --stat
   git diff --cached --stat

2. Determine whether changes are already staged:

• If staged changes exist, generate the message from git diff --staged.
• If nothing is staged, inspect unstaged changes and propose logical groups.
• If unrelated changes are mixed, recommend separate commits.

3. Guard against unsafe commits:

• Do not stage secrets, .env, credentials, private keys, local databases,

build caches, or large generated artifacts.

• If sensitive files appear, stop and delegate to git-safety.
• Do not include unrelated formatting churn in a feature/fix commit unless

it is required by the change.

4. Choose the Conventional Commit type:

• feat: user-visible feature or capability
• fix: bug fix
• docs: documentation only
• style: formatting only, no behavior change
• refactor: code restructuring without behavior change
• perf: performance improvement
• test: tests only
• build: build system, package manager, dependencies
• ci: CI/CD workflow changes
• chore: maintenance with no user-facing behavior
• revert: revert a previous commit

5. Detect scope:

• Prefer package, app, domain, or subsystem names already used in history.
• Omit scope if it would be vague (misc, stuff, changes).

6. Detect breaking changes:

• Public API contract changes
• CLI flags or output changes
• Database/schema migrations requiring user action
• Removed config keys, env vars, routes, events, or exported symbols

Format as type(scope)!: summary and include a BREAKING CHANGE: footer.

7. Generate the commit message:

   type(scope): imperative summary

   Optional body explaining why and any non-obvious implementation detail.

   Optional footer such as:
   BREAKING CHANGE: migration required because ...
   Refs: #123

8. If the user asked to commit, show the exact message and get approval:

   git add <approved-paths>
   git diff --staged --stat
   git commit -m "<subject>" -m "<body-or-footer>"

Quality Bar

• Subject is imperative and under 72 characters.
• Body explains why when the diff alone is not enough.
• Message does not overstate behavior.
• Commit contains one logical change.
• Verification commands are not placed in the commit message unless the repo

convention asks for them.

Gotchas

• `git add .` can stage unintended files. If .gitignore does not exclude node_modules, .env*, or build artifacts, always prefer git add <specific-paths>. Verify with git diff --staged --stat before committing.
• Breaking-change footer is case-sensitive. The token must be exactly BREAKING CHANGE: (with a space, all caps) for tools like semantic-release and conventional-changelog to detect it. BREAKING-CHANGE: is not equivalent.
• Amended commits rewrite history. Never amend a commit that has already been pushed to a shared branch. If the commit exists on the remote, create a new fix commit instead.
• Co-authored-by trailers conflict with repo conventions. Some repos (including this project) explicitly forbid Co-Authored-By trailers. Check CLAUDE.md or recent commit history for the project convention before adding them.

Examples

• feat(auth): add password reset flow
• fix(api): handle null provider response
• ci(actions): restrict pull request token permissions
• refactor(utils): extract date formatting helper
• docs: update GitHub project board workflow