git-commit

What this skill does

# Git Commit

Comprehensive Git commit protocol implementing Conventional Commits specification with strict safety rules, proper attribution, and complete workflow guidance.

## Table of Contents

- [Overview](#overview)
- [When to Use This Skill](#when-to-use-this-skill)
- [Critical Safety Rules (NEVER)](#critical-safety-rules-never)
- [Conventional Commits Format](#conventional-commits-format)
- [Commit Workflow (4 Steps)](#commit-workflow-4-steps)
- [Pull Request Creation](#pull-request-creation)
- [When to Commit](#when-to-commit)
- [System Changes Documentation](#system-changes-documentation)
- [Examples](#examples)
- [Resources](#resources)
- [Troubleshooting](#troubleshooting)
- [Best Practices](#best-practices)
- [Testing](#testing)
- [Version History](#version-history)

## Overview

This skill provides the authoritative protocol for all Git commit operations, including:

- **Conventional Commits format** with required attribution footer
- **Intelligent staging decisions** handling mixed staged/unstaged scenarios
- **Safety rules** preventing destructive operations
- **4-step commit workflow** ensuring proper execution
- **Pre-commit hook handling** for automated tooling failures
- **Pull request creation** with complete context
- **System changes verification** before committing

**CRITICAL**: This skill must be invoked before ANY commit operation to ensure compliance with safety protocols and message formatting requirements.

## When to Use This Skill

This skill should be used when:

- Creating any Git commit (regular, initial, merge)
- Drafting commit messages following Conventional Commits
- Handling pre-commit hook failures or modifications
- Creating pull requests with `gh pr create`
- Uncertain about commit timing (when to commit vs when to wait)
- Validating commit safety (checking for secrets, absolute paths, etc.)
- Amending commits (rare - requires safety checks)
- Verifying system changes documentation before committing

**IMPORTANT**: Only create commits when the user explicitly requests. If unclear, ask first.

## Critical Safety Rules (NEVER)

These rules are non-negotiable and MUST be followed:

### NEVER Rules

1. **NEVER update git config** - Configuration changes must be intentional and user-approved
2. **NEVER run destructive commands** - No `git push --force`, `git reset --hard`, etc. unless explicitly requested
3. **NEVER skip hooks** - No `--no-verify` or `--no-gpg-sign` flags unless explicitly requested by user
4. **NEVER force push to main/master** - Warn user if they request this
5. **NEVER use `git commit --amend`** - ONLY permitted when:
   - User explicitly requests amend, OR
   - Pre-commit hook modified files (requires safety checks - see [Hook Handling](#step-4-handle-pre-commit-hook-failures))
6. **NEVER commit without explicit user request** - This is VERY IMPORTANT - only commit when user asks
7. **NEVER commit secret files** - Do not commit `.env`, `credentials.json`, etc. - warn user if requested
8. **NEVER use interactive git commands** - No `-i` flags (`git rebase -i`, `git add -i`) - not supported in non-interactive environments

### Safety Verification Before Committing

Before executing any commit:

- ✅ **Check for secrets** - Scan staged files for common secret patterns
- ✅ **Check for absolute paths** - Ensure no machine-specific paths (like `D:\repos\...`, `/home/user/...`)
- ✅ **Verify SYSTEM-CHANGES.md** - If any files outside repo were modified (configs, keys, etc.), ensure documented
- ✅ **Confirm user intent** - If unclear whether to commit, ask user first

## Conventional Commits Format

All commit messages MUST follow the Conventional Commits specification with required Claude Code attribution.

### Basic Structure

```text
<type>[optional scope]: <description>

[optional body]

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
```

### Commit Types

Use these standardized types:

- **feat**: New feature (correlates to MINOR in SemVer)
- **fix**: Bug fix (correlates to PATCH in SemVer)
- **docs**: Documentation changes only
- **style**: Code style changes (formatting, missing semicolons, no logic change)
- **refactor**: Code refactoring (neither fixes bug nor adds feature)
- **perf**: Performance improvements
- **test**: Adding or updating tests
- **chore**: Maintenance tasks (dependencies, tooling, configs)
- **ci**: CI/CD configuration changes
- **build**: Build system or external dependency changes

### Breaking Changes

Indicate breaking changes using EITHER:

1. **Exclamation mark** before colon: `feat!: change API response format`
2. **BREAKING CHANGE footer**: Include `BREAKING CHANGE: <description>` in message body

### Scope (Optional)

Add scope to provide context about what area of codebase is affected:

```text
feat(api): add user authentication endpoint
fix(database): resolve connection timeout issue
docs(readme): update installation instructions
```

### Message Guidelines

- **Description**: Start with lowercase, no period at end, max ~50 characters
- **Focus on WHY, not WHAT**: Explain intent and reason, not just the change
- **Be concise**: 1-2 sentences in body if needed
- **Use imperative mood**: "add feature" not "added feature" or "adds feature"

### Complete Message Example

```bash
git commit -m "$(cat <<'EOF'
feat(auth): add JWT token refresh mechanism

Implements automatic token refresh to improve user experience
and reduce unnecessary re-authentication.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>
EOF
)"
```

## Commit Workflow (4 Steps)

Follow this complete workflow for every commit operation.

### Step 1: Gather Information (Parallel)

Run these commands in parallel to understand current state:

```bash
# View all staged and unstaged changes
git status

# See exact modifications (staged and unstaged)
git diff
git diff --staged

# Review recent commits to understand message style
git log --oneline -10
```

**Why parallel**: These are independent readonly operations - no dependencies between them.

### Step 2: Determine Staging Strategy and Draft Message

Based on gathered information, first determine what to commit, then draft the message.

#### 2.1: Analyze Staging State

Count the files in each category from `git status`:

- **Staged files**: Files in "Changes to be committed" section
- **Modified files**: Files in "Changes not staged for commit" section (tracked files modified)
- **Untracked files**: Files in "Untracked files" section

#### 2.2: Apply Staging Decision Logic

##### Scenario A: Nothing to commit (staged=0, modified=0, untracked=0)

```text
Working tree is clean - nothing to commit.
```

Exit gracefully. No commit needed.

##### Scenario B: Files staged, nothing modified (staged>0, modified=0)

Proceed directly to commit. User has already staged exactly what they want.

##### Scenario C: Nothing staged, but changes exist (staged=0, modified>0 or untracked>0)

Ask user what to commit using AskUserQuestion:

```text
"I see {N} modified file(s) but nothing is staged yet. What would you like to commit?"

Options:
1. "Stage and commit all modified files" → `git add -u` (stage all tracked files)
2. "Let me stage specific files first" → Exit, let user stage manually, then re-run /commit
```

If user chooses option 1, proceed with all modified files.
If user chooses option 2, exit and inform them to run `git add <files>` then `/commit` again.

##### Scenario D: Mixed staging (staged>0, modified>0)

Ask user using AskUserQuestion:

```text
"I see {N} file(s) staged and {M} file(s) modified but not staged. What would you like to commit?"

Options:
1. "Commit only the staged files" → Proceed with staged files only
2. "Stage and commit everything" → `git add -u` then commit all
```

Respect user's choice.

#### 2.3: Draft Commit Message

After confirming what will be committed:

1. **Review all changes to be committed**
2. **De