commit-assistant

What this skill does

# Commit Assistant

Comprehensive guidance on conventional commits with automatic message generation integrated with CCPM's Linear workflow. Ensures all commits are properly formatted, issue-linked, and semantically meaningful.

## When to Use

This skill auto-activates when:

- User asks **"commit my changes"**, **"create a git commit"**, **"how do I commit"**
- User asks about **"conventional commits"** or **"commit message format"**
- Running **`/ccpm:commit`** command
- Making changes that need to be committed to version control
- Need guidance on **commit type** or **commit message structure**
- Need help **generating commit messages** from code changes

## Core Principles

### 1. Conventional Commits Format

All commits in CCPM follow [Conventional Commits](https://www.conventionalcommits.org/) specification:

```
type(scope): message

[optional body]

[optional footer]
```

**Format breakdown**:
- **type**: What kind of change (feat, fix, docs, refactor, test, chore, perf, style)
- **scope**: What component or module changed (optional but recommended)
- **message**: Clear, concise description in imperative mood
- **body**: Detailed explanation (only for complex changes)
- **footer**: Issue references, breaking changes (optional)

### 2. Why Conventional Commits Matter

**Conventional commits enable**:
- ✅ Automatic changelog generation
- ✅ Semantic versioning (SemVer) automation
- ✅ Better git history readability
- ✅ Linear issue linking
- ✅ Filtered log searches (`git log --grep="^feat"`)
- ✅ CI/CD pipeline triggers (e.g., deploy on "feat:" commits)

### 3. Imperative Mood

Always write commit messages in **imperative mood** (command form):

**✅ Correct**:
- "add user authentication"
- "fix database connection timeout"
- "refactor auth module for clarity"
- "update API documentation"

**❌ Incorrect**:
- "added user authentication"
- "fixed database connection timeout"
- "refactoring auth module"
- "updates API documentation"

**Why**: Imperative mood matches git's own commit messages and convention specifications.

## Commit Types Explained

### `feat:` - New Features

**Use when**: Adding new functionality to the codebase.

**Examples**:
- `feat(auth): add JWT token refresh endpoint`
- `feat(api): implement rate limiting middleware`
- `feat(ui): add dark mode toggle`

**When NOT to use**: Bug fixes should use `fix:`, not `feat:`

### `fix:` - Bug Fixes

**Use when**: Fixing a bug or defect in existing functionality.

**Examples**:
- `fix(auth): prevent expired tokens from accessing protected routes`
- `fix(api): handle null values in user query results`
- `fix(ui): correct button alignment on mobile devices`

**When NOT to use**: Adding new features should use `feat:`, not `fix:`

### `docs:` - Documentation Changes

**Use when**: Writing or updating documentation, comments, README, or API docs.

**Examples**:
- `docs(readme): add installation instructions`
- `docs(api): document rate limiting headers`
- `docs: add troubleshooting guide`

**Impact**: Does NOT trigger version bumps (not a "feature" or "fix")

### `refactor:` - Code Refactoring

**Use when**: Restructuring code without changing functionality (performance, readability, maintainability).

**Examples**:
- `refactor(auth): extract JWT validation to separate module`
- `refactor(api): simplify error handling logic`
- `refactor: rename misleading variable names`

**Impact**: Does NOT trigger version bumps (internal improvement only)

### `test:` - Test Additions/Changes

**Use when**: Adding, updating, or fixing tests (no production code changes).

**Examples**:
- `test(auth): add tests for JWT expiration`
- `test(api): improve test coverage for rate limiter`
- `test: fix flaky database integration test`

**Impact**: Does NOT trigger version bumps

### `chore:` - Build/Tooling Changes

**Use when**: Updating dependencies, build config, CI/CD, or development tools.

**Examples**:
- `chore(deps): upgrade Node.js to v20.11`
- `chore(build): update webpack configuration`
- `chore(ci): configure GitHub Actions for linting`

**Impact**: Does NOT trigger version bumps

### `perf:` - Performance Improvements

**Use when**: Code optimization that improves performance metrics.

**Examples**:
- `perf(api): cache database queries for 5 minutes`
- `perf(ui): optimize image rendering for 40% faster load time`
- `perf: reduce bundle size by 15%`

**Impact**: Triggers patch version bump (like `fix:`)

### `style:` - Code Style Changes

**Use when**: Formatting, whitespace, or code style changes (no logic changes).

**Examples**:
- `style: reformat code according to ESLint rules`
- `style(css): remove unused CSS classes`
- `style: add missing semicolons`

**Impact**: Does NOT trigger version bumps

## Auto-Generation with `/ccpm:commit`

The `/ccpm:commit` command provides intelligent commit message auto-generation.

### Usage

**Basic usage**:
```bash
/ccpm:commit                    # Auto-detect issue, generate message
/ccpm:commit AUTH-123           # Link specific issue
/ccpm:commit AUTH-123 "Fix login validation"  # Explicit message
```

### How Auto-Detection Works

1. **Detects current git branch** for Linear issue ID
   - Example: `feat/AUTH-123-jwt-auth` → extracts `AUTH-123`
   - Example: `fix/WORK-456-cache-bug` → extracts `WORK-456`

2. **Analyzes git changes** to determine commit type
   - Tests added/modified → `test:`
   - Documentation only → `docs:`
   - Bug fix + test → `fix:`
   - New feature + test → `feat:`

3. **Extracts scope** from changed files
   - Files: `src/auth/jwt.ts`, `src/auth/login.ts` → scope: `auth`
   - Files: `src/api/users.ts`, `src/api/posts.ts` → scope: `api`

4. **Generates message** from:
   - Linear issue title
   - Git diff summary
   - Changed function/class names
   - Test names if tests added

5. **Links to Linear** automatically
   - Adds issue ID to footer
   - Updates Linear with commit link
   - Creates audit trail

### Example Auto-Generation Flow

**Scenario**: Branch `fix/AUTH-123-jwt-expiration`, changed `src/auth/jwt.ts`

```bash
$ /ccpm:commit

Analyzing changes for commit...

Branch: fix/AUTH-123-jwt-expiration
Issue: AUTH-123
Linear Title: "Prevent expired tokens from accessing API"

Changes detected:
- src/auth/jwt.ts: Modified token validation logic
- test/auth/jwt.test.ts: Added 2 tests for expiration

Commit type: fix (bug fix with tests)
Scope: auth
Message: "prevent expired tokens from accessing API"

Generated commit:
```
fix(auth): prevent expired tokens from accessing API

- Added token expiration check in validateToken()
- Added tests for expired token rejection
- Updated middleware to handle token validation errors

Closes AUTH-123
```

Proceed with commit? (yes/no)
```

## Best Practices

### 1. Keep Messages Concise

**First line** should be:
- Under 72 characters
- Complete thought
- Clear, specific (not vague like "fix bug" or "update code")

**✅ Good**: `fix(auth): validate JWT expiration before token use`
**❌ Bad**: `fix: bug` or `fix: updates`

### 2. Use the Scope

Always include scope when possible (what changed):

**✅ Good**: `feat(api):`, `fix(ui):`, `docs(readme):`
**❌ Bad**: `feat: new stuff`, `fix: problem`

### 3. Reference Issues in Footer

Link to Linear issues in commit footer:

```
fix(auth): prevent expired tokens

[body explaining the fix]

Closes AUTH-123
Refs AUTH-120
```

**Common footers**:
- `Closes ISSUE-123` - Closes the issue
- `Fixes ISSUE-123` - Fixes the issue
- `Refs ISSUE-123` - Just references
- `BREAKING CHANGE: ...` - Documents breaking changes

### 4. Add Body for Complex Changes

For significant changes, add explanation:

```
feat(auth): implement OAuth2 authentication flow

- Added OAuth2 provider integration
- Implemented token refresh mechanism
- Added session persistence to Redis
- Updated user model with OAuth fields

This enables third-party sign-in for better UX.
Addresses AUTH-127 requirements.

Closes AUTH-127
```

### 5. Group Related Changes

If multiple related files change, us