--- description: Assess if changes are atomic (single logical change) or should be split into multiple commits --- # Operation: Assess Atomicity Determine if changes form an atomic commit (single logical change) or should be split into multiple focused commits. ## Parameters from $ARGUMENTS No parameters required. Analyzes all current changes. ## Workflow ### Step 1: Gather Change Data ```bash git status --short git diff HEAD --stat git diff HEAD ``` ### Step 2: Run Atomicity Analysis Execute atomicity checker script: ```bash git diff HEAD | .scripts/atomicity-checker.py ``` The script analyzes: - Number of files changed - Types of changes (feat, fix, docs, etc.) - Scopes affected - Interdependencies - Logical cohesion ### Step 3: Atomicity Criteria **Atomic Commit** (single commit appropriate): - All changes serve ONE logical purpose - All files relate to the same feature/fix - Changes are interdependent - Same type throughout (all feat, or all fix) - Same scope throughout (all auth, or all api) - Can be reverted as a complete unit - Tests pass after commit **Non-Atomic** (should split): - Multiple distinct types (feat + fix + docs) - Multiple unrelated scopes (auth + api + ui) - Mixing concerns (feature + refactoring + bug fix) - Too many files (10+ unrelated files) - Multiple stories being told ### Step 4: Splitting Recommendations If non-atomic, suggest how to split: **By Type:** ``` Split into commits by change type: 1. feat(auth): OAuth implementation (5 files) 2. test(auth): OAuth tests (2 files) 3. docs: authentication guide (1 file) ``` **By Scope:** ``` Split into commits by module: 1. feat(auth): authentication system (6 files) 2. feat(api): user API endpoints (4 files) 3. feat(ui): login components (3 files) ``` **By Feature:** ``` Split into commits by logical unit: 1. feat(payments): Stripe integration (8 files) 2. feat(payments): PayPal integration (6 files) 3. test(payments): payment tests (4 files) ``` ### Step 5: Format Atomicity Assessment ``` ATOMICITY ASSESSMENT ═══════════════════════════════════════════════ STATUS: ANALYSIS: ─────────────────────────────────────────────── Files Changed: X Lines Changed: +XXX -XXX Type Diversity: Scope Diversity: Logical Cohesion: ATOMICITY CHECKS: ─────────────────────────────────────────────── ✓ Single logical purpose ✓ Related files only ✓ Same change type ✓ Same scope ✓ Interdependent changes ✓ Complete unit ✓ Can be reverted independently OR ✗ Multiple purposes detected ✗ Unrelated files mixed ✗ Multiple change types ✗ Multiple scopes ✗ Independent changes ✗ Incomplete without splits REASONING: ─────────────────────────────────────────────── If ATOMIC: All changes implement [specific feature/fix]. Files work together and depend on each other. Single commit tells a clear, focused story. If SHOULD SPLIT: Changes address multiple concerns: 1. 2. 3. Each concern should be a separate commit. SPLITTING RECOMMENDATIONS: ─────────────────────────────────────────────── Recommended Commits: Commit 1: (): Files: X files Purpose: Files: - file1.js - file2.js Lines: +XX -YY Commit 2: (): Files: X files Purpose: Files: - file3.js - file4.js Lines: +XX -YY BENEFITS OF SPLITTING: ─────────────────────────────────────────────── - Better code review (focused changes) - Easier to revert individual features - Clearer git history - Better bisecting for bugs - Easier cherry-picking RECOMMENDATION: ─────────────────────────────────────────────── ═══════════════════════════════════════════════ ``` ## Detailed Atomicity Rules ### Rule 1: Single Purpose Test **Question:** Can you describe ALL changes in one sentence? **Atomic Examples:** - "Add OAuth authentication" - "Fix null pointer in user endpoint" - "Refactor date utility functions" **Non-Atomic Examples:** - "Add OAuth and fix login bug and update README" - "Implement payment and refactor utils and add tests" ### Rule 2: Type Consistency **Atomic:** - All files are "feat" type - All files are "fix" type - All files are "refactor" type **Non-Atomic:** - Mix of feat + fix - Mix of refactor + feat - Mix of docs + code changes (exception: docs can accompany code) ### Rule 3: Scope Consistency **Atomic:** - All changes in "auth" module - All changes in "api" module - All changes in "ui/components" **Non-Atomic:** - Changes in auth + api + ui - Changes in multiple unrelated modules ### Rule 4: Revert Independence **Test:** If reverted, does it break unrelated functionality? **Atomic:** - Can be reverted without breaking other features - Forms a complete, self-contained unit **Non-Atomic:** - Reverting breaks unrelated features - Mixes independent changes ### Rule 5: Review Simplicity **Atomic:** - Reviewer can focus on one logical change - Clear what and why - Single story **Non-Atomic:** - Reviewer must context-switch between multiple concerns - Multiple stories mixed together ## File Count Guidelines **Generally Atomic:** - 1-5 files: Usually focused - 5-10 files: Check cohesion carefully - 10-15 files: Likely needs splitting unless tightly coupled **Usually Non-Atomic:** - 15+ files: Almost always should split - 20+ files: Definitely split **Exceptions:** - Large refactoring may touch many files atomically - Package updates may affect many files atomically - Renaming across project may touch many files atomically ## Edge Cases ### Case 1: Feature + Tests **Atomic?** Usually YES - Tests directly validate the feature code - They tell the same story - Can be reverted together **Example:** ``` feat(auth): implement OAuth authentication - 5 implementation files - 2 test files → ATOMIC (7 files, same feature) ``` ### Case 2: Feature + Documentation **Atomic?** DEPENDS - If docs describe the feature: YES - If docs are unrelated updates: NO **Example:** ``` feat(auth): add OAuth support - 5 auth files - 1 auth documentation file → ATOMIC (documents the feature) vs. feat(auth): add OAuth support - 5 auth files - README general update → NON-ATOMIC (split docs) ``` ### Case 3: Refactoring + New Feature **Atomic?** NO - Refactoring should be separate - Makes review harder - Mixing concerns **Example:** ``` Changes: - Refactor utils (3 files) - Add new payment feature (5 files) → NON-ATOMIC Split: 1. refactor(utils): simplify utility functions 2. feat(payments): add Stripe integration ``` ### Case 4: Multiple Small Fixes **Atomic?** DEPENDS - If all in same module: MAYBE - If unrelated: NO **Example:** ``` fix(auth): resolve three auth-related bugs - All in auth module - All are fixes - Related to each other → ATOMIC vs. - Fix auth bug - Fix API bug - Fix UI bug → NON-ATOMIC (different scopes) ``` ## Output Format Return: - Atomicity status (ATOMIC or SHOULD SPLIT) - Detailed analysis and reasoning - Atomicity checks (passed/failed) - Splitting recommendations if needed - Benefits explanation - Specific recommendation ## Error Handling **No changes:** ``` NO CHANGES TO ASSESS Working tree is clean. ``` **Single file change:** ``` ATOMIC (Single File) One file changed: Automatically atomic. ``` ## Integration with Agent The commit-assistant agent uses this operation to: 1. Determine if /commit or /commit-split should be used 2. Warn users about non-atomic changes 3. Provide splitting guidance 4. Educate users on atomic commit benefits ## Usage Example ```bash # Agent checks atomicity before committing # User: "commit my changes" # Agent: Invokes assess-atomicity # Operation: Returns "SHOULD SPLIT" # Agent: "Your changes should be split. Run /commit-review" ```