---
name: ring:committing-changes
description: "Committing working-tree changes as atomic conventional commits: analyzes the diff, groups it into coherent commits, confirms the plan, then creates GPG-signed commits carrying the mandatory X-Lerian-Ref trailer and offers to push. Use when the user says 'commit' or has changes ready to record. Skip when the tree is clean, work is still in progress, or the user wants raw git commands without grouping."
---

# 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.
