Smart Commit

Create meaningful conventional commits by analyzing your actual changes.

Workflow

Step 1: Assess the working tree

Run these commands to understand the current state:

git status git diff --stat git diff --cached --stat

Step 2: Handle unstaged changes

If nothing is staged (git diff --cached is empty):

• Show the user what files have changed

• Suggest what to stage based on logical grouping (e.g., "these 3 files are all related to the auth refactor")

• Ask if they want to stage all, or select specific files

• Stage the approved files with git add <files>

If changes are already staged, proceed to analysis.

Step 3: Analyze the diff

Read the full staged diff:

git diff --cached

Determine the commit type from the changes:

Signal Type

New files with new functionality feat

New test files or test additions test

Changes to existing logic fixing incorrect behavior fix

Structural changes without behavior change refactor

package.json, tsconfig, CI config changes chore

Build/bundler config changes build

README, docs, comments only docs

Formatting, whitespace, semicolons only style

Performance improvements perf

Determine the scope from the primary directory or module affected:

• src/api/ -> api

• src/components/auth/ -> auth

• tests/ -> tests

• Root config files -> omit scope

• Multiple unrelated areas -> omit scope

Step 4: Check for user overrides

If the user provided arguments via $ARGUMENTS :

• Single word (e.g., fix ) -> use as commit type

• Two words (e.g., refactor api ) -> use as type and scope

• Otherwise -> use auto-detected values

Step 5: Compose the commit message

Format: type(scope): imperative short description

Rules:

• Subject line max 72 characters

• Use imperative mood ("add", "fix", "refactor", not "added", "fixes")

• Don't end with a period

• Body explains WHY this change was made, not what changed (the diff shows what)

• If changes are trivial (typo fix, formatting), skip the body

Example:

feat(auth): add JWT refresh token rotation

Tokens were expiring mid-session for users with slow connections. Rotating refresh tokens extends the session without compromising security, since each refresh token can only be used once.

Step 6: Confirm and commit

Show the user the proposed commit message and ask for confirmation.

If confirmed, run:

git commit -m "<message>"

Then verify with:

git log --oneline -1

Show the committed hash and message.

Tips

• Run after completing a logical unit of work, not after every file change

• If the diff is too large for one commit, suggest splitting into multiple commits

• For breaking changes, add ! after the scope: feat(api)!: change response format

• The body should answer "if someone reads this commit in 6 months, will they understand WHY?"