gh-dhofheinz-open-plugins-plugins-git-commit-assistant/commands/commit-best-practices/USAGE_EXAMPLES.md

Commit Best Practices Skill - Usage Examples

Quick Reference

# Pre-commit validation (full)
/commit-best-practices check-pre-commit

# Pre-commit validation (quick - skip tests/lint)
/commit-best-practices check-pre-commit quick:true

# Review last commit
/commit-best-practices review-commit

# Review specific commit
/commit-best-practices review-commit commit:abc123

# Check if safe to amend
/commit-best-practices amend-guidance

# Amend with force (bypass safety)
/commit-best-practices amend-guidance force:true

# Revert guidance for commit
/commit-best-practices revert-guidance commit:abc123

# Workflow tips (all)
/commit-best-practices workflow-tips

# Workflow tips (specific focus)
/commit-best-practices workflow-tips focus:commit
/commit-best-practices workflow-tips focus:branch
/commit-best-practices workflow-tips focus:merge

Workflow Example 1: Safe Commit Flow

Developer: "I want to commit my changes"

Agent:
  1. Runs: /commit-best-practices check-pre-commit
  2. IF checks fail:
     - Shows: "Tests failing, debug code found"
     - Blocks commit
     - Provides guidance to fix
  3. IF checks pass:
     - Continues with commit workflow
     - Generates message
     - Creates commit
     - Reviews commit quality

Workflow Example 2: Amend Safety Check

Developer: "I need to amend my last commit"

Agent:
  1. Runs: /commit-best-practices amend-guidance
  2. Checks:
     - Not pushed to remote? ✓
     - Same author? ✓
     - Not on main/master? ✓
  3. Result: SAFE - provides amend instructions
  
  OR if unsafe:
  
  3. Result: UNSAFE - commit already pushed
     - Shows alternatives (new commit, revert)
     - Blocks amend

Workflow Example 3: Commit Review & Improvement

Developer commits code

Agent (automatically):
  1. Runs: /commit-best-practices review-commit
  2. Analyzes:
     - Message quality: GOOD
     - Atomicity: ✓ single feature
     - Tests: ⚠ missing
     - Score: 72/100
  3. Suggests:
     - "Good commit! Consider adding unit tests."
     - "Safe to push with minor note."

Script Output Examples

pre-commit-check.sh

{
  "status": "fail",
  "quick_mode": false,
  "checks": {
    "tests": {"status": "fail", "message": "Tests failing"},
    "lint": {"status": "pass", "message": "Linting passed"},
    "debug_code": {"status": "fail", "count": 3, "locations": ["src/auth.js:42: console.log(user)"]},
    "todos": {"status": "warn", "count": 1, "locations": ["src/auth.js:56: TODO: refactor"]},
    "merge_markers": {"status": "pass", "count": 0, "locations": []}
  }
}

commit-reviewer.py

{
  "commit": "abc123",
  "author": "John Doe <john@example.com>",
  "date": "2025-10-13",
  "message": {
    "subject": "feat(auth): add OAuth authentication",
    "subject_length": 38,
    "conventional": true,
    "type": "feat",
    "scope": "auth"
  },
  "changes": {
    "files_changed": 5,
    "insertions": 234,
    "deletions": 12,
    "test_files": 1
  },
  "quality": {
    "atomic": true,
    "message_quality": "excellent",
    "test_coverage": true,
    "issues": []
  },
  "score": 95
}

amend-safety.sh

{
  "safe": true,
  "recommendation": "safe",
  "commit": "abc123",
  "author": "John Doe <john@example.com>",
  "branch": "feature/oauth",
  "checks": {
    "not_pushed": {"status": "pass", "message": "Commit not pushed to origin/feature/oauth"},
    "same_author": {"status": "pass", "message": "You are the commit author"},
    "safe_branch": {"status": "pass", "message": "On feature branch: feature/oauth"},
    "collaborators": {"status": "pass", "message": "Solo work on branch"}
  }
}

revert-helper.sh

{
  "commit": "abc123",
  "original_message": "feat(auth): add OAuth authentication",
  "type": "feat",
  "scope": "auth",
  "files_affected": 5,
  "revert_message": "revert: feat(auth): add OAuth authentication\n\nThis reverts commit abc123.\n\nReason: [Provide reason here]",
  "safety": {
    "safe_to_revert": true,
    "warnings": [],
    "dependent_count": 0
  }
}

Integration with Other Skills

/commit-best-practices check-pre-commit
  ↓ (if pass)
/commit-analysis analyze
  ↓
/message-generation complete-message
  ↓
/commit (create commit)
  ↓
/commit-best-practices review-commit
  ↓ (if score < 70)
/commit-best-practices amend-guidance

Best Practices Enforced

1. Tests must pass - No commits with failing tests
2. No debug code - No console.log, debugger in commits
3. No TODOs - Fix or remove before committing
4. No merge markers - Resolve conflicts fully
5. Atomic commits - One logical change per commit
6. Quality messages - Conventional commits format
7. Safe amends - Only amend unpushed commits
8. Proper reverts - Use revert for shared history

Common Scenarios

Scenario 1: Debug Code Found

Pre-commit check fails:
  ❌ Debug code: 3 instances found
     - src/auth.js:42: console.log(user)
     - src/api.js:18: debugger statement

Action: Remove debug code, re-stage files, retry

Scenario 2: Tests Failing

Pre-commit check fails:
  ❌ Tests: 2 failing
     - test/auth.test.js: OAuth flow test

Action: Fix tests, verify passing, retry

Scenario 3: Unsafe Amend

Amend safety check:
  ❌ UNSAFE: Commit already pushed to remote
  
Alternatives:
  1. Create new commit (recommended)
  2. Use git revert (if undoing)
  3. Coordinate with team before force push

Scenario 4: Non-Atomic Commit

Commit review:
  Score: 58/100
  ⚠ Non-atomic: Mixes feat + fix + docs

Recommendation:
  Split into 3 commits:
    1. feat(auth): OAuth implementation
    2. fix(api): null pointer handling
    3. docs: authentication guide
    
  Use: /commit-split

---

This skill ensures high-quality commits through automated validation, intelligent review, and guided workflows.