dance-lessons-coach/.vibe/skills/commit-message/SKILL.md

---
name: commit-message
description: Helps create proper Gitmoji commit messages following the Common Gitmoji Reference from AGENTS.md. Use when creating commits to ensure consistent, visual commit messages. Includes Git hooks for automatic code formatting and dependency management.
license: MIT
metadata:
  author: dance-lessons-coach Team
  version: "1.1.0"
  based-on: AGENTS.md Common Gitmoji Reference
---

# Commit Message Skill

This skill helps create proper Gitmoji commit messages following the Common Gitmoji Reference from AGENTS.md. It also includes Git hooks for automatic code formatting and dependency management.

## Gitmoji Reference

### Feature Changes
- **✨ `:sparkles:` feat**: New feature
- **🐛 `:bug:` fix**: Bug fix
- **♻️ `:recycle:` refactor**: Code refactoring
- **🔥 `:fire:` remove**: Remove code/files
- **🚀 `:rocket:` perf**: Performance improvements
- **🔒 `:lock:` security**: Security fixes

### Documentation & Style
- **📝 `:memo:` docs**: Documentation
- **🎨 `:art:` style**: Code formatting
- **📦 `:package:` dependencies**: Dependency changes

### Platform-Specific
- **🐧 `:penguin:` linux**: Linux-specific changes
- **🍎 `:apple:` macos**: macOS-specific changes
- **🪟 `:window:` windows**: Windows-specific changes

### Testing & CI
- **🧪 `:test_tube:` test**: Tests
- **🤖 `:robot:` ci**: CI/CD changes

### Other
- **📈 `:chart_with_upwards_trend:` analytics**: Analytics/SEO
- **🌐 `:globe_with_meridians:` i18n**: Internationalization
- **⚡ `:zap:` performance**: Performance improvements
- **🔧 `:wrench:` chore**: Build/config changes

## Usage Examples

### New Feature
```bash
git commit -m "✨ feat: add user authentication"
git commit -m "✨ feat: implement BDD testing framework"
```

### Issue References
```bash
# When closing a single issue
git commit -m "✨ feat: implement workflow optimization (closes #2)"

# When fixing a bug
git commit -m "🐛 fix: resolve CI job failure (fixes #5)"

# When work is related to an issue
git commit -m "📝 docs: update workflow documentation (related to #2)"

# When referencing for context
git commit -m "♻️ refactor: clean up CI code (see #3)"

# For PR merges closing multiple issues (USE SEPARATE LINES!)
git commit -m "✨ merge: implement authentication system

Closes #4
Closes #5
Closes #6
Refs #7, #8"
```

### Bug Fix
```bash
git commit -m "🐛 fix: resolve port conflict in test server"
git commit -m "🐛 fix: handle JSON escaping in feature files"
```

### Documentation
```bash
git commit -m "📝 docs: add comprehensive BDD testing guide"
git commit -m "📝 docs: update AGENTS.md with commit conventions"
```

### Refactoring
```bash
git commit -m "♻️ refactor: move log setup to config package"
git commit -m "♻️ refactor: improve step pattern matching"
```

### Tests
```bash
git commit -m "🧪 test: add BDD scenarios for greet service"
git commit -m "🧪 test: implement health endpoint validation"
```

### Configuration
```bash
git commit -m "🔧 chore: add log output file configuration"
git commit -m "🔧 chore: update build system scripts"
```

## Issue Reference Integration

The skill now integrates with Gitea client to suggest issue references:

### Automatic Issue Suggestions (NON-BLOCKING)

When you run `git commit`, the pre-commit hook will:
1. **Check for open issues in Gitea** (if available)
2. **Display issue suggestions** (helpful information only)
3. **Suggest reference formats** (optional guidance)

**Important:** This is **completely non-blocking** - you can always commit with any message!

The suggestions are just helpful reminders, never requirements.

**Example Output:**
```
🔍 Checking for relevant issues...
📋 Found 1 open issue(s):
  #2: Optimize Gitea Workflow for Main Branch
    https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues/2

💡 Suggested commit message formats:
  - closes #<number>      (when issue is fully resolved)
  - fixes #<number>       (when fixing a bug)
  - resolves #<number>    (when resolving an issue)
  - related to #<number>   (when work is related)
  - see #<number>         (when referencing for context)

Example: ✨ feat: implement workflow (closes #2)
```

### Issue Reference Formats

**Standard Formats:**
- `closes #2` - When issue is fully resolved
- `fixes #5` - When fixing a specific bug
- `resolves #3` - When resolving an issue
- `related to #2` - When work is related
- `see #4` - When referencing for context

**GitHub/Gitea Compatible:**
These formats are recognized by both GitHub and Gitea to automatically close issues.

### ⚠️ IMPORTANT: Multiple Issue Closing

**For PR merge commits that close multiple issues, use SEPARATE lines:**

```markdown
✨ merge: implement authentication system

Closes #4
Closes #5  ← Use separate lines!
Closes #6  ← This ensures ALL issues are closed
Refs #7, #8
```

**❌ Avoid this (only closes first issue):**
```markdown
✨ merge: implement authentication system

Closes #4, #5, #6  ← Only #4 gets closed!
Refs #7, #8
```

**Why this matters:** GitHub/Gitea issue trackers typically only process the FIRST issue reference when multiple issues are listed on the same line. Using separate lines ensures ALL referenced issues are properly closed.

## Git Hooks for Code Quality

The project includes Git hooks that automatically run before commits to ensure code quality:

### Pre-commit Hook (NON-BLOCKING)
- **Location**: `.git/hooks/pre-commit`
- **Automatically runs**:
  - **Issue reference suggestions** (helpful but optional)
  - `go mod tidy` - Cleans up and organizes Go dependencies
  - `go fmt` - Formats staged Go files according to standards
  - Auto-adds modified files to the commit

**Behavior:**
- ✅ **Always allows commits** - never blocks you
- ✅ **Shows helpful suggestions** - you can ignore them
- ✅ **Formats Go code automatically** - but only if you're in a Go project
- ✅ **Gracefully handles errors** - continues even if something fails

### How It Works

```bash
# When you commit:
git add .
git commit -m "✨ feat: add new feature"

# The hook automatically:
1. Runs `go mod tidy`
2. Runs `go fmt` on all Go files
3. Adds any modified files to your commit
4. Allows commit if successful
```

### Benefits
- Ensures consistent code formatting
- Maintains clean dependency management
- Prevents common Go code issues
- Runs automatically - no manual steps needed

## Best Practices

### Commit Message Structure
```
<gitmoji> <type>: <description>

<optional body with details>

<optional footer with references>
```

### Examples

**Simple commit:**
```
✨ feat: add skill_creator framework
```

**Detailed commit:**
```
✨ feat: implement BDD testing with Godog

- Add features/greet.feature and features/health.feature
- Implement step definitions in pkg/bdd/steps/
- Create hybrid in-process test server
- Add comprehensive documentation

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
```

**Complex commit:**
```
🧪 test: add comprehensive BDD test suite

- Implement greet service scenarios
- Add health endpoint validation
- Create test server on port 9191
- Ensure no undefined/pending steps

Resolves: #42
Ref: AGENTS.md
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
```

## Validation

### Check Commit Message Format
```bash
# Verify gitmoji is present
echo "$commit_message" | grep -E "^[[:space:]]*[🎨✨🐛📝🔧♻️🚀🔒📦🔥🐧🍎🪟🤖🧪📈🌐⚡]"

# Verify type: description format
echo "$commit_message" | grep -E "^[🎨✨🐛📝🔧♻️🚀🔒📦🔥🐧🍎🪟🤖🧪📈🌐⚡][[:space:]]+[a-z_]+:"
```

### Common Validation Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| Missing gitmoji | No emoji at start | Add appropriate gitmoji from reference |
| Wrong type | Type doesn't match emoji | Use correct type from reference table |
| Missing colon | No colon after type | Add colon: `feat:` not `feat` |
| Long first line | First line > 50 chars | Keep first line concise, add details in body |

## Git Hooks Reference

### Hook Location
```bash
.git/hooks/pre-commit
```

### Hook Content
```bash
#!/bin/sh

# dance-lessons-coach pre-commit hook
# Runs go mod tidy and go fmt before allowing commits

echo "Running pre-commit hooks..."

# Check if we're in a Go project
if [ ! -f "go.mod" ]; then
    echo "Not a Go project, skipping hooks"
    exit 0
fi

# Run go mod tidy
echo "Running go mod tidy..."
go mod tidy
if [ $? -ne 0 ]; then
    echo "ERROR: go mod tidy failed"
    exit 1
fi

# Check if go.mod or go.sum were modified
if git diff --cached --name-only | grep -qE '(go\.mod|go\.sum)'; then
    echo "go.mod or go.sum changed, adding to commit..."
    git add go.mod go.sum
fi

# Run go fmt on all Go files
echo "Running go fmt..."
GOFILES=$(find . -name '*.go' -not -path "./vendor/*" -not -path "./.git/*")
if [ -n "$GOFILES" ]; then
    gofmt -w $GOFILES
    if [ $? -ne 0 ]; then
        echo "ERROR: go fmt failed"
        exit 1
    fi
    
    # Add formatted files to commit
    git add $GOFILES
fi

echo "Pre-commit hooks completed successfully"
exit 0
```

### Customization

To modify the hook:
```bash
# Edit the hook
nano .git/hooks/pre-commit

# Make it executable (if needed)
chmod +x .git/hooks/pre-commit
```

### Disabling Hooks

To skip hooks for a single commit:
```bash
git commit --no-verify -m "✨ feat: add new feature"
```

## References

- [Gitmoji Official Site](https://gitmoji.dev)
- [Common Gitmoji Reference in AGENTS.md](#common-gitmoji-reference)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Git Hooks Documentation](https://git-scm.com/docs/githooks)

## Troubleshooting

### Finding the Right Gitmoji
```bash
# Search for appropriate gitmoji
grep "feature\|new" .vibe/skills/commit_message/SKILL.md
# Result: ✨ :sparkles: feat - New feature
```

### Commit Message Too Long
```bash
# Split into concise first line + detailed body
git commit -m "✨ feat: add BDD framework" -m "- Implement Godog testing" -m "- Add greet/health features" -m "- Create test server"
```

### Multiple Changes in One Commit
```bash
# Use comprehensive description
git commit -m "♻️ refactor: improve BDD implementation" -m "- Update step patterns to match Godog exactly" -m "- Add JSON response validation" -m "- Implement server verification" -m "- Update all templates and documentation"
```

### Git Hooks Issues

**Hook fails with error:**
```bash
# Check the specific error message
# Fix the underlying issue (e.g., Go syntax error, dependency issue)
# Commit again
```

**Hook runs too slow:**
```bash
# The hooks are optimized to only process necessary files
# If performance is an issue, check for very large Go files
# Consider splitting large files into smaller modules
```

**Need to bypass hooks temporarily:**
```bash
# Use --no-verify flag
git commit --no-verify -m "⚡ chore: quick fix"

# Remember to run hooks manually later
go mod tidy
gofmt -w .
```

## Assets

- **gitmoji-cheatsheet.md**: Quick reference for common gitmoji
- **commit-template.txt**: Git commit message template
- **validate-commit.sh**: Commit message validation script
- **git-hooks/**: Git hooks for automatic code quality
  - **pre-commit**: Hook that runs `go mod tidy` and `go fmt`
  - **README.md**: Documentation for Git hooks