8.0 KiB
8.0 KiB
Operation: Review Commit Quality
Analyze a commit's quality including message, changes, atomicity, and completeness.
Parameters from $ARGUMENTS
- commit (optional): Commit SHA or reference (default: HEAD)
Parse as: review-commit commit:abc123 or review-commit (defaults to HEAD)
Commit Review Workflow
Step 1: Validate Commit Exists
# Check if commit exists
if ! git rev-parse --verify ${commit:-HEAD} >/dev/null 2>&1; then
ERROR: "Commit not found: ${commit}"
exit 1
fi
# Get commit hash
commit_sha=$(git rev-parse ${commit:-HEAD})
Step 2: Run Commit Reviewer Script
Execute comprehensive analysis:
./.claude/commands/commit-best-practices/.scripts/commit-reviewer.py "${commit_sha}"
The script returns JSON:
{
"commit": "abc123...",
"author": "John Doe <john@example.com>",
"date": "2025-10-13",
"message": {
"subject": "feat(auth): add OAuth authentication",
"body": "- Implement OAuth2 flow\n- Add providers",
"subject_length": 38,
"has_body": true,
"conventional": true,
"type": "feat",
"scope": "auth"
},
"changes": {
"files_changed": 5,
"insertions": 234,
"deletions": 12,
"test_files": 1,
"doc_files": 0
},
"quality": {
"atomic": true,
"message_quality": "excellent",
"test_coverage": true,
"issues": []
},
"score": 95
}
Step 3: Analyze Message Quality
Check Subject Line:
- Length ≤ 50 characters ✅
- Imperative mood ("add" not "added") ✅
- Conventional commits format ✅
- Clear and descriptive ✅
Check Body (if present):
- Wrapped at 72 characters ✅
- Explains WHY (not just what) ✅
- Uses bullet points for clarity ✅
- Blank line after subject ✅
Check Footer (if present):
- Breaking changes noted ✅
- Issue references included ✅
Step 4: Analyze Changes
Atomicity Check:
Atomic commit = Single logical change
Check for:
❌ Multiple types mixed (feat + fix)
❌ Multiple scopes mixed (auth + api + docs)
❌ Unrelated changes bundled together
Example ATOMIC:
feat(auth): add OAuth authentication
- 5 files, all auth-related
- Single feature implementation
Example NON-ATOMIC:
feat: add OAuth and fix null pointer
- Mixing feat + fix
- Should be 2 commits
Completeness Check:
Complete commit includes:
✅ Implementation code
✅ Tests for new code
✅ Documentation if needed
✅ No missing pieces
Incomplete examples:
❌ New feature without tests
❌ API change without docs
❌ Partial implementation
Step 5: Generate Review Report
Excellent Commit (Score 90-100):
✅ EXCELLENT COMMIT
Commit: abc123 (HEAD)
Author: John Doe
Date: 2025-10-13
Message Quality: EXCELLENT
✅ Subject: "feat(auth): add OAuth authentication" (38 chars)
✅ Conventional commits format
✅ Descriptive body with bullet points
✅ Proper formatting
Changes:
✅ Atomic: Single feature (OAuth authentication)
✅ Complete: Implementation + tests
✅ Files: 5 changed (+234 -12 lines)
✅ Test coverage included
Score: 95/100
This commit follows all best practices. Safe to push!
Good Commit (Score 70-89):
✅ GOOD COMMIT (Minor improvements possible)
Commit: abc123 (HEAD)
Author: John Doe
Date: 2025-10-13
Message Quality: GOOD
✅ Subject: "feat(auth): add OAuth authentication" (38 chars)
✅ Conventional commits format
⚠️ Body: Could be more detailed (explains WHAT but not WHY)
Changes:
✅ Atomic: Single feature
⚠️ Test coverage: Only integration tests (unit tests missing)
✅ Files: 5 changed (+234 -12 lines)
Score: 82/100
Suggestions:
1. Add more context in commit body about WHY this change
2. Consider adding unit tests for edge cases
Still a good commit. Safe to push with minor notes.
Needs Improvement (Score 50-69):
⚠️ NEEDS IMPROVEMENT
Commit: abc123 (HEAD)
Author: John Doe
Date: 2025-10-13
Message Quality: FAIR
⚠️ Subject: "add oauth" (9 chars - too short)
❌ Not conventional commits format (missing type/scope)
❌ No body explaining changes
Changes:
⚠️ Atomicity: Questionable (mixes auth + API changes)
❌ Test coverage: No tests included
✅ Files: 8 changed (+312 -45 lines)
Score: 58/100
Issues to address:
1. Improve commit message: "feat(auth): add OAuth authentication"
2. Add commit body explaining implementation
3. Add tests for new OAuth functionality
4. Consider splitting auth changes from API changes
Recommendation: Amend or rewrite this commit before pushing.
Poor Commit (Score < 50):
❌ POOR COMMIT - Should be rewritten
Commit: abc123 (HEAD)
Author: John Doe
Date: 2025-10-13
Message Quality: POOR
❌ Subject: "stuff" (5 chars - meaningless)
❌ No type, no scope, no clarity
❌ No body, no context
Changes:
❌ Non-atomic: Multiple unrelated changes
- Auth system
- API refactoring
- Documentation
- Bug fixes (3 different issues)
❌ No tests
❌ Files: 23 changed (+1,234 -567 lines)
Score: 28/100
Critical issues:
1. Commit message is meaningless ("stuff")
2. Bundles 4+ unrelated changes together
3. No tests for significant code changes
4. Too large (23 files)
Action required: Reset and split into 4+ atomic commits with proper messages.
Use: /commit-split (to split into atomic commits)
Step 6: Provide Actionable Guidance
Based on score, recommend action:
Score ≥ 90: Safe to push as-is Score 70-89: Safe to push, minor suggestions noted Score 50-69: Amend recommended before pushing Score < 50: Rewrite required, do not push
Amend Guidance
If commit needs improvement and is safe to amend:
To amend this commit:
1. Make improvements (add tests, update message, etc.)
2. Stage changes: git add <files>
3. Amend commit: git commit --amend
4. Review again: /commit-best-practices review-commit
Note: Only amend if commit not yet pushed to remote!
Check: /commit-best-practices amend-guidance
Split Guidance
If commit is non-atomic:
This commit should be split into multiple commits:
Detected separate concerns:
1. feat(auth): OAuth implementation (5 files)
2. fix(api): null pointer handling (2 files)
3. docs: authentication guide (1 file)
Use: /commit-split (for interactive splitting)
Or: git reset HEAD~1 (to undo and recommit properly)
Output Format
Commit Review Report
===================
Commit: <sha> (<ref>)
Author: <name> <email>
Date: <date>
MESSAGE QUALITY: [EXCELLENT|GOOD|FAIR|POOR]
[✅|⚠️|❌] Subject: "<subject>" (<length> chars)
[✅|⚠️|❌] Format: [Conventional|Non-conventional]
[✅|⚠️|❌] Body: [Present|Missing]
[✅|⚠️|❌] Clarity: [Clear|Vague]
CHANGES:
[✅|⚠️|❌] Atomic: [Yes|Questionable|No]
[✅|⚠️|❌] Complete: [Yes|Partial]
[✅|⚠️|❌] Tests: [Included|Missing]
[✅|⚠️|❌] Size: <files> files (+<ins> -<del> lines)
SCORE: <score>/100
[Issues list if any]
[Recommendations]
VERDICT: [Safe to push|Amend recommended|Rewrite required]
Error Handling
Commit not found:
ERROR: Commit not found: abc123
Check: git log (to see available commits)
Not a git repository:
ERROR: Not a git repository
Run: git init (to initialize)
Script execution error:
ERROR: Commit reviewer script failed
Check: .claude/commands/commit-best-practices/.scripts/commit-reviewer.py exists
Verify: Script is executable
Integration with Agent
After user creates a commit:
- Agent automatically runs review (unless disabled)
- If score < 70, suggest improvements
- If non-atomic, suggest splitting
- If excellent (≥90), congratulate and suggest push
Best Practices Enforced
- Meaningful messages - Clear, descriptive commit messages
- Conventional format - type(scope): description
- Atomic commits - One logical change per commit
- Complete commits - Include tests and docs
- Proper formatting - Subject ≤50 chars, body wrapped at 72
High-quality commits make git history useful for debugging, code review, and collaboration.