Git Commit Skill

Create meaningful, conventional commit messages that follow team standards.

Trigger

Activate when:

• User asks to commit changes
• User needs help writing a commit message
• User asks "what should I commit this as?"

---

Conventional Commit Format

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

[optional body]

[optional footer]

Types

Type	Description	Example
feat	New feature	feat(complaints): add priority filtering
fix	Bug fix	fix(auth): resolve session timeout issue
docs	Documentation	docs: update API documentation
style	Formatting (no code change)	style: fix indentation in models
refactor	Code restructuring	refactor(db): extract query builder
perf	Performance improvement	perf: add caching to dashboard
test	Adding/fixing tests	test: add complaint service tests
chore	Maintenance	chore: update dependencies
ci	CI/CD changes	ci: add pytest to GitHub Actions
build	Build system/dependencies	build: update webpack to v5
revert	Revert a previous commit	revert: revert feat(api) endpoint

Scope

Optional area of change:

• api - Backend API changes
• ui - Frontend/Streamlit changes
• db - Database changes
• auth - Authentication
• complaints - Complaints feature
• analytics - Analytics feature

---

Phase 1: Analyze Changes

Actions

0. Run a pre-commit quality gate (blocking)

   # Python repos
   ruff check .
   
   # TypeScript/React repos
   npm run lint
   
   # If both stacks exist, run both.

   If lint fails, do not proceed to commit generation until fixed.

1. Review staged changes

   # If files are staged, use staged diff
   git diff --staged --stat
   git diff --staged
   
   # If nothing staged, check working tree
   git diff
   git status --porcelain

2. Stage files if needed

   # Stage specific files
   git add path/to/file1 path/to/file2
   
   # Stage by pattern
   git add *.test.*
   git add src/components/*

   Never stage secrets (.env, credentials.json, private keys).

3. Categorize the changes

   • What files were modified?
   • What was the primary purpose?
   • Are there multiple logical changes?

4. Identify the commit type

   • New functionality → feat
   • Bug fix → fix
   • Code improvement without behavior change → refactor
   • Tests → test
   • Documentation → docs

---

Phase 2: Craft the Message

Subject Line Rules

1. Use imperative mood: "add" not "added" or "adds"
2. No period at the end
3. 50 characters or less (hard limit: 72)
4. Lowercase after the colon

# ✅ Good
feat(complaints): add priority filter to dashboard
fix(api): handle null customer_id in query
refactor(db): extract database adapter class

# ❌ Bad
feat(complaints): Added priority filter to dashboard.  # Past tense, period
FEAT: ADD PRIORITY FILTER  # Uppercase, no scope
fix: various bug fixes  # Too vague

Body (When Needed)

Include body when:

• Change needs explanation
• There's context that isn't obvious
• Breaking changes exist

feat(api): add complaint analytics endpoint

Add new endpoint for retrieving complaint statistics
including resolution times, category distribution, and
trend analysis.

This endpoint powers the new analytics dashboard.

Footer (When Needed)

# Breaking change
feat(api)!: change complaint response format

BREAKING CHANGE: complaint.created_at now returns ISO format

# Issue reference
fix(ui): resolve dashboard loading error

Fixes #123

---

Phase 3: Generate Message

Template

Based on the changes, generate:

## Suggested Commit Message

():

```

Reasoning

• Type: [Why this type was chosen]
• Scope: [Area of the codebase affected]
• Subject: [What the change does]

---

## Examples

### Simple Feature

**Changes**: Added a new filter dropdown to the complaints dashboard

feat(ui): add status filter to complaints dashboard

### Bug Fix with Context

**Changes**: Fixed issue where queries with special characters caused errors

fix(db): escape special characters in search queries

The search function was failing when users entered characters
like quotes or semicolons. Added proper escaping using
parameterized queries.

Fixes #42

### Refactoring

**Changes**: Moved database logic from routes to repository classes

refactor(api): extract database operations to repository layer

Move direct database calls from route handlers to dedicated
repository classes. This improves testability and follows
the separation of concerns principle.

### Multiple Files, Single Purpose

**Changes**: Updated multiple files to add logging

feat: add structured logging throughout application

• Add loguru configuration in config.py
• Replace print statements with logger calls
• Add request logging middleware

### Breaking Change

**Changes**: Changed API response format

feat(api)!: standardize API response envelope

BREAKING CHANGE: All API responses now wrapped in
{ "data": ..., "meta": { "timestamp": ... } } format.

Clients need to update response parsing logic.

---

## Quick Reference

When in doubt, ask yourself:

1. **What type of change is this?** → Choose type
2. **What area does it affect?** → Choose scope
3. **What does it do?** (in imperative) → Write subject
4. **Why was this done?** → Write body if needed
5. **Does it break anything?** → Add BREAKING CHANGE if yes

---

## Git Safety Protocol

- NEVER update git config
- NEVER run destructive commands (`--force`, hard reset) without explicit user request
- NEVER skip hooks (`--no-verify`) unless user asks
- NEVER force push to main/master
- ALWAYS verify lint gate status before creating a commit message
- If a commit fails due to pre-commit hooks, fix the issue and create a NEW commit (don't amend the failed one)
- One logical change per commit
- Reference issues in footers: `Closes #123`, `Refs #456`

---

## Commit Message Checklist

- [ ] Type is appropriate for the change
- [ ] Scope identifies the affected area
- [ ] Subject uses imperative mood
- [ ] Subject is under 50 characters
- [ ] Body explains "why" if not obvious
- [ ] Breaking changes are marked with `!` and footer
- [ ] Related issues are referenced
- [ ] No secrets or credentials in staged files