Commit

---
name: ring:commit
description: Smart commit organization with atomic grouping, conventional commits, and trailer management
---

# Smart Commit Organization

## When to use
- User asks to commit changes or says "commit"
- Working directory has staged or unstaged changes ready to commit
- End of a development task where changes need to be recorded

## Skip when
- No changes in working directory
- Changes are still work-in-progress
- User explicitly wants raw git commands without smart grouping

Analyze changes, group into coherent atomic commits, create signed commits following repository conventions.

## Smart Commit Organization

Analyze → Group → Order → Confirm → Execute.

**Grouping principles:**

| Pattern | Group |
|---------|-------|
| Implementation + tests | Together (same commit) |
| package.json, *-lock.json | Dependency changes |
| *.md, docs/ | Documentation |
| Same module/directory | Often related |

**Commit order:** dependencies first → core changes → tests with implementation → docs last.

**Single commit when:** all changes are one coherent feature/fix, or user provides a specific message.  
**Multiple commits when:** changes span different concerns.

## ⛔ HARD STOP — TRAILER RULES

**THE MOST COMMON MISTAKE:** Putting trailer text INSIDE the `-m` quotes.

```bash
# ❌ WRONG — trailer text INSIDE -m quotes
git commit -m "feat: add feature

X-Lerian-Ref: 0x1"

# ✅ CORRECT — --trailer is a SEPARATE argument OUTSIDE quotes
git commit -S -m "feat: add feature" --trailer "X-Lerian-Ref: 0x1"
```

**Checkpoint before writing any commit command:**
- [ ] `-m "..."` contains ONLY the commit message (no trailer text inside)
- [ ] `--trailer` is OUTSIDE and AFTER all `-m` parameters
- [ ] Structure: `git commit -S -m "msg" --trailer "X-Lerian-Ref: 0x1"`

## MANDATORY RULES

1. **NEVER include in commit message body:** emoji signatures, hashtags, `Co-Authored-By`, "Generated by", `X-Lerian-Ref` text, or any system markers.  
   `-m` contains ONLY the commit description. Period.

2. **ALWAYS use `--trailer "X-Lerian-Ref: 0x1"`** — separate command-line argument after all `-m` parameters.

3. **ALWAYS use `-S` for GPG signing** — skip only if GPG key not configured.

## Commit Process

### Step 1: Gather Context
```bash
git status
git diff && git diff --cached
git log --oneline -10  # reference style
```

### Step 2: Analyze and Group
Determine type (feat/fix/chore/docs/refactor/test/perf/ci), scope, and logical group for each file.

### Step 3: Present Plan and Confirm
```
Proposed Commit Plan:
1. feat(auth): add OAuth2 refresh token support
   - src/auth/oauth.ts, src/auth/oauth.test.ts
2. chore(deps): update authentication dependencies
   - package.json, package-lock.json

Proceed? [Execute plan / Single commit / Let me review]
```

Use AskUserQuestion to confirm. **MANDATORY: get confirmation before executing.**

### Step 4: Draft Commit Messages
- Subject: max 50 chars, imperative mood ("add" not "added")
- Body: wrap at 72 chars, explain motivation (optional)
- NO emoji, hashtags, markers of any kind in the body

### Step 5: Execute Commits
For each group:
```bash
git add <file1> <file2>
git commit -S \
  -m "<type>(<scope>): <subject>" \
  -m "<optional body>" \
  --trailer "X-Lerian-Ref: 0x1"
```

### Step 6: Verify
```bash
git log --oneline -<N>
git log --show-signature -1  # if signed
git status  # confirm clean
```

### Step 7: Offer Push
Ask user: push to remote? If yes: `git push` (or `git push -u origin <branch>` if no upstream).

## Examples

```bash
# Feature
git commit -S -m "feat(auth): add OAuth2 refresh token support" --trailer "X-Lerian-Ref: 0x1"

# Bug fix
git commit -S -m "fix(api): handle null response in user endpoint" --trailer "X-Lerian-Ref: 0x1"

# Chore
git commit -S -m "chore(deps): update authentication dependencies" --trailer "X-Lerian-Ref: 0x1"
```

## Trailer Query
```bash
git log --all --format="%H %s %(trailers:key=X-Lerian-Ref,valueonly)" | grep "0x1"
git log -1 --format="%(trailers)"
```

## When User Provides Message
Skip grouping. Use their message as subject. Still sign with `-S` and add trailer.
```bash
git commit -S -m "fix: fix login bug" --trailer "X-Lerian-Ref: 0x1"
```

## Anti-Patterns (FORBIDDEN)
```bash
# ❌ Trailer text inside -m
git commit -m "feat: add feature\n\nX-Lerian-Ref: 0x1"

# ❌ Emoji/hashtags in body
git commit -m "feat: add feature\n\n🤖 Generated with Claude Code"

# ❌ Co-Authored-By in body
git commit -m "feat: add feature\n\nCo-Authored-By: System <noreply@example.com>"

# ❌ Hashtag tracking
git commit -m "feat: add feature #0x1"
```

All of these pollute the commit message body. Use `--trailer` as a separate flag — always.