Initial commit

2025-11-29 18:20:25 +08:00
commit 0d6226e0d8
69 changed files with 20934 additions and 0 deletions
--- a/commands/commit-best-practices/review-commit.md
+++ b/commands/commit-best-practices/review-commit.md
@@ -0,0 +1,347 @@
+# 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
+
+```bash
+# 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:
+
+```bash
+./.claude/commands/commit-best-practices/.scripts/commit-reviewer.py "${commit_sha}"
+```
+
+The script returns JSON:
+```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:
+1. Agent automatically runs review (unless disabled)
+2. If score < 70, suggest improvements
+3. If non-atomic, suggest splitting
+4. If excellent (≥90), congratulate and suggest push
+
+## Best Practices Enforced
+
+1. **Meaningful messages** - Clear, descriptive commit messages
+2. **Conventional format** - type(scope): description
+3. **Atomic commits** - One logical change per commit
+4. **Complete commits** - Include tests and docs
+5. **Proper formatting** - Subject ≤50 chars, body wrapped at 72
+
+High-quality commits make git history useful for debugging, code review, and collaboration.