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 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:

/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

$ /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, use single commit:

git add src/auth/jwt.ts test/auth/jwt.test.ts
git commit -m "fix(auth): validate JWT expiration"

Not:

git add src/auth/jwt.ts
git commit -m "fix(auth): validate JWT expiration"
git add test/auth/jwt.test.ts
git commit -m "test(auth): add JWT expiration tests"

Commit Message Examples

Example 1: Simple Feature

Scenario: Added new user registration endpoint

feat(api): add user registration endpoint

- POST /auth/register creates new user accounts
- Validates email format and password strength
- Returns JWT token on successful registration

Closes AUTH-101

Analysis:

• ✅ Type: feat: (new feature)
• ✅ Scope: api (API endpoint changed)
• ✅ Message: Imperative mood, under 72 chars
• ✅ Body: Clear explanation
• ✅ Issue link: References LINEAR issue

Example 2: Bug Fix

Scenario: Fixed database timeout issue

fix(db): handle connection timeouts gracefully

- Added 30-second connection timeout
- Retry logic with exponential backoff
- Return 503 Service Unavailable to clients
- Log timeout events for monitoring

Fixes DB-456
Refs AUTH-123

Analysis:

• ✅ Type: fix: (bug fix)
• ✅ Scope: db (database layer)
• ✅ Message: Clear problem & solution
• ✅ Body: Technical details
• ✅ Issue links: Primary issue + related

Example 3: Refactoring

Scenario: Extracted authentication logic into module

refactor(auth): extract validation logic to utility module

- Move JWT validation to src/auth/validators.ts
- Extract middleware factory to src/auth/middleware.ts
- Improve code reusability and testability
- No functional changes

Analysis:

• ✅ Type: refactor: (internal improvement)
• ✅ Scope: auth (authentication module)
• ✅ Message: Clear intent (extract, not add)
• ✅ Body: What was extracted + benefit
• ✅ No issue link: Not user-facing change

Example 4: Documentation Update

Scenario: Added API authentication guide

docs(api): add authentication implementation guide

- New section: JWT token flow diagrams
- New section: Token refresh strategy
- Code examples for common authentication patterns
- Links to security best practices

Analysis:

• ✅ Type: docs: (documentation)
• ✅ Scope: api (API documentation)
• ✅ Message: Clear what was added
• ✅ Body: Section breakdown
• ✅ No issue link: Documentation improvement

Example 5: Performance Optimization

Scenario: Added caching to reduce database queries

perf(api): implement request caching for 40% query reduction

- Cache GET requests for 5 minutes (TTL)
- Invalidate cache on POST/PUT/DELETE
- Add Redis cache layer
- Reduces database load by 40% in benchmarks

Closes PERF-234

Analysis:

• ✅ Type: perf: (performance improvement)
• ✅ Scope: api (API layer)
• ✅ Message: Clear improvement + metric (40%)
• ✅ Body: Implementation details
• ✅ Metrics: Quantifiable improvement shown

Example 6: Multi-File Feature

Scenario: Implemented complete authentication system

feat(auth): implement JWT authentication system

- Add JWT token generation and validation
- Add login endpoint with credential verification
- Add logout endpoint with token blacklisting
- Add protected route middleware
- Add 90 tests covering all scenarios

This enables secure user authentication and session management.
Replaces legacy session-based auth system.

Closes AUTH-105
Closes AUTH-106
Closes AUTH-107

Analysis:

• ✅ Type: feat: (new feature)
• ✅ Scope: auth (authentication)
• ✅ Message: High-level overview
• ✅ Body: All components included
• ✅ Multiple issues: References all related tasks
• ✅ Impact statement: Explains change scope

Integration with /ccpm:commit

Command Syntax

/ccpm:commit [issue-id] [message]

Examples:

# Auto-detect everything from current branch
/ccpm:commit

# Specify issue, auto-generate message
/ccpm:commit AUTH-123

# Specify issue and message
/ccpm:commit AUTH-123 "Fix login validation error"

# Just provide message (detects issue from branch)
/ccpm:commit "Refactor authentication module"

What the Command Does

1. Analyzes current git changes
2. Detects commit type from changes
3. Extracts scope from modified files
4. Generates commit message (if not provided)
5. Links to Linear issue
6. Creates the commit
7. Updates Linear with commit link
8. Suggests next action (verification, sync, etc.)

Workflow Example

# 1. Make changes
$ vim src/auth/jwt.ts

# 2. Stage changes
$ git add src/auth/jwt.ts test/auth/jwt.test.ts

# 3. Create conventional commit linked to Linear
$ /ccpm:commit

Analyzing changes...
Branch: fix/AUTH-123-jwt-expiration
Files: src/auth/jwt.ts, test/auth/jwt.test.ts
Type: fix
Scope: auth

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

Proceed? (yes/no)

# 4. Commit created automatically
$ git log -1 --oneline
a1b2c3d fix(auth): prevent expired tokens from accessing API

# 5. Linear updated
AUTH-123 comment added: "Commit: a1b2c3d"

Common Mistakes to Avoid

Mistake 1: Wrong Commit Type

❌ Mistake: Using feat: for a bug fix

feat(auth): fix JWT validation

✅ Correct: Use fix: for bug fixes

fix(auth): validate JWT expiration

Why: Different types trigger different version bumps. A bug fix should not bump minor version.

Mistake 2: Vague Messages

❌ Mistake: Generic, unclear message

fix: update auth
chore: fixes
feat: improvements

✅ Correct: Specific, action-oriented messages

fix(auth): validate JWT expiration before token use
chore(deps): upgrade Node.js to v20.11
feat(api): add user registration endpoint

Mistake 3: Avoiding Issue Links

❌ Mistake: No issue reference

fix(auth): prevent expired tokens

✅ Correct: Link to Linear issue

fix(auth): prevent expired tokens

Closes AUTH-123

Why: Creates audit trail and helps team understand why change was made.

Mistake 4: Past Tense in Message

❌ Mistake: Past tense (non-imperative)

fixed JWT validation
added user registration
refactored auth module

✅ Correct: Imperative mood

fix JWT validation
add user registration
refactor auth module

Mistake 5: Too Much Detail in Subject Line

❌ Mistake: Long, detailed first line

feat(auth): add comprehensive JWT authentication system with token refresh
 and improved security checks including rate limiting and IP whitelisting

✅ Correct: Concise subject (under 72 chars), details in body

feat(auth): add JWT authentication system

- Add token generation and validation
- Add logout with token blacklisting
- Add protected route middleware
- Add rate limiting and IP checks

Integration with CCPM Workflow

In Planning Phase

When planning a task with /ccpm:plan:

Task: "Implement JWT authentication"

Implementation plan:
- [ ] Create auth module
- [ ] Add login endpoint
- [ ] Add protected route middleware
- [ ] Add comprehensive tests

Commits expected:
1. `feat(auth): create JWT authentication module`
2. `feat(api): add login endpoint`
3. `feat(api): add protected route middleware`
4. `test(auth): add JWT validation tests`

During Implementation

When making changes during /ccpm:work:

# 1. Work on feature
$ vim src/auth/jwt.ts

# 2. Run tests
$ npm test

# 3. Create conventional commit
$ /ccpm:commit

# 4. Sync progress
$ /ccpm:sync "Implemented JWT validation"

# 5. Repeat for each logical change

Before Verification

When verifying with /ccpm:verify:

Commit history should show:

a1b2c3d feat(auth): prevent expired tokens from accessing API
b2c3d4e feat(api): add login endpoint
c3d4e5f test(auth): add JWT validation tests

Each commit should:

• ✅ Be conventional format
• ✅ Be linked to Linear issue
• ✅ Have clear, specific message
• ✅ Include related tests

Before Completion

When finalizing with /ccpm:done:

Check commit history:

git log --oneline --grep="ISSUE-123"

Should show:

• ✅ Multiple logical commits (not one giant commit)
• ✅ Clear progression from task start to completion
• ✅ All conventional commits format
• ✅ All linked to issue

Activation Triggers

This skill activates when you:

• Ask "How do I commit changes?"
• Ask "Create a git commit" or "commit my changes"
• Ask "What's a conventional commit?"
• Ask "What should my commit message be?"
• Ask "How do I write commit messages?"
• Ask about "commit message format" or "commit types"
• Run /ccpm:commit command
• Run /ccpm:done (which includes commit step)
• Need help generating or formatting commit messages

Integration with Other CCPM Skills

Works alongside:

• pm-workflow-guide: Suggests committing at right workflow stages
• external-system-safety: If commits trigger external updates (GitHub Actions, CD/CI)
• ccpm-code-review: Verifies commits follow quality standards
• docs-seeker: For commit message examples and best practices

Example combined workflow:

User: "I finished the JWT feature"
       ↓
/ccpm:sync → Update Linear with progress
       ↓
/ccpm:commit → Create conventional commit
       ↓
commit-assistant → Auto-generate message, link to issue
       ↓
/ccpm:verify → Run quality checks on changed code
       ↓
/ccpm:done → Create PR, sync external systems

Summary

This skill ensures:

• ✅ All commits follow conventional commit format
• ✅ Commit messages are clear and specific
• ✅ Issues are properly linked in commits
• ✅ Commit history is searchable and meaningful
• ✅ Automatic changelog generation possible
• ✅ Semantic versioning automation enabled
• ✅ Git history is clean and maintainable

Philosophy: Clear commits enable clear history, which enables automation and team communication.

---

Based on: Conventional Commits 1.0.0 License: MIT CCPM Integration: /ccpm:commit, /ccpm:sync, /ccpm:done