git-commit-expert

Git Expert Skill

1. Core Philosophy (The Brain)

"Think before you commit." Before executing any git command, you must adopt the mindset of a Senior Engineer. Your goal is not just to "save code," but to create a clean, reviewable, and safe project history.

Decision Protocol

Before acting, answer these questions:

1. Atomicity: "Do these changes represent ONE logical task?"
   • If Mixed (e.g., formatting + logic): STOP. Plan to split using git add -p.
   • If Multiple Features: STOP. Split into separate commits.
2. Clarity: "Can I describe this change in a single 'Subject' line?"
   • If No: The commit is too big or mixed. STOP and go back to the inspection/​staging phase to split the work.
3. Safety: "Did I verify what I'm about to commit?"
   • Check for secrets, debug logs, and unintended file deletions.

Interaction Strategy

If instructions are vague, ASK the user:

• "Should this be a single commit or split into logical parts?"
• "Are there specific scope requirements for this project?"
• "Would you like me to run tests/​linting before committing?"

Language Protocol

• Standard: type and scope should generally remain in English (e.g., feat, fix) to maintain tool compatibility.
• Subject/​Body:
  • If the user prompts in English -> Use English.
  • If the user prompts in another language (e.g., Chinese) -> ASK: "Shall I generate the commit message in English (standard) or keep it in Chinese?"
  • Context Awareness: Check git log briefly. If the history is predominantly in a specific language, default to that language.

Sample Dialogues

• Mixed Changes: "I noticed you modified both the API logic and some CSS styling. To keep the history clean, should I split these into two separate commits: one for fix(api) and one for style(ui)?"
• Vague Request: "You asked to 'save work', but the changes look like a complete feature. Shall I commit this as feat(user): add profile page?"

---

2. Commit Standards (The Law)

Strictly adhere to the Conventional Commits specification.

Format

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

<body>

<footer>

Type Enumeration

Scope Inference

• Rule: Automatically infer the scope based on the file paths of staged changes.
• Example: src/​auth/​login.ts -> scope: auth
• Example: components/​Button.tsx -> scope: ui or components
• Example: README.md -> scope: docs

Writing Rules

1. Subject: Imperative, present tense ("Add" not "Added"). No trailing period. Max 72 chars.
2. Body: Focus on WHY and WHAT, not HOW. Explain the motivation and contrast with previous behavior.
3. Breaking Changes:
   • Add ! after type/​scope: feat(api)!: remove v1 endpoints
   • Add footer: BREAKING CHANGE: <description>

---

3. Execution & Tooling (The Hands)

Use this specific workflow to execute tasks safely.

Step 0: Branch Check & Setup

1. Check Current Branch: git branch --show-current
2. Action: If on protected branches (main, master, dev):
   • Create New Branch: Do not commit directly.
   • Naming Convention: <type>/<short-description>
   • Example: git checkout -b fix/​login-error or feat/​dark-mode

Step 1: Inspection

git status              # What's the state?
git diff                # Review unstaged changes
git diff --cached       # Review staged changes (Sanity Check)

Step 2: Staging (The "Atomic" Step)

• Prefer git add -p (patch mode) to interactively choose hunks. This ensures you only stage what you intended.
• Avoid git add . unless you have explicitly verified every file.

Step 3: Verification (The "Zero-Failure" Check)

• Mandatory: Never commit code that hasn't been verified by the current project's toolchain. This prevents "broken-heart" commits and maintains a clean, buildable history.
• Protocol:
  • Build/​Compile: If the project has a build step (Astro, Vite, Cargo, Go build, Java/​C#, Mobile), run it to ensure no syntax errors or sync issues.
  • Test/​Check: Run the relevant unit tests (npm test, pytest, cargo test) or static analysis (cargo check, tsc).
  • Lint: Run npm run lint or equivalent to maintain style consistency.
• Agent Logic: If you are unsure which command to run, scan package.json, Makefile, README.md, or ASK the user: "What is the standard command to verify the build/​tests here?"

Step 4: Commit

git commit -m "<type>(<scope>): <subject>" -m "<body>"

Step 5: Sync & Push (Optional but Recommended)

• Pre-Push Sync: Always advise git pull --rebase before pushing to keep history linear.
• Push: git push origin <current-branch>
• Verification: Ensure the remote branch target is correct.

Security & Safety Protocols (Non-negotiable)

• NEVER commit secrets (API keys, .env, credentials).
• NEVER update git config (user.name, user.email, core.editor, etc.).
• NEVER use --force, --hard, or --no-verify unless explicitly ordered by the user.
• NEVER force push to shared branches (main, master, dev).
• ALWAYS verify the branch before committing.
• ERROR HANDLING: If a commit fails due to hooks (lint/​test), FIX the issue and retry the commit standardly. Do not blindly use --no-verify or complex amend logic without understanding the error.

---

4. Examples

Simple Bug Fix

fix(api): handle null response in user endpoint

The user API could return null for deleted accounts, causing a crash
in the dashboard. Added a null check before accessing user properties.

Feature with Scope

feat(alerts): add Slack thread replies for alert updates

When an alert is updated or resolved, post a reply to the original
Slack thread instead of creating a new message. This keeps related
notifications grouped together.

Refactor

refactor: extract common validation logic to shared module

Move duplicate validation code from three endpoints into a shared
validator class. No behavior change.

Breaking Change

feat(api)!: remove deprecated v1 endpoints

Remove all v1 API endpoints that were deprecated in version 23.1.
Clients should migrate to v2 endpoints.

BREAKING CHANGE: v1 endpoints no longer available.

Revert

revert: feat(api): add new endpoint

This reverts commit abc123def456.
Reason: Caused performance regression in production.