git-storytelling-commit-messages

What this skill does

# Git Storytelling - Commit Messages

This skill guides you in crafting commit messages that are clear, informative, and tell the story of your development process. Good commit messages are documentation that lives with your code.

## Core Principles

### The Purpose of Commit Messages

Commit messages serve multiple audiences and purposes:

- **Future developers** (including yourself) understanding why changes were made
- **Code reviewers** evaluating the intent and scope of changes
- **Project managers** tracking progress and understanding what was delivered
- **Automated tools** generating changelogs and release notes
- **Git tools** like blame, log, and bisect for debugging

### The Three-Part Structure

Effective commit messages follow a consistent structure:

1. **Subject Line**: Brief summary (50 characters or less)
2. **Body** (optional): Detailed explanation of what and why
3. **Footer** (optional): Issue references, breaking changes, co-authors

### The Subject Line Format

```
<type>: <description>

Examples:
feat: add user authentication system
fix: resolve race condition in payment processing
docs: update API documentation for v2 endpoints
```

## Commit Message Anatomy

### Subject Line Rules

**DO:**

- Start with a type prefix (feat, fix, docs, etc.)
- Use imperative mood ("add" not "added" or "adds")
- Keep it under 50 characters
- Don't end with a period
- Capitalize the first letter after the colon
- Be specific and descriptive

**DON'T:**

- Use vague terms like "update stuff" or "fix things"
- Include file names unless necessary
- Describe HOW you did it (that's what the code shows)
- Use past tense
- Be too generic

### Body Guidelines

The body should explain:

- **What** changed (briefly, the code shows details)
- **Why** the change was needed
- **Any side effects** or implications
- **Alternatives** considered
- **Context** that isn't obvious from the code

Format:

- Wrap at 72 characters per line
- Use bullet points for multiple items
- Separate from subject with a blank line
- Use proper paragraphs for complex explanations

### Footer Elements

```
Refs: #123, #456
Closes: #789
Breaking Change: API endpoint /users now requires authentication
Co-Authored-By: Jane Doe <[email protected]>

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

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

## Commit Types

### feat: New Features

Use when adding new functionality or capabilities.

```
feat: add password reset functionality

Implement password reset flow with email verification:
- Generate secure reset tokens
- Send reset emails with expiration
- Validate tokens before allowing password change
- Log password reset events for security audit

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

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

### fix: Bug Fixes

Use when correcting defects or unexpected behavior.

```
fix: prevent duplicate order submission

Add client-side debouncing and server-side idempotency check
to prevent users from accidentally submitting the same order
multiple times when clicking quickly.

Closes: #234

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

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

### docs: Documentation

Use for documentation-only changes.

```
docs: add architecture decision record for database choice

Document why we chose PostgreSQL over MongoDB for our
primary datastore, including performance benchmarks and
team expertise considerations.

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

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

### refactor: Code Restructuring

Use when improving code without changing behavior.

```
refactor: extract authentication logic into middleware

Move authentication checks from individual route handlers
into reusable middleware to reduce duplication and improve
maintainability.

No functional changes to authentication behavior.

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

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

### test: Testing Changes

Use when adding or modifying tests.

```
test: add integration tests for payment flow

Add end-to-end tests covering:
- Successful payment processing
- Failed payment handling
- Refund processing
- Webhook event handling

Improves test coverage from 65% to 82%.

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

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

### perf: Performance Improvements

Use for changes that improve performance.

```
perf: optimize database query in user dashboard

Replace N+1 query pattern with single JOIN query, reducing
dashboard load time from 2.3s to 0.4s for users with 100+
items.

Added database index on user_id and created_at columns.

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

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

### style: Formatting Changes

Use for whitespace, formatting, missing semicolons, etc.

```
style: format code with prettier

Apply prettier formatting across all TypeScript files
to maintain consistent code style. No functional changes.

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

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

### chore: Maintenance Tasks

Use for routine tasks, dependency updates, build changes.

```
chore: upgrade dependencies to latest stable versions

Update all npm packages to resolve security vulnerabilities:
- express: 4.17.1 -> 4.18.2
- axios: 0.21.1 -> 1.4.0
- jest: 27.0.6 -> 29.5.0

All tests passing after upgrade.

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

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

## Code Examples

### Example 1: Feature with Context

```
feat: implement webhook signature verification

Add HMAC-SHA256 signature verification for incoming webhooks
to ensure requests are authentic and haven't been tampered with.

Implementation details:
- Validate signature from X-Webhook-Signature header
- Use timing-safe comparison to prevent timing attacks
- Return 401 for invalid signatures
- Log suspicious webhook attempts

Security measure required before production launch.

Refs: #567

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

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

### Example 2: Fix with Root Cause

```
fix: resolve memory leak in event listener cleanup

Event listeners were being added on component mount but not
removed on unmount, causing memory to accumulate and browser
to slow down after multiple navigation cycles.

Root cause: Missing cleanup function in useEffect hook.

Solution: Return cleanup function that removes all event
listeners when component unmounts.

This bug affected users who navigated the app extensively
without refreshing, particularly noticeable after 10+ page
transitions.

Closes: #892

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

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

### Example 3: Refactor with Motivation

```
refactor: replace callback hell with async/await

Convert nested callback-based error handling to async/await
pattern for improved readability and maintainability.

Before: 5 levels of nested callbacks
After: Linear async/await flow

Benefits:
- Easier to understand error handling
- Reduced cognitive load when reading code
- Simpler to add new steps to the flow
- Better stack traces for debugging

No behavior changes, all existing tests pass.

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

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

### Example 4: Breaking Change

```
feat: migrate to v2 API with breaking changes

Update API client to use v2 endpoints with improved
error handling and response format.

BREAKING CHANGE: Response format has changed
- Old: { data: {...}, status: "ok" }
- New: { result: {...}, success: true }

Migration guide:
1. Update response handlers to use 'result' instead of 'data'
2