687 lines
21 KiB
Markdown
687 lines
21 KiB
Markdown
---
|
|
description: Review staged changes and recommend commit strategy for atomic commits
|
|
allowed-tools: Bash(git:*)
|
|
---
|
|
|
|
# Commit Review - Analyze Changes for Atomic Commits
|
|
|
|
Review your staged or unstaged changes and receive recommendations on whether to create a single commit or split into multiple atomic commits.
|
|
|
|
## Overview
|
|
|
|
The `/commit-review` command provides comprehensive change analysis by orchestrating multiple analytical skills to determine whether your changes should be committed as one atomic commit or split into multiple focused commits.
|
|
|
|
### Skills Orchestrated
|
|
|
|
This command coordinates:
|
|
|
|
1. **commit-error-handling** - Repository state validation
|
|
- Operation: `/commit-error-handling diagnose-issues`
|
|
- Ensures repository is ready for analysis
|
|
|
|
2. **commit-analysis** - Multi-dimensional change analysis
|
|
- Operation: `/commit-analysis analyze`
|
|
- Detects: types, scopes, file changes, atomicity
|
|
- Provides: Comprehensive change breakdown
|
|
|
|
3. **atomic-commit** - Splitting analysis
|
|
- Operations:
|
|
- `/atomic-commit analyze` - Determine if should split
|
|
- `/atomic-commit group strategy:type` - Group files by type
|
|
- `/atomic-commit suggest` - Generate commit breakdown
|
|
- Provides: Detailed splitting recommendations
|
|
|
|
4. **message-generation** - Preview commit messages
|
|
- Operation: `/message-generation complete`
|
|
- Generates: Suggested messages for each commit group
|
|
|
|
5. **history-analysis** (optional) - Project convention awareness
|
|
- Operation: `/history-analysis analyze-style`
|
|
- Ensures: Recommendations match project style
|
|
|
|
### Workflow Integration
|
|
|
|
After `/commit-review` shows recommendations:
|
|
|
|
**If single commit recommended**:
|
|
→ Use `/commit` to create the commit
|
|
|
|
**If split recommended**:
|
|
→ Use `/commit-split` for interactive splitting
|
|
→ OR use `/atomic-commit interactive` for granular control
|
|
→ OR manually commit each group
|
|
|
|
### For Granular Control
|
|
|
|
Analyze specific aspects independently:
|
|
- `/commit-analysis detect-type` - Just classify change types
|
|
- `/commit-analysis assess-atomicity` - Just check atomicity
|
|
- `/atomic-commit group` - Just group files
|
|
- `/atomic-commit suggest` - Just get commit suggestions
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
/commit-review # Review all changes (staged and unstaged)
|
|
```
|
|
|
|
## What is an Atomic Commit?
|
|
|
|
An atomic commit is a single, focused commit that:
|
|
- Contains one logical change
|
|
- Can be reverted independently without breaking other functionality
|
|
- Has all tests passing after the commit
|
|
- Is self-contained and complete
|
|
- Has a clear, single purpose
|
|
|
|
**Good Atomic Commits:**
|
|
- Add authentication feature (all auth files together)
|
|
- Fix login bug (only the fix, not other changes)
|
|
- Update dependencies (package updates together)
|
|
|
|
**Bad Non-Atomic Commits:**
|
|
- Add feature + fix unrelated bug + update docs
|
|
- Refactor + add new functionality
|
|
- Mix of formatting changes and logic changes
|
|
|
|
## Complete Analysis Workflow
|
|
|
|
```
|
|
User: /commit-review
|
|
↓
|
|
┌────────────────────────────────┐
|
|
│ 1. Validate Repository │
|
|
│ /commit-error-handling │
|
|
│ diagnose-issues │
|
|
└────────────┬───────────────────┘
|
|
↓
|
|
┌────────────────────────────────┐
|
|
│ 2. Analyze All Changes │
|
|
│ /commit-analysis analyze │
|
|
│ - Detect types │
|
|
│ - Identify scopes │
|
|
│ - Count files/lines │
|
|
└────────────┬───────────────────┘
|
|
↓
|
|
┌────────────────────────────────┐
|
|
│ 3. Assess Atomicity │
|
|
│ /atomic-commit analyze │
|
|
└────────────┬───────────────────┘
|
|
↓
|
|
┌─────┴──────┐
|
|
│ Should │
|
|
│ Split? │
|
|
└─────┬──────┘
|
|
│
|
|
┌────────┴────────┐
|
|
│ │
|
|
YES NO
|
|
↓ ↓
|
|
┌───────────────┐ ┌──────────────────┐
|
|
│ 4a. Group │ │ 4b. Recommend │
|
|
│ Files │ │ Single Commit │
|
|
│ /atomic- │ │ │
|
|
│ commit group │ │ → Use /commit │
|
|
└───────┬───────┘ └──────────────────┘
|
|
↓
|
|
┌───────────────────┐
|
|
│ 5a. Generate │
|
|
│ Suggestions │
|
|
│ /atomic-commit │
|
|
│ suggest │
|
|
│ │
|
|
│ For each group: │
|
|
│ /message- │
|
|
│ generation │
|
|
│ complete │
|
|
└─────────┬─────────┘
|
|
↓
|
|
┌─────────────────────────────┐
|
|
│ 6a. Present Plan │
|
|
│ - Commit breakdown │
|
|
│ - Suggested messages │
|
|
│ - File groups │
|
|
│ │
|
|
│ → Use /commit-split │
|
|
└─────────────────────────────┘
|
|
```
|
|
|
|
## Process
|
|
|
|
### Step 1: Repository Validation
|
|
|
|
**Orchestrates**: `/commit-error-handling diagnose-issues`
|
|
|
|
Before analyzing changes, verify:
|
|
- Valid git repository
|
|
- Changes present (staged or unstaged)
|
|
- No merge conflicts blocking analysis
|
|
- Repository not in problematic state
|
|
|
|
This prevents analysis of invalid states.
|
|
|
|
**For detailed diagnostics**: `/commit-error-handling diagnose-issues`
|
|
|
|
```bash
|
|
git rev-parse --git-dir 2>/dev/null
|
|
git status --short
|
|
```
|
|
|
|
If not a git repo, show error and exit.
|
|
|
|
### Step 2: Analyze All Changes
|
|
|
|
**Orchestrates**: `/commit-analysis analyze`
|
|
|
|
Performs multi-dimensional analysis:
|
|
|
|
**File-Level Analysis**:
|
|
- Type detection (feat, fix, docs, refactor, test, chore, style, perf, ci)
|
|
- Scope identification (auth, api, ui, database, etc.)
|
|
- Line change statistics (+/- counts)
|
|
|
|
**Change-Level Analysis**:
|
|
- Total files modified
|
|
- Insertions and deletions
|
|
- Change complexity assessment
|
|
|
|
**Atomicity Assessment**:
|
|
- Single concern vs. multiple concerns
|
|
- Related vs. unrelated changes
|
|
- Interdependencies between files
|
|
|
|
**Grouping Strategy**:
|
|
- Type-based grouping (all feat together)
|
|
- Scope-based grouping (all auth together)
|
|
- Feature-based grouping (implementation + tests)
|
|
|
|
Check both staged and unstaged changes:
|
|
|
|
```bash
|
|
# Get status
|
|
git status --short
|
|
|
|
# Get staged changes
|
|
git diff --cached --stat
|
|
git diff --cached
|
|
|
|
# Get unstaged changes
|
|
git diff --stat
|
|
git diff
|
|
|
|
# Count files by status
|
|
git status --short | wc -l
|
|
```
|
|
|
|
**Type Detection Rules**:
|
|
|
|
Analyze the diff output to categorize each file by its primary change type:
|
|
|
|
1. **feat** (New Feature):
|
|
- New files being added
|
|
- New functions/classes/exports
|
|
- New functionality in existing files
|
|
- Look for: `export function`, `export class`, `export const`, new files
|
|
|
|
2. **fix** (Bug Fix):
|
|
- Error handling additions
|
|
- Null/undefined checks
|
|
- Validation fixes
|
|
- Look for: `if (!`, `try/catch`, `throw`, `error`, `null`, `undefined`
|
|
|
|
3. **refactor** (Code Restructuring):
|
|
- Variable/function renaming
|
|
- Code extraction or reorganization
|
|
- Look for: similar logic moved, renamed identifiers
|
|
|
|
4. **docs** (Documentation):
|
|
- README.md changes, documentation files (*.md), JSDoc additions
|
|
- Look for: file extensions `.md`, comment blocks
|
|
|
|
5. **style** (Formatting):
|
|
- Whitespace changes only, indentation fixes
|
|
- Look for: only whitespace diffs, no logic changes
|
|
|
|
6. **test** (Tests):
|
|
- Test file changes (*.test.js, *.spec.js, *_test.py)
|
|
- Look for: `test(`, `describe(`, `it(`, `expect(`, file patterns
|
|
|
|
7. **chore** (Build/Config):
|
|
- package.json dependencies, build configuration
|
|
- Look for: package.json, *.config.js, .github/workflows
|
|
|
|
8. **perf** (Performance):
|
|
- Optimization changes, caching implementations
|
|
- Look for: `cache`, `memoize`, performance-related comments
|
|
|
|
9. **ci** (CI/CD):
|
|
- GitHub Actions workflows, GitLab CI configs
|
|
- Look for: .github/workflows, .gitlab-ci.yml
|
|
|
|
**For granular analysis**:
|
|
- `/commit-analysis detect-type file:path` - Type for specific file
|
|
- `/commit-analysis identify-scope file:path` - Scope for specific file
|
|
- `/commit-analysis file-stats` - Just statistics
|
|
|
|
### Step 3: Determine Split Strategy
|
|
|
|
**Orchestrates**: `/atomic-commit analyze`
|
|
|
|
Evaluates whether changes should be split:
|
|
|
|
**Split Criteria**:
|
|
- Multiple types present (feat + fix + docs)
|
|
- Multiple scopes (auth + api + ui)
|
|
- Too many files (10+ of different types)
|
|
- Mixed concerns (feature + unrelated refactor)
|
|
|
|
**Keep Together Criteria**:
|
|
- Single type and scope
|
|
- All files serve same purpose
|
|
- Changes are interdependent
|
|
- Reasonable file count (≤10)
|
|
|
|
**Atomicity Scoring**:
|
|
- atomic=true (single commit) → Proceed to `/commit`
|
|
- atomic=false (split needed) → Continue to grouping
|
|
|
|
**For direct splitting analysis**: `/atomic-commit analyze`
|
|
|
|
### Step 4: Group Related Files
|
|
|
|
**Orchestrates**: `/atomic-commit group strategy:type`
|
|
|
|
Groups files into logical commit groups:
|
|
|
|
**Grouping Strategies**:
|
|
|
|
1. **Type-Based** (default):
|
|
- feat files → Commit 1
|
|
- fix files → Commit 2
|
|
- docs files → Commit 3
|
|
- test files → Commit 4
|
|
|
|
2. **Scope-Based**:
|
|
- auth files → Commit 1
|
|
- api files → Commit 2
|
|
- ui files → Commit 3
|
|
|
|
3. **Feature-Based**:
|
|
- Implementation + Tests → Commit 1
|
|
- Documentation → Commit 2
|
|
|
|
Create a mapping of files to their change types:
|
|
|
|
```
|
|
feat:
|
|
- src/auth/oauth.js
|
|
- src/auth/providers.js
|
|
- src/auth/middleware.js
|
|
|
|
test:
|
|
- tests/auth.test.js
|
|
- tests/oauth.test.js
|
|
|
|
docs:
|
|
- README.md
|
|
|
|
refactor:
|
|
- src/utils.js
|
|
- src/helpers.js
|
|
```
|
|
|
|
**For custom grouping**:
|
|
- `/atomic-commit group strategy:scope` - Group by module
|
|
- `/atomic-commit group strategy:feature` - Group by feature
|
|
|
|
### Step 5: Generate Commit Recommendations
|
|
|
|
**Orchestrates**:
|
|
- `/atomic-commit suggest` - Create commit breakdown
|
|
- `/message-generation complete` (for each group) - Generate messages
|
|
|
|
For each group, generates:
|
|
- **Commit message**: Conventional commits format
|
|
- **File list**: All files in the group
|
|
- **Change summary**: What the commit does
|
|
- **Line statistics**: Insertions/deletions
|
|
|
|
**Message Generation Uses**:
|
|
- Detected type (feat, fix, etc.)
|
|
- Identified scope (auth, api, etc.)
|
|
- Change analysis (what was actually done)
|
|
- Project conventions (from history-analysis)
|
|
|
|
**For custom messages**:
|
|
- `/message-generation subject` - Just subject line
|
|
- `/message-generation validate` - Check message format
|
|
|
|
### Step 6: Present Analysis Results
|
|
|
|
## Analysis Output Format
|
|
|
|
### Split Recommendation
|
|
|
|
When multiple concerns are detected:
|
|
|
|
```
|
|
COMMIT REVIEW ANALYSIS
|
|
═══════════════════════════════════════════════
|
|
Data from: /commit-analysis analyze
|
|
/atomic-commit analyze
|
|
|
|
RECOMMENDATION: SPLIT INTO ATOMIC COMMITS
|
|
|
|
Your changes cover multiple concerns:
|
|
⚠ Multiple types: feat, test, refactor, docs
|
|
⚠ Multiple scopes or unrelated changes
|
|
⚠ Better split for clear history
|
|
|
|
──────────────────────────────────────────────
|
|
CURRENT CHANGES SUMMARY:
|
|
Data from: /commit-analysis analyze
|
|
────────────────────────────────────────────
|
|
Total Files: 12
|
|
Insertions: 847 (+)
|
|
Deletions: 234 (-)
|
|
|
|
CHANGE TYPE BREAKDOWN:
|
|
────────────────────────────────────────────
|
|
FEAT (5 files) - New authentication system
|
|
M src/auth/oauth.js (+156 lines)
|
|
M src/auth/providers.js (+89 lines)
|
|
M src/auth/middleware.js (+73 lines)
|
|
M src/auth/config.js (+45 lines)
|
|
M src/auth/index.js (+23 lines)
|
|
|
|
TEST (2 files) - Authentication tests
|
|
M tests/auth.test.js (+142 lines)
|
|
M tests/oauth.test.js (+98 lines)
|
|
|
|
REFACTOR (3 files) - Code cleanup
|
|
M src/utils.js (+45 -67 lines)
|
|
M src/helpers.js (+34 -52 lines)
|
|
M src/validators.js (+12 -8 lines)
|
|
|
|
DOCS (2 files) - Documentation updates
|
|
M README.md (+156 -42 lines)
|
|
M docs/authentication.md (+74 lines)
|
|
|
|
──────────────────────────────────────────────
|
|
SPLITTING PLAN
|
|
Generated by: /atomic-commit suggest
|
|
Messages from: /message-generation complete
|
|
|
|
Commit 1 (feat): 5 files, 386 lines
|
|
feat(auth): implement OAuth authentication system
|
|
|
|
- Add OAuth2 authentication flow
|
|
- Implement provider support for Google and GitHub
|
|
- Add authentication middleware
|
|
- Include configuration management
|
|
|
|
Files:
|
|
src/auth/oauth.js
|
|
src/auth/providers.js
|
|
src/auth/middleware.js
|
|
src/auth/config.js
|
|
src/auth/index.js
|
|
|
|
────────────────────────────────────────────
|
|
|
|
Commit 2 (test): 2 files, 240 lines
|
|
test(auth): add comprehensive OAuth authentication tests
|
|
|
|
- Add unit tests for OAuth flow
|
|
- Add integration tests for providers
|
|
- Achieve 95% coverage for auth module
|
|
|
|
Files:
|
|
tests/auth.test.js
|
|
tests/oauth.test.js
|
|
|
|
────────────────────────────────────────────
|
|
|
|
Commit 3 (refactor): 3 files, 24 lines
|
|
refactor: simplify utility functions and improve validation
|
|
|
|
- Simplify date/time utilities
|
|
- Improve helper function clarity
|
|
- Enhance validator logic
|
|
|
|
Files:
|
|
src/utils.js
|
|
src/helpers.js
|
|
src/validators.js
|
|
|
|
────────────────────────────────────────────
|
|
|
|
Commit 4 (docs): 2 files, 188 lines
|
|
docs: add OAuth authentication guide
|
|
|
|
- Update README with authentication setup
|
|
- Add detailed authentication documentation
|
|
- Include usage examples
|
|
|
|
Files:
|
|
README.md
|
|
docs/authentication.md
|
|
|
|
──────────────────────────────────────────────
|
|
|
|
NEXT STEPS:
|
|
→ Interactive splitting: /commit-split
|
|
→ Granular control: /atomic-commit interactive
|
|
→ Manual commits: Use /commit for each group
|
|
|
|
WHY SPLIT COMMITS?
|
|
Atomic commits provide:
|
|
✓ Better history browsing (each commit tells a story)
|
|
✓ Easier code review (reviewers see logical changes)
|
|
✓ Safer reverts (revert one feature without breaking others)
|
|
✓ Clearer blame/annotate (understand why changes were made)
|
|
✓ Better bisecting (find bugs by commit)
|
|
═══════════════════════════════════════════════
|
|
```
|
|
|
|
### Single Commit Recommendation
|
|
|
|
When changes form a cohesive unit:
|
|
|
|
```
|
|
COMMIT REVIEW ANALYSIS
|
|
═══════════════════════════════════════════════
|
|
Data from: /commit-analysis analyze
|
|
|
|
RECOMMENDATION: SINGLE ATOMIC COMMIT ✓
|
|
|
|
Your changes form a cohesive unit:
|
|
✓ Single type: feat
|
|
✓ Single scope: auth
|
|
✓ Logical unit: OAuth authentication
|
|
✓ Reasonable size: 5 files, 386 lines
|
|
|
|
──────────────────────────────────────────────
|
|
CURRENT CHANGES SUMMARY:
|
|
Data from: /commit-analysis analyze
|
|
────────────────────────────────────────────
|
|
Total Files: 5
|
|
Insertions: 386 (+)
|
|
Deletions: 0 (-)
|
|
|
|
CHANGE TYPE BREAKDOWN:
|
|
────────────────────────────────────────────
|
|
FEAT (5 files) - Complete authentication feature
|
|
M src/auth/oauth.js
|
|
M src/auth/providers.js
|
|
M src/auth/middleware.js
|
|
M src/auth/config.js
|
|
M src/auth/index.js
|
|
|
|
──────────────────────────────────────────────
|
|
SUGGESTED COMMIT MESSAGE
|
|
Generated by: /message-generation complete
|
|
|
|
feat(auth): implement OAuth authentication system
|
|
|
|
- Add OAuth2 authentication flow
|
|
- Implement provider support for Google and GitHub
|
|
- Add authentication middleware
|
|
- Include configuration management
|
|
──────────────────────────────────────────────
|
|
|
|
ATOMICITY CHECK: PASSED
|
|
✓ All files relate to a single feature (auth)
|
|
✓ Changes are cohesive and interdependent
|
|
✓ Single commit tells a clear story
|
|
✓ Can be reverted as a complete unit
|
|
|
|
NEXT STEPS:
|
|
→ Create commit: /commit
|
|
→ Pre-validate: /commit-best-practices check-pre-commit
|
|
═══════════════════════════════════════════════
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
**Not a git repository:**
|
|
```
|
|
ERROR: Not a git repository
|
|
Run: git init
|
|
```
|
|
|
|
**No changes to review:**
|
|
```
|
|
NO CHANGES TO REVIEW
|
|
|
|
Your working tree is clean.
|
|
Make some changes, then run /commit-review again.
|
|
```
|
|
|
|
**All changes already committed:**
|
|
```
|
|
ALL CHANGES COMMITTED
|
|
|
|
Great job! Your working tree is clean.
|
|
Run git log to see your commits.
|
|
```
|
|
|
|
## Tips for Atomic Commits
|
|
|
|
**DO:**
|
|
- Group related changes together
|
|
- Keep features separate from fixes
|
|
- Keep refactoring separate from new features
|
|
- Include tests with the code they test (optional)
|
|
- Make each commit independently buildable
|
|
|
|
**DON'T:**
|
|
- Mix formatting changes with logic changes
|
|
- Combine multiple features in one commit
|
|
- Include unrelated bug fixes with features
|
|
- Make "WIP" or "misc changes" commits
|
|
- Bundle everything at the end of the day
|
|
|
|
## Examples
|
|
|
|
**Example 1: Mixed changes (needs splitting)**
|
|
```bash
|
|
/commit-review
|
|
# Shows: feat (3 files), fix (2 files), docs (1 file)
|
|
# Recommends: Split into 3 commits
|
|
# Next: /commit-split
|
|
```
|
|
|
|
**Example 2: Clean atomic change**
|
|
```bash
|
|
/commit-review
|
|
# Shows: fix (2 files) - all related to login bug
|
|
# Recommends: Single commit is appropriate
|
|
# Next: /commit
|
|
```
|
|
|
|
**Example 3: Large feature**
|
|
```bash
|
|
/commit-review
|
|
# Shows: feat (15 files) - authentication system
|
|
# Recommends: Consider splitting by module/component
|
|
# Next: /commit-split or careful manual commits
|
|
```
|
|
|
|
## Related Skills and Commands
|
|
|
|
### Analytical Skills Used
|
|
|
|
- **commit-analysis**: `/commit-analysis` - Detailed change analysis
|
|
- Operations: analyze, detect-type, identify-scope, assess-atomicity, file-stats
|
|
- Purpose: Multi-dimensional change analysis and type/scope detection
|
|
|
|
- **atomic-commit**: `/atomic-commit` - Splitting analysis and grouping
|
|
- Operations: analyze, group, suggest, sequence, interactive
|
|
- Purpose: Determine if changes should split and generate commit groups
|
|
|
|
- **history-analysis**: `/history-analysis` - Project convention analysis
|
|
- Operations: analyze-style, recent-patterns, common-scopes
|
|
- Purpose: Learn project conventions to inform recommendations
|
|
|
|
### Execution Skills Referenced
|
|
|
|
- **message-generation**: `/message-generation` - Message creation
|
|
- Operations: complete, subject, body, validate
|
|
- Purpose: Generate conventional commit messages for each group
|
|
|
|
- **commit-best-practices**: `/commit-best-practices` - Validation
|
|
- Operations: check-pre-commit, workflow-tips, validate-message
|
|
- Purpose: Ensure commits follow best practices
|
|
|
|
- **commit-error-handling**: `/commit-error-handling` - Error diagnosis
|
|
- Operations: diagnose-issues, recover, clean-state
|
|
- Purpose: Validate repository state before analysis
|
|
|
|
### Related Commands
|
|
|
|
- `/commit` - Create single atomic commit
|
|
- Use when: Review recommends single commit
|
|
- Purpose: Execute the commit with generated message
|
|
|
|
- `/commit-split` - Interactively split into atomic commits
|
|
- Use when: Review recommends splitting
|
|
- Purpose: Interactive file-by-file commit creation
|
|
|
|
### Workflow Paths
|
|
|
|
```
|
|
/commit-review (analysis)
|
|
↓
|
|
├─ Single commit? → /commit (execution)
|
|
│
|
|
└─ Multiple commits? → /commit-split (execution)
|
|
OR /atomic-commit interactive (granular control)
|
|
```
|
|
|
|
### For Power Users
|
|
|
|
Access granular operations directly:
|
|
|
|
**Analysis Only**:
|
|
- `/commit-analysis detect-type` - Classify file types
|
|
- `/commit-analysis identify-scope` - Extract scopes
|
|
- `/commit-analysis assess-atomicity` - Check if should split
|
|
|
|
**Grouping Only**:
|
|
- `/atomic-commit group strategy:type` - Group by type
|
|
- `/atomic-commit group strategy:scope` - Group by scope
|
|
- `/atomic-commit group strategy:feature` - Group by feature
|
|
|
|
**Message Generation Only**:
|
|
- `/message-generation complete` - Generate full message
|
|
- `/message-generation subject` - Just subject line
|
|
- `/message-generation validate message:"text"` - Validate format
|
|
|
|
### Documentation References
|
|
|
|
- **Atomic Commits Guide**: See `/commit-best-practices workflow-tips`
|
|
- **Skill Architecture**: See `.claude/docs/SKILL_ARCHITECTURE.md`
|
|
- **Agent Reference**: See `agents/commit-assistant.md`
|
|
- **Command List**: See plugin README.md for all available commands
|