Atomic Commits

Core Question

How should the selected change scope be split into minimal coherent commits without staging unrelated work, overwriting user choices, or hiding risky behavior?

When To Use

Use this skill when the user asks to:

• organize staged changes into atomic commits,
• split explicitly included changes into multiple commits,
• propose grouping for unstaged or untracked changes without staging by default,
• stage exact hunks or files only after explicit file/hunk confirmation,
• create several local commits from a large change when the source scope is explicit.

When Not To Use

Do not use this skill for message-only work, branch synchronization, conflict resolution, recovery, versioning, release notes, or tags.

Route to:

• conventional-commits for commit message generation or validation only.
• branch-workflow for branch creation, switching, sync, upstream, push, or remote refs.
• resolve-conflicts when the index has unmerged paths or conflict markers.
• undo-recover for reset, restore, abort, reflog, stash, broad unstage, or recovery work.
• version-bump, changelog-maintenance, release-notes, or tag-release for release workflows.

Required Evidence

Before action, inspect or establish:

• git status --short --branch,
• staged file list and staged diff,
• unstaged and untracked file list as excluded evidence by default,
• generated files, lockfiles, and documentation changes,
• project instructions and commit conventions,
• recent commit style when message conventions are unclear,
• test commands when discoverable,
• secret-like values in selected diffs.

Staged changes are the source of truth by default. Unstaged and untracked files are dirty-state evidence, not permission to stage them.

Commit Source Modes

Default mode: staged-only.

When staged changes exist, commit plans, commit messages, and commits must use staged changes only.

Unstaged and untracked files are dirty-state evidence, not permission to stage them.

Whole-working-tree mode is allowed only when the user explicitly says one of:

• "organize the whole working tree"
• "split all current changes"
• "commit all current changes"
• "include unstaged changes"

Even in whole-working-tree mode:

• do not use broad staging commands,
• present planned file/hunk groups before staging,
• require file-specific or group-specific confirmation before staging,
• verify git diff --cached --name-only before each commit.

Operating Contract

You MAY:

• inspect repository status, staged diff, unstaged diff, untracked files, and recent commits,
• propose commit groups,
• stage exact files or hunks only after explicit file/hunk confirmation,
• unstage only files or hunks staged by the agent during the current task or explicitly confirmed by the user,
• create local commits only when the user explicitly requested commit execution,
• call conventional-commits for message classification after the commit group is selected.

You MUST:

• preserve pre-existing user-staged work,
• keep each commit focused on one rollback/review intent,
• verify the staged set before every commit,
• keep generated files and lockfiles with their source change only when project evidence requires it,
• stop when selected scope is ambiguous or would overwrite user work,
• report excluded unstaged/untracked files.

You MUST NOT:

• stage unstaged or untracked files merely because they appear related,
• stage documentation files unless they are already staged or explicitly requested,
• convert a staged-only commit request into a whole-working-tree commit request,
• run git add ., git add -A, git add --all, or broad directory staging commands for atomic commits,
• run git reset, git restore --staged ., or broad unstaging commands to reshape user-staged work,
• unstage pre-existing user-staged files without explicit confirmation,
• push, amend, squash, force-push, or rewrite history from this skill without routing or explicit R5 confirmation.

State / Risk Table

Workflow

1. Identify whether the user requested a plan only or actual local commits.
2. Inspect status, staged diff, unstaged files, untracked files, and commit conventions.
3. Classify source mode: staged-only or explicitly confirmed whole-working-tree mode.
4. Classify state and risk.
5. Propose commit groups and excluded files.
6. For each group, verify exact staged file/hunk boundary.
7. Generate message using conventional-commits only for that group.
8. Create local commit only when requested and safe.
9. Verify log/status after each commit.
10. Report commits, evidence, verification, excluded files, and residual risk.

Decision Rules

• One commit should represent one logical intent and one likely rollback decision.
• If a message needs unrelated "and" clauses, split the commit.
• Keep tests with the behavior they validate unless the user requests test-only commits.
• Keep lockfile changes with dependency changes.
• Keep generated files with source changes only when generated artifacts are committed by project convention.
• Separate formatting-only changes from behavior changes unless the user explicitly selected them together.
• Separate docs from code unless already staged with the code or explicitly requested.
• Do not use unstaged or untracked files as commit candidates without explicit file/hunk confirmation.
• Do not create a commit if the staged boundary does not match the intended group.

Workflow Guardrails

Broad Staging Guardrail

Trigger:

• The user asks to commit, organize, split, or stage changes with broad wording such as all, everything, current changes, or whole working tree.

Default: <!-- guardrail:staging.default-staged-boundary -->

• Treat staged changes as the source of truth; treat unstaged and untracked files as excluded evidence.

Must:

• Inspect git diff --name-only, git diff --cached --name-only, and untracked paths.
• Present exact file or hunk groups before staging excluded work.
• Use git add -- exact-path or hunk staging only after file/hunk-specific confirmation.

Must not: <!-- guardrail:staging.no-stage-all-by-intent -->

• Treat commit intent as permission to stage all files.
• Run git add ., git add -A, or git add --all unless a skill-specific exception is explicitly confirmed and all paths are listed.
• Use broad unstaging to reshape pre-existing user-staged work.

Requires explicit confirmation:

• Each unstaged or untracked path/hunk to stage.
• Any exception to the broad staging ban.
• Any unstaging of pre-existing user-staged files.

Verification:

• Verify git diff --cached --name-only exactly matches the confirmed commit boundary before each commit.
• Report excluded unstaged and untracked files.

Tool Rules

Allowed:

• inspect status, diffs, logs, and commit convention evidence,
• propose atomic groups,
• create local commits only when explicitly requested and after staged boundaries are verified,
• stage only exact files/hunks after explicit file/hunk confirmation,
• unstage only files/hunks staged by the agent during the current task or explicitly confirmed by the user.

Forbidden without explicit routing or confirmation:

• broad staging, broad unstaging, reset, clean, stash drop, amend, squash, rebase, push, force-push, tag, or release publication,
• any command that may discard or rewrite user work.

Verification

Before each commit:

1. Inspect git diff --cached --name-only.
2. Confirm the staged file list matches the intended commit boundary.
3. Confirm excluded unstaged/untracked files are not staged.
4. Stop if unexpected staged files are present.

If unexpected staged files appear:

• stop and report the mismatch,
• do not unstage files unless the agent staged those exact files during the current task or the user explicitly confirms unstaging them,
• preserve pre-existing user-staged files.

After each commit:

• inspect git log -1 --oneline or equivalent commit evidence,
• inspect git status --short for remaining or excluded work,
• report tests run or verification not run.

Output Contract

Final response should include:

## State

- Branch and staged/unstaged/untracked state.

## Action

- Commit groups proposed or commits created.

## Evidence

- Status, diffs, files, and conventions used.

## Verification

- Cached file checks, commits created, tests or limitations.

## Remaining Risk

- Excluded files, unverified behavior, or required human review.

Stop / Confirmation Rules

Stop when the repository state is dirty, conflicted, diverged, missing required evidence, or ambiguous in a way that could overwrite user work, invalidate the requested scope, or require a gated action.

Requires explicit confirmation for:

• staging unstaged/untracked files,
• unstaging pre-existing user-staged files,
• broad staging or broad unstaging requests,
• destructive local changes,
• remote/shared mutation,
• history rewrite,
• secret remediation and recommit decisions.

Lazy-load References

Load:

• references/chunking-rules.md when grouping boundaries are ambiguous.
• references/commands.md when command choice is needed.
• references/examples.md when the user asks for examples.
• references/failure-modes.md when state is risky or ambiguous.
• references/verification.md when verification depth is unclear.