gh-dhofheinz-open-plugins-plugins-git-commit-assistant/commands/commit-analysis/assess-atomicity.md

description

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

git status --short
git diff HEAD --stat
git diff HEAD

Step 2: Run Atomicity Analysis

Execute atomicity checker script:

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: <ATOMIC | SHOULD SPLIT>

ANALYSIS:
───────────────────────────────────────────────
Files Changed: X
Lines Changed: +XXX -XXX

Type Diversity: <Single | Multiple>
Scope Diversity: <Single | Multiple>
Logical Cohesion: <High | Medium | Low>

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:
───────────────────────────────────────────────
<detailed explanation>

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. <concern 1>
    2. <concern 2>
    3. <concern 3>

  Each concern should be a separate commit.

SPLITTING RECOMMENDATIONS:
───────────────────────────────────────────────
<if should split>

Recommended Commits:

Commit 1: <type>(<scope>): <description>
  Files: X files
  Purpose: <specific purpose>
  Files:
    - file1.js
    - file2.js
  Lines: +XX -YY

Commit 2: <type>(<scope>): <description>
  Files: X files
  Purpose: <specific purpose>
  Files:
    - file3.js
    - file4.js
  Lines: +XX -YY

BENEFITS OF SPLITTING:
───────────────────────────────────────────────
<if should split>
- Better code review (focused changes)
- Easier to revert individual features
- Clearer git history
- Better bisecting for bugs
- Easier cherry-picking

RECOMMENDATION:
───────────────────────────────────────────────
<specific actionable 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: <filename>
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

# 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"