dev-git-commit-message

What this skill does

# Git Commit Message Generator

**Auto-generates conventional commit messages from git diffs with tiered format enforcement**

## Purpose

Analyze staged git changes and generate concise, meaningful commit messages following a tiered Conventional Commits specification. This skill examines file modifications, additions, and deletions to infer the type and scope of changes, producing commit messages that match the importance of the change - from detailed documentation for critical features to concise messages for minor updates.

**Key Innovation**: Three-tier format system that balances thoroughness for critical commits (feat, fix, security) with efficiency for routine changes (docs, chore, style).

## When This Skill Activates

- When `/commit-msg` command is invoked
- When invoked from a `commit-msg`/`prepare-commit-msg` hook (if installed)
- When user requests commit message suggestions
- When analyzing changes before creating a commit

## Core Capabilities

**1. Diff Analysis**
- Parse `git diff --staged` output
- Identify modified, added, and deleted files
- Analyze code changes (additions, deletions, modifications)
- Detect patterns across multiple files

**2. Change Classification**
- Determine commit type from changes:
  - `feat`: New features or functionality
  - `fix`: Bug fixes
  - `security`: Security fixes or hardening
  - `refactor`: Code restructuring without behavior change
  - `docs`: Documentation changes
  - `style`: Formatting, whitespace, code style
  - `test`: Adding or modifying tests
  - `chore`: Build process, dependencies, tooling
  - `perf`: Performance improvements
  - `ci`: CI/CD configuration changes
  - `build`: Build system changes
  - `revert`: Reverting previous commits

**3. Scope Detection**
- Infer scope from file paths and patterns:
  - Directory names (e.g., `api`, `auth`, `ui`)
  - File name patterns (e.g., `*.test.js` → `tests`)
  - Framework conventions (e.g., `components/`, `services/`)

**4. Message Generation**
- Format: `type(scope): description`
- Enforce tier limits: Tier 1 summary max 50 chars; Tier 2/3 summary max 72 chars (ideal 50)
- Use imperative mood ("add" not "added")
- Focus on "what" and "why", not "how"
- Provide 2-3 alternative suggestions

## Tier System: Smart Format Enforcement

This skill uses a **three-tier format system** that matches message detail to commit criticality:

### Tier 1: Critical Commits (feat, fix, perf, security)

**Requirements**: Detailed documentation with impact statement

**Format**:
```
type(scope): summary line (max 50 chars)

- Detailed description point 1
- Detailed description point 2
- Detailed description point 3

This change [impact statement describing user-facing benefit or risk addressed].

Affected files/components:
- path/to/file1
- path/to/file2
```

**Why**: Features, fixes, and performance changes affect users directly and need thorough documentation for future reference and changelog generation.

### Tier 2: Standard Commits (refactor, test, build, ci)

**Requirements**: Brief context and file list

**Format**:
```
type(scope): summary line (max 72 chars)

Brief explanation of what changed and why (1-2 sentences).

Files: path/to/file1, path/to/file2
```

**Why**: Internal improvements need context for maintainability but don't require extensive documentation.

### Tier 3: Minor Commits (docs, style, chore)

**Requirements**: Summary line, optional description

**Format**:
```
type(scope): summary line (max 72 chars)

[Optional: Additional context if helpful]
```

**Why**: Documentation and routine maintenance are self-explanatory from the diff; verbose messages add noise.

## Workflow

```text
0. Pre-staging typecheck (if project uses TypeScript):
   - Run `tsc --noEmit` on changed files before staging
   - Fix type errors before committing (avoids pre-commit hook retry loops)
1. Get staged changes (staged only, not working tree):
   - git diff --staged --name-status
   - git diff --staged --stat
   - git diff --staged
2. Load config → frameworks/shared-skills/skills/dev-git-commit-message/config.yaml
3. Analyze changes:
   - Count files modified/added/deleted
   - Identify primary change type using analysis patterns
   - Detect scope from project structure (config.yaml)
   - Determine tier (1/2/3) based on commit type
   - Extract key modifications
4. Generate commit messages:
   - Apply tier-appropriate format
   - Primary suggestion (best match)
   - Alternative 1 (different scope/angle)
   - Alternative 2 (broader/narrower focus)
5. Validate against rules:
   - Check forbidden patterns
   - Verify required elements present
   - Ensure length limits
6. Present to user with explanation and tier info
```

## Optional Modes (If Supported By The Caller)

- `--validate "<message>"`: Validate a commit message without generating suggestions (format/type/scope/length/forbidden patterns; then report required Tier 1/2/3 elements if missing).
- `--tier <1|2|3>`: Force the tier format (overrides auto-detection).
- `--interactive` or `-i`: Ask for confirmation of type, scope, and summary before final output.

## Output Format

```
[NOTE] Suggested Commit Messages (based on X files changed)

PRIMARY:
feat(api): add user authentication endpoints

ALTERNATIVES:
1. feat(auth): implement JWT token validation
2. feat: add user authentication system

ANALYSIS:
- 3 files modified in src/api/
- New functions: authenticateUser, generateToken
- Primary change: new feature (authentication)
- Scope detected: api/auth
```

## Conventional Commits Quick Reference

**Type Guidelines**:
- `feat`: User-facing features or API additions
- `fix`: Corrects incorrect behavior
- `refactor`: Improves code without changing behavior
- `docs`: README, comments, documentation files
- `style`: Formatting only (prettier, eslint --fix)
- `test`: Test files or test utilities
- `chore`: Build scripts, package updates, config
- `perf`: Measurable performance improvements
- `ci`: GitHub Actions, CircleCI, build pipelines

**Scope Guidelines**:
- Use lowercase
- Be specific but not too narrow
- Match your project's module structure
- Omit if changes span multiple unrelated areas

**Description Guidelines**:
- Start with lowercase verb
- No period at the end
- Be specific and concise
- Focus on user impact for `feat` and `fix`

## Edge Cases

**Multiple unrelated changes**:
- Suggest splitting into separate commits
- If forced to combine, use broader scope or omit scope

**Breaking changes**:

- Append exclamation mark after type/scope (example: feat(api)!: change auth flow)
- Include BREAKING CHANGE in body (handled by user)

**WIP or experimental**:
- Use `chore(wip): description` or `feat(experimental): description`

**No meaningful changes**:
- Detect and warn: "No staged changes detected"
- Suggest `git add` commands

## Integration Points

**Pre-commit hook**: Triggered before commit (if installed/configured)
**Slash command**: Manual invocation via `/commit-msg`
**Direct skill call**: From other skills or tools

## Best Practices

1. **Analyze context**: Look at file paths, function names, import statements
2. **Prioritize clarity**: Prefer obvious descriptions over clever ones
3. **Respect conventions**: Follow project's existing commit patterns if detected
4. **Avoid hallucination**: Only describe what's actually in the diff
5. **Be concise**: 50 chars is ideal, 72 is maximum for first line
6. **Stage specific files**: Use `git add <file1> <file2>`, not `git add -A` or `git add .`, to avoid pulling in unrelated changes or sensitive files
7. **Avoid heredoc in sandboxed shells**: Sandboxed environments may block temp file creation for here-documents. Use `git commit -m "$(cat <<'EOF'\nmessage\nEOF\n)"` or pass `-m "message"` directly
8. **Pre-commit typecheck**: Run `tsc --noEmit` on the staged surface before committing to catch type errors early and avoid retry cascades from pre-commit hooks

## Example Analyses

**Scenario 1**: New React component
```
Files: src/components/UserProfi