commit-message-generating

Original source / Raw SKILL.md

---
name: commit-message-generating
version: 3.0.0
description: Generate and validate conventional commit messages with confidence-based type/scope detection. Analyzes code changes to determine type, infer scope from file paths, and detect breaking changes. Use when writing or validating commit messages.
allowed-tools: Read, Bash, AskUserQuestion
---

# Commit Message Generating

Generate and validate conventional commit messages for projects with high commit message quality requirements.

## Requirements

- Git repository with commit history
- Explicit commit reference (any valid git ref)
- Optional: `.commitmsgrc.md` for custom project rules

## Mode Detection

- **Generation**: "generate", "create", "write" or `/commit-gen`
- **Validation**: "validate", "check", "verify" or `/commit-check`

## Configuration

Load `.commitmsgrc.md` from project root if present. Extract: `types`, `scopes`, `require_scope`, `required_ticket_format`, `max_subject_length`, `require_body_for_breaking`, `add_attribution_footer`.

**Defaults:** Types (feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert), Subject max 72 chars, Body required for breaking changes, Attribution footer disabled.

---

## Generation Workflow

### Step 1: Load Config and Resolve Reference

1. Read `.commitmsgrc.md` if present, use defaults otherwise
2. Resolve commit reference: `git rev-parse --verify <ref>^{commit}`
3. Get diff and file list: `git show <sha> --format="" --name-status` and `git show <sha> --format=""`

**Error:** Invalid ref → show `git log --oneline -5`

### Step 2: Determine Type

Analyze diff to determine type. See [Type Detection](mdc:references/type-detection.md) for decision tree and confidence rules.

- HIGH/MEDIUM confidence → use type directly
- LOW confidence → use AskUserQuestion with options from analysis
- Store breaking change indicators for later use

### Step 3: Infer Scope

Infer scope from file paths. See [Scope Detection](mdc:references/scope-detection.md) for inference rules.

- HIGH/MEDIUM confidence → use scope directly
- LOW confidence → use AskUserQuestion
- Omit scope when redundant (docs type + README, style type, ci type, root configs)

### Step 4: Craft Subject and Message

**Subject rules:** Imperative mood, lowercase, no period, max length from config, specific description.

**Message format:**
```
type(scope): subject

body (if complex changes or breaking)

BREAKING CHANGE: description (if breaking)
Refs: TICKET-123 (if required_ticket_format)

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

Co-authored-by: Claude <model-name> <[email protected]> (if add_attribution_footer)
```

Note: Use your actual model name (e.g., "Opus 4.5", "Sonnet 4") for `<model-name>`.

### Step 5: Validate and Present

Quick self-check: type matches changes, scope matches files, subject is accurate. If issues found, fix and note. Present the generated message.

**Output format:** Brief analysis (type reasoning, scope reasoning, breaking changes), then the commit message.

---

## Validation Workflow

### Step 1: Load Config and Get Commit

1. Read `.commitmsgrc.md` if present
2. Resolve commit reference and get: message, diff, files
3. Parse message: type, scope, breaking marker, subject, body, footer

### Step 2: Format Compliance

Check against Conventional Commits spec and project config:
- Type in allowed list
- Scope format (kebab-case) and in allowed list if configured
- Subject: no period, lowercase after colon, imperative mood
- Breaking marker (!) has BREAKING CHANGE footer
- Subject length within limits

### Step 3: Consistency Check

Analyze actual changes and compare:
- Type accuracy: Does type match change nature?
- Scope accuracy: Do files match claimed scope?
- Subject accuracy: Does subject describe changes?
- Breaking changes: Properly marked?

### Step 4: Validate Body Quality

Validate body quality. See [Body Validation](mdc:references/body-validation.md) for checks.

- Check presence requirements (required for breaking changes, recommended for 5+ files)
- Check content quality (WHY not WHAT)
- Check structure (blank line, line length)
- For breaking changes: verify migration instructions

### Step 5: Generate Report

Format validation results directly using these templates:

**Status Icons:** PASS=✓, WARN=⚠, FAIL=✗

**Concise** (for batch operations):
```
Commit {hash}: {STATUS} {icon} ({N} issues)
```

**Standard** (default):
```
Commit Message Validation Report
=================================

Commit: {hash}
Message: "{message}"

Format Compliance: {STATUS} {icon}
Consistency Check: {STATUS} {icon}
  {Only WARN/FAIL items with icon prefix}
Body Quality: {STATUS} {icon}
  {Only WARN/FAIL items with icon prefix}

Recommendations:
  1. {First recommendation from failed checks}
```

**Verbose** (for complex issues):
- Include all check details with reasoning
- Add suggested improved message if issues found

Present the formatted report to user.

---

## Git Commands

Use these git commands directly:

```bash
# Resolve reference to SHA
git rev-parse --verify <ref>^{commit}

# Commit files and diff
git show <sha> --name-status --format=''
git show <sha> --format=''

# Commit message
git log -1 --format='%B' <sha>
```

---

## Error Handling

- Not a git repo → suggest `git init`
- Invalid commit ref → show recent commits with `git log --oneline -5`
- Invalid config → warn, use defaults, continue

## Output Guidelines

- **Generation:** Brief analysis, then commit message (no validation checkmarks)
- **Validation:** Formatted report with status, issues, recommendations
- Adapt verbosity: verbose for complex/uncertain, concise for batch operations


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### references/body-validation.md

```markdown
# Body Validation

Validate commit message body: presence, content quality, and migration instructions.

## Presence Checks

**Body Required (FAIL if missing):**
- Breaking changes (when config.require_body_for_breaking: true)
- Type in config.require_body_for_types list

**Body Recommended (WARN if missing):**
- 5+ files changed

**Body Optional:**
- Simple changes, trivial commits (style, docs, chore)

## Content Quality

Check if body explains **WHY** (motivation) not **WHAT** (obvious from code).

**Good signals (WHY):** "caused", "because", "motivation", metrics, user impact, trade-offs

**Bad signals (WHAT):** "Added", "Created", "Updated", "Modified", file names

**Examples:**
- Bad: "Added RedisService class with cache methods"
- Good: "File-based caching caused 60% slower responses with multiple servers. Redis provides shared cache."

## Structure Rules

- Blank line after subject (FAIL if missing)
- Lines ~72 chars (WARN if >87)

## Migration Instructions (Breaking Changes)

For breaking changes, verify body includes:
1. Clear statement of what broke
2. Step-by-step migration instructions
3. Before/after examples

**Bad:** "BREAKING CHANGE: API changed. Update your code."

**Good:**
```
BREAKING CHANGE: Auth endpoint changed from /auth/login to /auth/oauth.

Migration:
1. Register OAuth app
2. Update endpoints
3. Handle redirect flow
```

## Validation Algorithm

1. Check if body required → FAIL if missing when required
2. Check content quality → WARN if just restates code
3. Check structure → FAIL if no blank line after subject
4. For breaking changes: Check migration → FAIL if missing/vague

**Overall Status:** Any FAIL → FAIL | Any WARN → WARN | All PASS → PASS

## Examples

### Missing Body for Breaking Change
Status: FAIL
Checks:
- Presence: FAIL - "Body required for breaking changes"
- Migration: FAIL - "No migration instructions"

Recommendation: Add body explaining impact and migration with step-by-step instructions and before/after examples.

### Good Body
Status: PASS
Checks:
- Presence: PASS - "Body present and provides context"
- Content: PASS - "Explains motivation and includes metrics"
- Structure: PASS - "Proper formatting with paragraphs"

### Body Restates Code
Status: WARN
Checks:
- Presence: PASS - "Body present"
- Content: WARN - "Body describes WHAT changed, not WHY"

Recommendation: Explain motivation - why was this change needed? What problem does it solve?

## Key Principles

1. **Breaking changes always need body + migration**
2. **WHY over WHAT** - Motivation matters more than description
3. **Specific is better** - Metrics, examples, clear steps
4. **Actionable recommendations** - Tell exactly what to add

```

### references/consistency-validation.md

```markdown
# Consistency Validation

Validate that commit messages accurately describe code changes.

## Validation Dimensions

1. **Type** - Does type match change nature?
2. **Scope** - Does scope match changed files?
3. **Subject** - Does subject describe what changed?
4. **Breaking** - Are breaking changes marked?
5. **Body** - Present when needed? Explains WHY?

## Common Inconsistencies

| Issue | Example | Fix |
|-------|---------|-----|
| Type mismatch | `fix: add feature` | `feat: add feature` |
| Wrong scope | `feat(auth): add API endpoint` | `feat(api): add endpoint` |
| Vague subject | `fix: fix bug` | `fix(cache): resolve memory leak` |
| Missing `!` | `refactor(api): change endpoints` + BREAKING | `refactor(api)!: change endpoints` |
| Missing footer | `feat(api)!: change auth` (no BREAKING CHANGE) | Add BREAKING CHANGE footer |

## Type Validation

- **feat** → New functionality, endpoints, features
- **fix** → Corrects wrong behavior, patches bugs
- **docs** → Documentation only
- **style** → Code formatting (no logic change)
- **refactor** → Code restructuring, no behavior change
- **perf** → Performance optimization
- **test** → Test changes only
- **build** → Build system, dependencies
- **ci** → CI/CD configuration
- **chore** → Maintenance tasks
- **revert** → Revert previous commit

## Breaking Change Rules

Mark as breaking when:
- API signature changes (params added/removed)
- Public methods removed/renamed
- Return types changed
- URL/endpoint paths changed

NOT breaking:
- Optional parameters added
- New methods (additive)
- Internal changes

## Severity Levels

- **FAIL**: Wrong type, unmarked breaking change, completely wrong subject
- **WARN**: Scope too broad, subject vague, minor ambiguity
- **PASS**: Minor wording, acceptable omissions

```

### references/custom-rules.md

```markdown
# Custom Rules Configuration

Configure project-specific rules via `.commitmsgrc.md` in project root.

## Configuration Options

```yaml
---
# Required: Allowed commit types (example subset - see commitmsgrc-template.md for all 11 types)
types: [feat, fix, docs, refactor, test, chore]

# Optional: Allowed scopes (empty = infer from files)
scopes: [api, auth, ui, db]

# Optional: Require scope in all commits
require_scope: false

# Optional: Ticket reference pattern (regex)
required_ticket_format: "JIRA-\\d+"

# Optional: Subject line max length (default: 72)
max_subject_length: 72

# Optional: Require body for breaking changes (default: true)
require_body_for_breaking: true
---
```

## Example Configurations

### Minimal
```yaml
---
types: [feat, fix, docs, refactor, test, chore]
---
```

### Enterprise
```yaml
---
types: [feat, fix, docs, refactor, test]
scopes: [api, auth, billing, ui]
require_scope: true
required_ticket_format: "JIRA-\\d+"
max_subject_length: 50
---
```

### Open Source
```yaml
---
types: [feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert]
required_ticket_format: "#\\d+"
---
```

## Loading Behavior

1. Check for `.commitmsgrc.md` in project root
2. Parse YAML frontmatter
3. Apply custom rules (or defaults if missing/invalid)
4. Warn on invalid config, continue with defaults

```

### references/examples.md

```markdown
# Examples

Quick reference examples for generation and validation.

## Generation

### New Feature
```
feat(auth): add JWT token generation service

Implements JWT token creation with configurable expiration.
Uses HS256 algorithm with secret from environment.
```

### Bug Fix
```
fix(auth): correct age validation boundary

Allows 18-year-olds to register (was incorrectly requiring >18).
```

### Breaking Change
```
refactor(api)!: migrate user endpoints to v2

BREAKING CHANGE: User endpoints moved from /api/user to /api/v2/users.
Update client requests to new endpoint paths.
```

### Performance
```
perf(db): optimize user query with indexing

Added composite index on (email, status) columns.
Query time reduced from 450ms to 67ms (85% improvement).
```

## Validation Reports

### Pass
```
Commit: abc123f
Message: "fix(api): resolve token expiration bug"

Format Compliance: PASS ✓
Consistency Check: PASS ✓
```

### Fail - Type Mismatch
```
Commit: def456a
Message: "fix: update authentication"

Format Compliance: PASS ✓
Consistency Check: FAIL ✗
  ✗ Type mismatch: New endpoint added, should be 'feat'

Recommendations:
  1. Change type from 'fix' to 'feat'
```

## Common Mistakes

| Mistake | Wrong | Correct |
|---------|-------|---------|
| Wrong tense | `Added feature` | `add feature` |
| Vague subject | `fix: fix bug` | `fix(cache): resolve memory leak` |
| Missing `!` | `refactor(api): change endpoints` + BREAKING footer | `refactor(api)!: change endpoints` |
| Ends with period | `feat: add auth.` | `feat: add auth` |
| Too long | 90+ char subject | 50-72 chars, details in body |

```

### references/scope-detection.md

```markdown
# Scope Detection

Determine conventional commit scope from file paths with confidence-based analysis.

## Scope Inference

Map directory structure to scope:
- `src/auth/**` → auth
- `src/api/**` → api
- `src/components/**` → ui
- `packages/core/**` → core (monorepo)
- `apps/web/**` → web (monorepo)

**Naming conventions:**
- Lowercase, kebab-case: `user-profile` not `UserProfile`
- Singular preferred: `user` not `users`
- Concise (1-2 words): `api` not `api-v2-users`

## Confidence Levels

**HIGH**: All files in single clear module
- `src/auth/LoginService.ts`, `src/auth/types.ts` → auth

**MEDIUM**: Related modules with clear feature
- `src/api/users.ts`, `src/services/UserService.ts` → user (feature-based)

**LOW**: Multiple unrelated modules → use AskUserQuestion
- `src/auth/`, `src/database/`, `src/cache/` → ask user

## When to Omit Scope

Omit scope when:
- Type is `docs` with project-wide docs (README.md)
- Type is `style` (formatting only)
- Type is `ci` (CI config only)
- Root-level config files (.gitignore, LICENSE)
- Cross-cutting changes with no clear module

## Config Validation

If project config has `scopes` list:
1. Check if inferred scope is in allowed list
2. If not found → LOW confidence, ask user for closest match
3. If `require_scope: true` → never suggest omitting

## User Question Format (LOW Confidence)

When confidence is LOW, ask the user:

```
AskUserQuestion(
  question="Which scope best describes these changes?",
  header="Commit Scope",
  multiSelect=false,
  options=[
    {label: "auth", description: "Changes in src/auth/ directory"},
    {label: "db", description: "Database migration changes"},
    {label: "Omit scope", description: "Cross-cutting concern"}
  ]
)
```

Include 2-4 options. Best guess first, "Omit scope" last.

## Examples

### HIGH Confidence: Single Module
Scope: `auth`
Reasoning: "All files in src/auth/ directory: LoginService.ts, AuthMiddleware.ts, types.ts"

### MEDIUM Confidence: Feature-based
Scope: `user`
Reasoning: "Files span api, services, models but all relate to user management"

### HIGH Confidence: Omit Scope
Scope: (omit)
Reasoning: "Only README.md changed. Type is 'docs' - scope redundant."

### LOW Confidence: Ask User
Reasoning: "Files in auth/, database/, cache/ - no clear primary module"
Action: Ask user with options for auth, db, and "Omit scope"

## Key Principles

1. **Infer from paths** - Directory structure is the primary signal
2. **Be specific but not granular** - `auth` not `AuthController`
3. **Omit when redundant** - docs type + README = no scope needed
4. **Respect project config** - Use allowed scopes when configured

```

### references/type-detection.md

```markdown
# Type Detection

Determine conventional commit type from git diffs with confidence-based analysis.

## Decision Tree

Apply in priority order:

1. Reverting commit? → `revert`
2. Only docs (*.md, comments)? → `docs`
3. Only formatting/whitespace? → `style`
4. Only test files? → `test`
5. Only build/deps (package.json, Dockerfile)? → `build`
6. Only CI configs (.github/workflows)? → `ci`
7. New functionality added? → `feat`
8. Fixes broken behavior? → `fix`
9. Performance improvements? → `perf`
10. Code restructuring (same behavior)? → `refactor`
11. Otherwise → `chore`

## Confidence Levels

**HIGH**: Single type clearly dominates, no conflicting signals
- New files + exports + routes → feat
- Logic error fix → fix
- Only README.md → docs

**MEDIUM**: Primary type clear with secondary changes
- feat + minor refactor → feat
- Multi-module but related changes

**LOW**: Multiple types equally valid → use AskUserQuestion
- feat + fix equally present
- refactor + perf ambiguous

## User Question Format (LOW Confidence)

When confidence is LOW, ask the user:

```
AskUserQuestion(
  question="Which commit type best describes these changes?",
  header="Commit Type",
  multiSelect=false,
  options=[
    {label: "feat - New feature", description: "Specific reason from diff (~100 chars)"},
    {label: "fix - Bug fix", description: "Specific reason from diff (~100 chars)"}
  ]
)
```

Include 2-4 plausible options. Best guess first.

## Breaking Change Detection

Mark as breaking when:
- API signature changes (required params added/removed)
- Public methods removed or renamed
- Return types changed
- Database schema breaking changes
- Default behavior changed

NOT breaking:
- Internal/private changes
- Optional parameters added
- New methods (additive)

## Examples

### HIGH Confidence: New Feature
Type: `feat`
Reasoning: "New OAuth2Service class with authenticate() method and POST /auth/oauth2 endpoint added"
Breaking: false

### HIGH Confidence: Bug Fix
Type: `fix`
Reasoning: "Changed age check from > to >= to include 18-year-olds - fixes incorrect denial of access"
Breaking: false

### LOW Confidence: Ambiguous
Type: Best guess `feat`
Reasoning: "New v2 API endpoint (feat) and v1 bug fix (fix) both present. Primary unclear."
Action: Ask user with options for feat and fix

### Breaking Change Detected
Type: `feat`
Reasoning: "Response property 'userId' renamed to 'id' - clients expecting userId will fail"
Breaking: true
Breaking reasoning: "Response format changed: userId → id. Existing clients will break."

## Key Principles

1. **Be specific in reasoning** - Reference actual code patterns observed
2. **Don't inflate confidence** - LOW is fine when genuinely uncertain
3. **Breaking changes are critical** - Analyze API compatibility carefully
4. **Mixed changes** - Use dominant type if 80%+, otherwise LOW confidence

```