name:: commit
description:: Analyze git diffs or staged changes and generate conventional commit messages that explain WHY a change was made. Supports auto-detecting type and scope, intelligent file staging, and interactive overrides. Use when asked to "write a commit message", "generate a commit", "describe my changes", "commit this", "summarize my diff", or "/commit".
argument-hint:: [analyze|generate|stage|validate] [optional: type/scope override or description]

Analyze changes and generate a Conventional Commits message explaining the motivation behind the change.

Mode: analyze

Inspect staged or unstaged changes and classify the commit type and scope.

Steps:

Run git diff --staged — if empty, run git diff HEAD to capture unstaged changes
Group changed files by logical concern (feature, fix, refactor, docs, config, tests, ci)
Identify the type from the change pattern:
- feat — new capability or behavior added
- fix — corrects broken or incorrect behavior
- refactor — restructures code without changing behavior
- perf — measurably improves performance
- test — adds or corrects tests only
- docs — documentation only
- chore — build tooling, dependency updates, config changes with no production effect
- ci — changes to CI/CD pipelines or workflow files
- revert — reverting a prior commit
Infer scope from the most specific common ancestor: module name, service name, directory, or filename
Check for breaking changes: API removals, signature changes, config renames, behavior inversions — flag with ! and add BREAKING CHANGE: footer
Report: detected type, scope, whether breaking, and a one-line WHY summary

Reference: references/conventional-commits.md → Type Classification, Scope Rules

Mode: generate

Generate a complete conventional commit message from diff or description.

Steps:

Run analyze mode first to determine type, scope, and breaking status
Write the subject line:
- Format: <type>(<scope>): <imperative verb> <what and why>
- Max 72 characters
- Imperative mood: "add", "fix", "remove", "update", "extract" — not "added", "fixes"
- Focus on the WHY, not just the what: "fix(auth): validate token expiry before redirect" not "fix(auth): update token check"
Write the body (when the subject line is insufficient):
- Wrap at 72 characters
- Explain the problem being solved and the approach chosen
- One blank line between subject and body
Write footers:
- BREAKING CHANGE: <description> for breaking changes (also add ! to subject)
- Fixes #<issue> or Closes #<issue> for linked issues
- Co-authored-by: if applicable
Output the full message in a code block ready to copy

Message structure:

<type>(<scope>): <subject>

<body — optional, explains motivation and approach>

<footers — optional>

Reference: references/conventional-commits.md → Message Structure, Body and Footer Rules

Intelligently stage files for a logical, atomic commit.

Steps:

Run git status to list all modified, added, and deleted files
Group files by logical change:
- Source files that implement a single feature or fix together
- Test files that cover those source changes
- Documentation that describes those changes
- Config or build changes that support those changes
Separate unrelated changes into distinct groups — each group should be a separate commit
If multiple logical groups exist: present the groupings and ask which to stage first
Stage the chosen group: git add <files>
Confirm staged set with git diff --staged --stat
Run generate mode to produce the commit message for the staged group

Reference: references/conventional-commits.md → Atomic Commits

Validate an existing commit message against the Conventional Commits specification.

Steps:

Accept the message as input (or read from git log -1 --format=%B)
Check subject line:
- Has valid type from the allowed list
- Scope (if present) uses lowercase, no spaces
- ! before : only when BREAKING CHANGE footer is also present
- Subject after : starts with lowercase, no period at end, ≤ 72 chars
Check body (if present):
- Separated from subject by exactly one blank line
- Lines wrap at 72 characters
Check footers (if present):
- BREAKING CHANGE: value is non-empty
- Issue references use correct format (Fixes #N, Closes #N)
Report: PASS or list of violations with the exact rule broken and the corrected line