/commit

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]"
title: "Commit Command"
sidebar_label: "commit"
custom_edit_url: null

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: 1. Run `git diff --staged` — if empty, run `git diff HEAD` to capture unstaged changes 2. Group changed files by logical concern (feature, fix, refactor, docs, config, tests, ci) 3. 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

4. Infer scope from the most specific common ancestor: module name, service name, directory, or filename 5. Check for breaking changes: API removals, signature changes, config renames, behavior inversions — flag with `!` and add `BREAKING CHANGE:` footer 6. 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: 1. Run `analyze` mode first to determine type, scope, and breaking status 2. 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"

3. 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

4. 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

5. 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

Mode: stage

Intelligently stage files for a logical, atomic commit.

Steps: 1. Run `git status` to list all modified, added, and deleted files 2. 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

3. Separate unrelated changes into distinct groups — each group should be a separate commit 4. If multiple logical groups exist: present the groupings and ask which to stage first 5. Stage the chosen group: `git add <files>` 6. Confirm staged set with `git diff --staged --stat` 7. Run `generate` mode to produce the commit message for the staged group

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

Mode: validate

Validate an existing commit message against the Conventional Commits specification.

Steps: 1. Accept the message as input (or read from `git log -1 --format=%B`) 2. 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

3. Check body (if present):

• Separated from subject by exactly one blank line
• Lines wrap at 72 characters

4. Check footers (if present):

• `BREAKING CHANGE:` value is non-empty
• Issue references use correct format (`Fixes #N`, `Closes #N`)

5. Report: PASS or list of violations with the exact rule broken and the corrected line

Reference: `references/conventional-commits.md` → Validation Rules