# Atomic Commit Strategy Skill

A disciplined approach to version control and iterative development that enables high-frequency commits while maintaining stability and traceability.

---

## Core Philosophy

**"Each commit does exactly one thing."**

This principle enables:

- Fast problem isolation via `git bisect`
- Safe, surgical rollbacks
- Clear, reviewable code history
- Rapid iteration without cascading failures

---

## Commit Message Format

Follow the **Conventional Commits** specification:

```
<type>(<scope>): <description>

[optional body]

[optional footer(s)]
```

### Commit Types

| Type       | Purpose                                  | Impact Boundary              |
| ---------- | ---------------------------------------- | ---------------------------- |
| `fix`      | Bug fixes                                | No API changes               |
| `feat`     | New features                             | Clear, documented boundaries |
| `docs`     | Documentation only                       | Independent of code behavior |
| `refactor` | Code restructuring                       | No behavior changes          |
| `test`     | Adding or updating tests                 | No production code changes   |
| `chore`    | Build, CI, tooling, dependencies         | No production logic changes  |
| `perf`     | Performance improvements                 | No functional changes        |
| `style`    | Code formatting (whitespace, semicolons) | No logic changes             |

### Examples

```bash
# Good: Atomic, single-purpose commits
fix: honor state dir override in config resolution
feat: add webhook retry with exponential backoff
docs: update API authentication examples
refactor: extract validation logic into utils module
test: add edge cases for date parsing
chore: bump typescript to 5.4.0

# Bad: Multi-purpose commits
fix: various bug fixes and improvements
feat: add new features and fix some issues
update: changes to multiple files
```

---

## Implementation Rules

### Rule 1: One Logical Change Per Commit

Before committing, ask:

- Does this commit do exactly ONE thing?
- Can I describe it in a single sentence without "and"?
- If I revert this, will only ONE feature/fix be affected?

**Split commits when:**

- Fixing a bug AND adding a feature
- Refactoring AND changing behavior
- Updating deps AND modifying code that uses them

### Rule 2: Type Isolation

Each commit type has strict boundaries:

```
fix:      MUST NOT change public APIs or add features
feat:     MUST have clear scope; document breaking changes
refactor: MUST NOT change external behavior (tests should pass unchanged)
docs:     MUST NOT include code changes (except doc comments)
test:     MUST NOT modify production code
chore:    MUST NOT affect runtime behavior
```

### Rule 3: Commit Frequency

Commit early and often:

- After each logical unit of work completes
- Before switching context to a different task
- When tests pass for the current change

### Rule 4: Meaningful History

Each commit message should:

- Start with lowercase (after the type prefix)
- Use imperative mood ("add" not "added")
- Be concise but descriptive (50 chars or less for title)
- Reference issues when applicable: `fix: resolve timeout error (#123)`

---

## Quality Gates

### Before Each Commit

```bash
# 1. Review staged changes
git diff --staged

# 2. Ensure single logical change
# Ask: "Does this do ONE thing?"

# 3. Run relevant tests
npm test -- --related  # or equivalent

# 4. Lint/format check
npm run lint
```

### Commit Checklist

- [ ] Single logical change only
- [ ] Correct commit type selected
- [ ] Tests pass (or tests added for new code)
- [ ] No unrelated changes included
- [ ] Message clearly describes the change

---

## Progressive Release Strategy

For projects with release cycles:

```
feature branch → beta/canary → stable/main
```

### Workflow

1. **Development**: High-frequency commits to feature branches
2. **Beta Release**: Merge to beta branch, tag with `-beta.N`
3. **Validation**: Beta users test; fixes continue as atomic commits
4. **Stable Release**: Promote validated beta to stable

```bash
# Beta release
chore: prep 2024.3.15-beta.1 release

# After validation
chore: release 2024.3.15
```

---

## Continuous Hardening Pattern

Security and stability improvements should be:

- Incremental, not monolithic
- Clearly labeled with `fix: harden` prefix
- Focused on single attack vectors or failure modes

```bash
fix: harden file path traversal checks
fix: harden auth token validation
fix: harden rate limiting for API endpoints
fix: harden input sanitization for user content
```

---

## Documentation as Product

Documentation commits should be frequent and synchronized:

- Every `feat:` should have a corresponding `docs:` (same PR or follow-up)
- API changes require immediate doc updates
- README, CHANGELOG, and inline comments are first-class citizens

Target: **10-15% of commits should be documentation**

---

## Git Workflow Commands

### Interactive Staging (for splitting commits)

```bash
# Stage specific hunks
git add -p

# Stage specific files
git add path/to/specific/file.ts

# Unstage accidentally added files
git reset HEAD path/to/file.ts
```

### Amending (before push only)

```bash
# Fix last commit message
git commit --amend -m "fix: corrected message"

# Add forgotten file to last commit
git add forgotten-file.ts
git commit --amend --no-edit
```

### Bisect for Bug Hunting

```bash
git bisect start
git bisect bad                 # Current commit is broken
git bisect good <known-good>   # Last known working commit
# Git will binary search; mark each as good/bad
git bisect reset               # When done
```

---

## Anti-Patterns to Avoid

| Anti-Pattern           | Problem                     | Solution                                                |
| ---------------------- | --------------------------- | ------------------------------------------------------- |
| "WIP" commits          | Meaningless history         | Squash before merge or use descriptive messages         |
| "Fix stuff"            | No traceability             | Be specific: `fix: resolve null pointer in user lookup` |
| Mega-commits           | Impossible to review/revert | Split into atomic units                                 |
| Mixing types           | Violates isolation          | Separate into multiple commits                          |
| Committing broken code | Breaks bisect               | Always ensure tests pass                                |

---

## Integration with AI-Assisted Development

When using AI coding assistants:

1. **Review AI-generated changes** before committing
2. **Split AI output** into atomic commits if it spans multiple concerns
3. **Verify tests pass** for each logical unit
4. **Use AI to draft commit messages** but ensure accuracy

```bash
# Let AI suggest, but you decide the commit boundaries
# AI might generate: "Add validation and fix bug and update docs"
# You split into:
#   fix: resolve edge case in date validation
#   feat: add email format validation
#   docs: update validation API examples
```

---

## Metrics for Success

Track these to measure adoption:

| Metric                | Target            | Purpose              |
| --------------------- | ----------------- | -------------------- |
| Avg. files per commit | < 5               | Ensures atomicity    |
| Commits with tests    | > 30% of fix/feat | Quality assurance    |
| Doc commits ratio     | 10-15%            | Documentation health |
| Revert frequency      | < 2%              | Commit quality       |
| Bisect success rate   | > 90%             | History usefulness   |

---

## Quick Reference Card

```
COMMIT FORMULA:
  <type>(<scope>): <imperative-description>

TYPES:
  fix | feat | docs | refactor | test | chore | perf | style

RULES:
  ✓ One logical change per commit
  ✓ Type boundaries respected
  ✓ Tests pass before commit
  ✓ Message is clear and specific

BEFORE COMMIT:
  1. git diff --staged (review)
  2. Is this ONE thing? (verify)
  3. npm test (validate)
  4. git commit -m "type: description" (commit)
```

---

## References

- [Conventional Commits Specification](https://www.conventionalcommits.org/)
- [Git Bisect Documentation](https://git-scm.com/docs/git-bisect)
- [Semantic Versioning](https://semver.org/)