Git Skill

Comprehensive git workflow guidance covering commit messages, history editing, branch management, and safety patterns.

Capabilities

Commit Messages:

• All commits: Agent-based generation with intelligent file sampling
• No context limits (samples 2-5 files for small commits, 10-15 files for large)
• Schema-based validation (4 quality gates)
• Conventional commit format enforcement
• Concision patterns (Problem/Solution/Impact)
• generate_commit_v2.py available as standalone verification tool (not used in /commit workflow)

History Editing:

• git-revise for surgical commit rewrites
• Interactive rebase workflows
• Squash, fixup, reword patterns
• Safe history editing practices

Branch Management:

• Feature branch workflows
• Branch naming conventions
• PR/MR strategies
• Branch cleanup patterns

Merge vs Rebase:

• Decision tree for choosing approach
• Fast-forward strategies
• Conflict resolution patterns
• Squash merge guidelines

Safety Patterns:

• Backup strategies before destructive operations
• Force-push safety (--force-with-lease)
• Reflog recovery patterns
• Detached HEAD recovery

Scripts:

• generate_commit_v2.py - Pydantic AI commit generation (uses acf_openai + Typer)
  • Supports --staged (default) and --hash <sha> modes
  • --instructions for user feedback
  • --reasoning-effort for complex commits
• rewrite_commits.py - Bulk commit rewriting with git-revise automation
  • JSON-based commit message rewrites
  • Safety checks for unpushed commits

When to Use

Commit workflow:

• "Generate commit message"
• "Validate commit format"
• "Follow conventional commits"

History editing:

• "Edit git history"
• "Rewrite commits"
• "Squash commits"
• "Use git-revise"

Branch management:

• "Create feature branch"
• "Branch naming strategy"
• "Cleanup old branches"

Merge/rebase:

• "Should I merge or rebase?"
• "Resolve merge conflicts"
• "Squash commits before merge"

Safety/recovery:

• "Undo git changes"
• "Recover lost commits"
• "Safe force push"

Debugging/regression:

• "Find regression commit"
• "Git bisect workflow"
• "When did feature break"
• "Binary search commits"

---

Quick Reference

Commit Message Generation: commit-message agent with intelligent file sampling (all commits)

History Editing: See resources/history-editing.md

Branch Management: See resources/branch-strategies.md

Safety Patterns: See resources/safety-patterns.md

Refactoring Safety: See resources/refactoring-safety.md

Git Bisect: See resources/git-bisect-workflow.md

Commit Message Agent: See resources/commit-message-agent-workflow.md

---

Commit Message Generation

All commits use commit-message agent with intelligent file sampling.

Method: Task(subagent_type="commit-message") - invoked for ALL commits regardless of size

Why agent-only:

• No context limits: Uses intelligent file sampling instead of reading full diffs
• Consistent approach: Same method for small and large commits
• Robust: Handles any commit size (2 files or 200 files)
• Adaptive sampling: Samples 2-5 files for small commits, 10-15 files for large commits

Agent workflow: See resources/commit-message-agent-workflow.md

Invocation:

# Agent invoked directly (no routing)
Task(subagent_type="commit-message")

Standalone verification tool:

• generate_commit_v2.py - NOT used in /commit workflow
• Available as CLI tool for manual commit message verification/testing
• Usage: uv run -m acf.git.generate_commit_v2 --hash <sha> (check previous commits)

---

Commit Message Standards

Message Body Formats

Agent selects format based on changeset analysis - three formats supported:

Format 1: Problem/Solution/Impact

Use when pre-existing pain point, gap, or improvement exists.

Problem - What issue exists:

• Current pain points
• Why change is needed

Solution - How you fixed it:

• Key implementation choices
• What changed (high-level)

Impact - Expected outcomes:

• Benefits to users/system
• Risks mitigated

Best for: fix, refactor, improvement-focused feat

Example:

fix(api): prevent race condition in user session creation

Problem:
- Concurrent requests could create duplicate sessions
- No atomic check-and-create operation

Solution:
- Add unique constraint on (user_id, device_id)
- Use INSERT ON CONFLICT DO NOTHING pattern

Impact:
- Eliminates duplicate sessions
- Safe concurrent session creation
- Reduced auth errors by 95% in testing

Format 2: Impact-Forward

Use when pure addition, new capability, no pre-existing problem.

Structure:

• What it does + why it matters
• Capabilities/use cases
• Benefits

Best for: New features, initial implementations, experimental additions

Example:

feat(ui): add dark mode toggle

Provides light/dark theme switching through preferences menu.
Improves accessibility for low-light environments and aligns
with modern application standards.

Supports:
- System preference detection
- Manual override toggle
- Persistent user preference storage

Format 3: Grouped Bullets

Use when multiple unrelated changes, chore/docs commits, simple additions.

Structure:

• Grouped changes with bullets
• Optional context/impact

Best for: chore, docs, multi-file refactors

Example:

docs(skills): update progressive disclosure guidance

- Add token budget philosophy section
- Document 500-line SKILL.md target
- Update Quick Reference best practices
- Fix broken cross-references

Concision Patterns

Symbol vocabulary (save tokens):

• "to/from" → "→"
• "and" → "+"
• "or" → "/"
• "versus" → "vs"

Telegraphic style (drop filler words):

• ❌ "This change is needed because..." → ✅ "Needed because..."
• ❌ "We are going to implement..." → ✅ "Implement..."
• ❌ "Update the authentication logic" → ✅ "Update authentication logic"

Avoid speculative metrics:

• ❌ "Improves performance by 40%" (unless measured)
• ❌ "Saves 2 hours per week" (unless validated)
• ✅ "Reduces API calls from 10→3 per request" (factual count)

See resources/concision-patterns.yaml for complete patterns.

Anti-Patterns

Vague subjects:

• ❌ "fix bug" → ✅ "fix race condition in session creation"
• ❌ "update code" → ✅ "refactor auth middleware for testability"

Missing context:

• ❌ "Change validation" → ✅ "Change validation to prevent XSS"

Wrong mood:

• ❌ "Added logging" → ✅ "Add logging"
• ❌ "Fixed bug" → ✅ "Fix bug"

Overly detailed:

• ❌ Line-by-line code changes → ✅ High-level intent + impact

See resources/anti-patterns.md for complete list.

---

History Editing Workflows

When to Edit History

Before merging PR/MR:

• Squash "WIP" commits
• Reword unclear messages
• Remove debugging commits
• Organize into logical commits

Never on public branches:

• main, master, develop
• Shared feature branches
• Published releases

git-revise Workflows

Install:

brew install git-revise        # macOS
pip install git-revise         # Any platform

Common patterns:

# Fix typo in recent commit message
git revise --edit HEAD~2

# Autosquash fixup commits
git commit --fixup=<commit-hash>  # Mark for squashing
git revise --autosquash           # Apply squashes

# Edit multiple commits interactively
git revise --interactive main

# Cut commit in two (edit mode)
git revise --edit <commit-hash>
# During edit:
git reset HEAD~1        # Unstage changes
git add -p              # Stage selectively
git commit -m "Part 1"
git commit -m "Part 2"
git revise --continue

Advantages over interactive rebase:

• Non-interactive (can script)
• Preserves commit dates
• Better conflict resolution
• Clearer command syntax

See resources/history-editing.md for advanced patterns.

---

Branch Strategies

Feature Branch Workflow

1. Create branch:

git checkout -b feature/oauth-integration main

2. Develop with regular commits:

git commit -m "wip: add OAuth client"
git commit -m "wip: implement token exchange"
git commit -m "wip: add tests"

3. Before opening PR - Clean history:

git rebase -i main  # Squash WIP commits, reword messages

4. Keep updated with main:

git fetch origin
git rebase origin/main  # Replay your commits on latest main

5. Open PR/MR

6. After merge - Cleanup:

git checkout main
git pull
git branch -d feature/oauth-integration

GitHub Flow (Simple)

• main - Always deployable
• Feature branches off main
• PR to merge back to main
• Deploy from main

Best for: Continuous deployment, small teams

Git Flow (Complex)

• main - Production releases
• develop - Integration branch
• feature/* - Features off develop
• release/* - Release candidates
• hotfix/* - Urgent fixes off main

Best for: Scheduled releases, larger teams

See resources/branch-strategies.md for detailed workflows.

---

PR End State Protocol

Strong recommendation: Implementation tasks should end with PR

Workflow:

1. Work on feature branch (not main/master)
2. Make changes + commit incrementally (/commit command)
3. Run quality gates (automatic in /commit for code changes)
4. Create PR (natural language request)

PR creation:

Request PR creation with natural language:

User: "Create a PR"
User: "Open a pull request"

Claude invokes Skill("github") and executes resources/pr-workflow.md:

• Auto-detects PR type (feature/bugfix/hotfix/docs)
• Selects appropriate template
• Extracts quality evidence from commits
• Creates PR with gh CLI

Exceptions:

• Solo projects (direct-to-main acceptable)
• WIP branches (draft PR or defer)
• Experimental work (no PR needed)

---

Commit Workflow

Used by: /commit command (delegates to this workflow)

Step 1: Stage Files

Stage provided files or use already-staged files:

FILES="$ARGUMENTS"
[ -n "$FILES" ] && git add $FILES

Step 2: Generate Message

Invoke commit-message agent:

Task(subagent_type="commit-message")

Agent workflow:

• Analyzes changeset with intelligent sampling
• Detects scope from directory patterns
• Samples key files strategically
• Generates message in Problem/Solution/Impact format
• See resources/commit-message-agent-workflow.md for complete process

Step 3: Present and Get Approval

Output the generated message to the user:

===== PROPOSED COMMIT MESSAGE =====
$message
===================================

Then use AskUserQuestion with 4 options:

• Approve: Accept message and commit immediately
• Fix: Provide feedback for inline edit by Claude (fast, no agent re-invocation)
• Regenerate: Full re-analysis by re-invoking agent with user feedback
• Cancel: Abort commit

Step 4: Handle Response

If Approve:

git commit -m "$message"
git log -1 --stat
echo "✅ Commit created successfully"

If Fix (inline edit by Claude):

• User provides feedback (e.g., "make scope more specific")
• Claude edits message directly based on feedback
• No agent re-invocation needed (fast, free)
• Return to Step 3 with updated message

If Regenerate (full re-analysis):

• User provides instructions (e.g., "focus on performance impact")
• Re-invoke agent with feedback incorporated into prompt
• Agent re-analyzes changeset with new focus
• Return to Step 3 with regenerated message

If Cancel: Exit without committing

Step 5: Verify

git log -1 --stat
echo "✅ Commit created successfully"

Complete workflow: resources/commit-script-workflow.md (now agent-based, not script-based)

---

Safety Patterns

Pre-Flight Checklist

Before rebasing, force-pushing, or history editing:

# 1. Check current state
git status
git log --oneline -10

# 2. Create backup
git branch backup-$(date +%Y%m%d-%H%M%S)

# 3. Verify you're on right branch
git branch --show-current

# 4. Check for unpushed work
git log origin/$(git branch --show-current)..HEAD

# 5. Confirm no one else working on branch (check with team)

Force-Push Safety

Golden rules:

1. Never force-push to main/develop/shared branches
2. Use --force-with-lease not --force
3. Communicate with team before force-pushing shared feature branch
4. Check branch protection rules first

# Safe force push
git push --force-with-lease origin feature-branch

# If rejected:
# Someone else pushed to branch since your last fetch
# Fetch and review their changes before deciding
git fetch origin
git log HEAD..origin/feature-branch
git rebase origin/feature-branch  # Incorporate their changes
git push --force-with-lease

Reflog Recovery

reflog = reference log = local history of HEAD movements

# View reflog (90-day retention by default)
git reflog

# Output:
# abc1234 HEAD@{0}: commit: Add feature X
# def5678 HEAD@{1}: rebase: Fix conflict
# ghi9012 HEAD@{2}: reset: moving to HEAD~1

# Recover to specific point
git reset --hard HEAD@{2}

# Or create branch from reflog entry
git checkout -b recovery HEAD@{5}

Common recovery scenarios:

# Accidentally deleted branch
git reflog | grep "branch-name"
git checkout -b branch-name <sha-from-reflog>

# Bad rebase - want to undo
git reflog | grep "rebase"
git reset --hard HEAD@{before-rebase}

# Lost commits after reset
git reflog | grep "commit"
git cherry-pick <sha-from-reflog>

See resources/safety-patterns.md for comprehensive recovery workflows.

---

Scripts

generate_commit_v2.py (Standalone Verification Tool)

Purpose: Standalone CLI tool for manual commit message verification/testing

NOT used in /commit workflow - that uses commit-message agent instead

Use cases:

• Verify quality of previous commit messages
• Test commit message generation manually
• Quick checks during development
• Rewording historical commits

Usage:

# Verify previous commit message
uv run -m acf.git.generate_commit_v2 --hash abc123

# Test message generation for staged files
uv run -m acf.git.generate_commit_v2

# With custom instructions
uv run -m acf.git.generate_commit_v2 --instructions "focus on performance"

# With higher reasoning effort
uv run -m acf.git.generate_commit_v2 --reasoning-effort high

Features:

• Typer CLI with type-safe arguments
• Pydantic AI validation (gpt-5-codex model)
• Supports --staged and --hash modes
• Google docstrings, full test coverage

Limitations:

• Context size constraints (works for small/medium commits only)
• Not suitable for large diffs (10+ files, 1000+ insertions)
• This is why /commit uses commit-message agent instead

Exit codes:

• 0 - Success
• 1 - Generation failed
• 2 - No changes found
• 4 - Git error

rewrite_commits.py

Purpose: Bulk commit rewriting automation with git-revise

Usage:

# Rewrite commits from JSON map
uv run -m acf.git.rewrite_commits commits.json

# JSON format:
# {
#   "abc123": "new commit message...",
#   "def456": "another message..."
# }

Features:

• Bulk commit message rewriting with git-revise
• Safety checks (verifies commits are unpushed)
• Chronological ordering (rewrites oldest first)
• Requires git-revise installed in .venv (uv add git-revise)

---

Resources

Workflow Guides

resources/commit-script-workflow.md:

• Complete commit approval workflow
• AskUserQuestion integration (Approve/Fix/Regenerate/Cancel)
• Inline edit vs script regeneration patterns
• Usage examples and troubleshooting

resources/history-editing.md:

• git-revise complete reference
• Interactive rebase patterns
• git-absorb workflows (auto-fixup)
• git-branchless for stacked diffs

resources/branch-strategies.md:

• GitHub Flow vs Git Flow comparison
• Feature branch best practices
• Branch naming conventions
• Cleanup automation patterns

resources/safety-patterns.md:

• Pre-flight checklists
• Backup strategies
• Recovery workflows (reflog, reset, cherry-pick)
• Force-push safety protocols

Reference Files

resources/concision-patterns.yaml:

• Symbol vocabulary mappings
• Telegraphic transformation rules
• Metric validation patterns

resources/anti-patterns.md:

• Common commit message mistakes
• How to fix each anti-pattern
• Before/after examples

---

Integration with Other Skills

bash-patterns:

• Git command patterns for complex operations
• Approval optimization for multi-step git workflows
• Heredoc patterns for commit messages

framework:

• Git workflow patterns referenced in framework skill
• Integration with agent workflows

Commands:

• /commit - Delegates to this skill for commit message generation

Type: Hybrid Type 3 (Schema Validator for commits) + Type 6 (Guidance-Only for workflows)

---

Official Documentation

Git:

• Official docs: https://git-scm.com/docs
• Pro Git book: https://git-scm.com/book
• git-revise: https://github.com/mystor/git-revise

Conventional Commits:

• Specification: https://www.conventionalcommits.org/
• Why it matters: https://www.conventionalcommits.org/en/v1.0.0/#why-use-conventional-commits

GitHub:

• Branch protection: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches
• PR best practices: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests