---
name: Commit Workflow
description: Systematic commit process with pre-commit checks, atomic commits, and conventional commit messages
when_to_use: when committing code changes, before creating pull requests, when another agent needs to commit work
version: 1.0.0
---

# Commit Workflow

## Overview

Structured commit process ensuring code quality through pre-commit verification, atomic commit composition, and conventional commit message formatting.

## Quick Reference

**Before committing:**
1. Check staging status
2. Review diff to understand changes
3. Analyze for atomic commit opportunities

**Commit composition:**
1. Split multiple distinct changes into separate commits
2. Use conventional commit format
3. Follow project git guidelines

**Note:** Quality gates (PostToolUse, SubagentStop hooks) automatically enforce pre-commit checks, so code quality is already verified.

## Implementation

### Prerequisites

Read these before committing:
- `${CLAUDE_PLUGIN_ROOT}standards/conventional-commits.md` - Commit message format
- `${CLAUDE_PLUGIN_ROOT}standards/git-guidelines.md` - Git workflow standards

### Step-by-Step Workflow

**Note:** Pre-commit quality checks (linters, tests, build) are enforced automatically by quality gates (PostToolUse, SubagentStop hooks). By the time you're committing, gates have already verified code quality.

#### 1. Check staging status

**Review what's staged:**

```bash
git status
```

**If 0 files staged:**
- Automatically add all modified and new files: `git add .`
- Or selectively stage: `git add <specific-files>`

#### 2. Review diff

**Understand what's being committed:**

```bash
# See staged changes
git diff --staged

# See all changes (staged + unstaged)
git diff HEAD
```

**Analyze for logical grouping:**
- Are multiple distinct features/fixes present?
- Can this be split into atomic commits?

#### 3. Determine commit strategy

**Single commit:** All changes are logically related (one feature, one fix)

**Multiple commits:** Multiple distinct changes detected:
- Feature A + Bug fix B → Split into 2 commits
- Refactoring + New feature → Split into 2 commits
- Multiple unrelated changes → Split into N commits

**If splitting, stage selectively:**

```bash
# Stage specific files
git add file1.py file2.py
git commit -m "..."

# Stage remaining files
git add file3.py
git commit -m "..."
```

#### 4. Write conventional commit message

**Format (from standards/conventional-commits.md):**

```
<type>(<optional-scope>): <description>

[optional body]

[optional footer]
```

**Common types:**
- `feat`: New feature
- `fix`: Bug fix
- `refactor`: Code change that neither fixes bug nor adds feature
- `docs`: Documentation changes
- `test`: Adding or updating tests
- `chore`: Maintenance tasks

**Example messages:**

```bash
git commit -m "feat(auth): add password reset functionality

Implement forgot-password flow with email verification.
Includes rate limiting to prevent abuse."

git commit -m "fix: handle null values in user profile endpoint"

git commit -m "refactor: extract validation logic into separate module

Improves testability and reduces duplication across endpoints."
```

#### 5. Commit changes

**Execute commit:**

```bash
git commit -m "type(scope): description"
```

**Verify commit:**

```bash
git log -1 --stat
```

## What NOT to Skip

**NEVER skip:**
- Reviewing full diff before committing
- Analyzing for atomic commit opportunities
- Following conventional commit format
- Verifying commit was created correctly

**Common rationalizations that violate workflow:**
- "Small change" → Review diff and follow format anyway
- "Will fix message later" → Write correct message now
- "Mixing changes is faster" → Atomic commits are worth the time
- "Don't need to verify" → Always check commit with git log

**Note:** Pre-commit quality checks are enforced by quality gates automatically - no need to run them manually at commit time.

## Testing This Skill

See `test-scenarios.md` for pressure tests validating this workflow resists shortcuts.