atomic-commits

Files (1)

• SKILL.md

SKILL.md (first lines)

# Atomic Commits

## Overview

Take a dirty working tree of uncertain provenance and produce a clean, linear sequence of atomic commits where every commit builds, every commit could be reverted in isolation, and `git bisect` will land on a meaningful unit when chasing a regression. The agent does not assume it remembers what changed — it investigates, classifies, groups, then commits.

## Core Principle: The Bisect Test

Every commit must satisfy this test:

> If `git bisect` lands on this commit alone, can the project still build, run its test suite, and be deployed? And does the commit's title accurately describe a single coherent change?

This produces two rules that govern every grouping decision:

1. **Smallest buildable + deployable unit.** Do not split a change so finely that an intermediate commit fails to compile, breaks tests, or leaves an import dangling. A new module and its first caller belong together if the caller would not compile without the module.
2. **No smaller, no larger.** Do not bundle two unrelated improvements just because they touched the same file. Two bug fixes in `auth.py` should be two commits — bisect cannot tell which one introduced a regression if they ship together.

When the two pull in different directions, prefer the smaller commit and add the minimum scaffolding (e.g., a stub, a no-op default) needed to keep the tree green.

## Workflow

### Phase 1 — Survey

Before classifying anything, get a complete picture of the working tree.

```bash
git status --short
git diff --stat
git diff                       # unstaged
git diff --cached              # staged (rare in this workflow but check)
git log -10 --oneline          # recent history for tone/style of messages
```

If there are staged changes already, decide whether to keep them as-is (commit first) or unstage to reclassify (`git reset HEAD`) — but never use destructive resets. When unsure, ask the user.

### Phase 2 — Investigate

Treat the diff as code written by someone else. For each modified file:

1. **Read the full diff** for the file (`git diff -- path/to/file`), not just the hunks summary.
2. **Read surrounding code** when the diff alone does not explain intent — function signatures, imports, related call sites.
3. **Note the *kind* of change** for each hunk: feature addition, bug fix, refactor, test, docs, formatting, dependency bump, generated/lockfile, config, dead-code removal.
4. **Note dependencies between hunks**: does hunk B import a symbol introduced by hunk A? Does a test in `tests/` exercise a new function in `src/`?

Write a brief mental (or scratch) inventory: a list of logical changes, each tagged with the files and hunks it spans. This inventory is what gets converted into commits.

### Phase 3 — Group

Map the inventory of logical changes onto a commit sequence:

- **One logical change → one commit.** A bug fix and the regression test that proves it is *one* logical change and belongs in *one* commit.
- **Order commits to keep the tree green.** Foundations first (new module, then its callers; new field on a struct, then code that reads it; new test fixture, then tests using it). Never schedule a commit that depends on a symbol introduced by a later commit.
- **Refactors are their own commits.** A behavior-preserving rename or extraction should not ride along with a behavioral change. If a feature commit also contains an unrelated refactor, split them.
- **Generated files travel with the change that regenerates them.** A lockfile bump goes with the dependency change that caused it; a generated client goes with the schema change.
- **Formatting-only changes are their own commit, ideally first or last.** Mixing a reformat into a feature commit obscures the diff under review and confuses bisect.
- **Docs, tests, and code touching the same change live together.** Splitting these is over-fragmentation and breaks the "deployable" half of the rule.

If a single file contains hunks belonging to multiple logical changes, plan to use `cortex git patch` (Phase 4 — hunk-level path).

### Phase 4 — Commit

Use the right tool for the shape of the commit.

#### File-level: `cortex git commit`

When every hunk in each named file belongs to the same logical change, commit the files whole:

```bash
cortex git commit "feat(auth): add OAuth2 device flow support" \
  src/auth/oauth_device.py tests/auth/test_oauth_device.py
```

This stages the named files in full from the working tree and commits atomically. Use this whenever possible — it's the simplest and safest path.

#### Hunk-level: `cortex git patch --diff`

When a file contains hunks that belong to *different* logical changes, isolate the hunks for one commit via a diff fed through `--diff`. The `files` positional is an allowlist — the command will refuse to commit if the diff stages anything outside that list, so name only the files this particular commit should touch.

Two practical ways to produce the diff:

**Option A — interactive split via temp file.** Generate the file's full diff, edit it down to only the hunks for this commit, then apply:

```bash
git diff -- src/auth/oauth_device.py > /tmp/commit-1.diff
# edit /tmp/commit-1.diff in place: delete hunks that don't belong in this commit
cortex git patch "fix(auth): reject device codes after expiry" \
  --diff /tmp/commit-1.diff src/auth/oauth_device.py
```

**Option B — stdin pipe.** Build the targeted diff with `git diff` flags or by piping through filters, and feed via `-`:

```bash
git diff -- src/auth/oauth_device.py \
  | filter-hunks-script \
  | cortex git patch "fix(auth): reject device codes after expiry" \
      --diff - src/auth/oauth_device.py
```

After each hunk-level commit, the remaining hunks for that file stay in the working tree, ready to be committed (whole or split again) by the next call.

**Strongly prefer hunk-level commits over bundling unrelated changes.** Two bug fixes in the same file should not share a commit. The hunk-level path is the right tool, not a last resort.

#### Commit message conventions

Recent history in most Cortex/Nick projects uses Conventional Commits with lowercase types:

- `feat(scope): summary` — new behavior
- `fix(scope): summary` — bug fix
- `refactor(scope): summary` — behavior-preserving change
- `docs(scope): summary` — docs only
- `test(scope): summary` — tests only
- `chore(scope): summary` — tooling, deps, build
- `build(scope): summary` — packaging, lockfiles

Always check `git log -10 --oneline` first and match the project's actual style.

### Phase 5 — Verify

After the last commit, confirm the result:

From NickCrew/Claude-Cortex, MIT.

More from NickCrew/Claude-Cortex