Atomic Commit Discipline
Overview
Turn completed work into small, reviewable commits with scoped validation, related task-state updates, and no unrelated files.
This skill is not a review template or ledger template. It focuses on minimal commits, exact staged paths, task-state coupling, validation, and commit messages. For shared harness terms, see ../../references/harness-patterns.md; when commit rules are absent, use references/build-when-missing.md. For delivery artifact evidence, see references/delivery-artifact-checklist.md.
When To Use
- The user asks to commit, split commits, stage exact paths, or avoid unrelated changes.
- You are preparing a commit and need to inspect
git status or diffs to avoid unrelated work.
- The worktree has multiple changes and you need to decide which belong in the same logical commit.
- A tracked task is completed, changed, or invalidated and its task-state update must travel with the related commit.
- The project requires Conventional Commits or a ledger entry paired with each commit.
Inputs Needed
- Current
git status, git diff, and git diff --cached.
- User goal and completed validation.
- Current task-state surface, such as
tasks.md, docs/tasks.md, or the repository's issue tracker reference.
- Repository commit rules and whether ledger entries must be committed together.
Execution Order
- First: Read
git status and relevant diffs to identify your changes and unrelated changes.
- Then: Split staged paths by one logical behavior per commit, include related task-state updates, and run the minimum relevant validation.
- Finally: Write a Conventional Commit message, commit, and re-check status and commit contents.
Step-by-Step Process
- Run
git status --short --branch and list all tracked and untracked changes.
- Read
git diff -- <path> for every file you intend to commit; do not commit changes you do not understand.
- If no commit discipline is documented, bootstrap the minimum grouping and validation checklist from
references/build-when-missing.md.
- Identify whether the change completes, changes, or invalidates a tracked task; if yes, include the corresponding task-state update in the same logical commit.
- Group by logical boundary: docs, tests, implementation, harness, ledger, and task state should not be mixed unless they describe the same logical change or repository rules require the same commit.
- Run the smallest validation command that matches each group; fix failures before committing.
- Use
git add <exact paths>; avoid git add . unless the whole worktree contains only this change.
- Write a Conventional Commit subject, and use the body for validation, skip reasons, task IDs, or linked artifacts when needed.
- After committing, run
git show --stat --oneline HEAD and git status --short.
Checks
- Scope: each commit has one logical purpose.
- Ownership: no user-owned changes or temporary generated files are included by accident.
- Task coupling: task-state updates are present when the commit fulfills, changes, or invalidates a tracked task; unrelated task churn is absent.
- Validation: the commit has matching pre-commit validation.
- Message: the subject describes behavior, not "update files."
- Ledger: if the repository requires
agent_chats in the same commit, it is staged with the change.
Output Format
# Atomic Commit Plan
## Detected Mapping
- work-state:
- ledger:
- validation:
## Worktree State
-
## Commit Groups
1. Subject:
Paths:
Task-state updates:
Validation:
## Excluded Changes
-
## Final Checks
- First:
- Then:
- Finally:
Common Mistakes
- Using
git add . and bringing unrelated files into the commit.
- Mixing features, formatting, docs, refactors, and temporary fixes in one commit.
- Splitting a completed task's status update into a later unrelated commit.
- Committing before reading the diff.
- Writing commit messages such as "fix" or "update."
- Committing after validation fails.
Example Prompts
- "Split these changes into atomic commits."
- "Commit only the harness docs and leave unrelated files unstaged."
- "Check git status and commit by logical group, including related task updates."
1---2name: atomic-commit-discipline3description: Use when splitting changes into atomic commits, preparing commits from mixed worktrees, staging exact paths, including related task-state updates, writing Conventional Commits, or preventing unrelated changes.4metadata:5 source: https://skillmd.com/skills/concertonotes/atomic-commit-discipline6---78# Atomic Commit Discipline910## Overview1112Turn completed work into small, reviewable commits with scoped validation, related task-state updates, and no unrelated files.1314This skill is not a review template or ledger template. It focuses on minimal commits, exact staged paths, task-state coupling, validation, and commit messages. For shared harness terms, see `../../references/harness-patterns.md`; when commit rules are absent, use `references/build-when-missing.md`. For delivery artifact evidence, see `references/delivery-artifact-checklist.md`.1516## When To Use1718- The user asks to commit, split commits, stage exact paths, or avoid unrelated changes.19- You are preparing a commit and need to inspect `git status` or diffs to avoid unrelated work.20- The worktree has multiple changes and you need to decide which belong in the same logical commit.21- A tracked task is completed, changed, or invalidated and its task-state update must travel with the related commit.22- The project requires Conventional Commits or a ledger entry paired with each commit.2324## Inputs Needed2526- Current `git status`, `git diff`, and `git diff --cached`.27- User goal and completed validation.28- Current task-state surface, such as `tasks.md`, `docs/tasks.md`, or the repository's issue tracker reference.29- Repository commit rules and whether ledger entries must be committed together.3031## Execution Order3233- First: Read `git status` and relevant diffs to identify your changes and unrelated changes.34- Then: Split staged paths by one logical behavior per commit, include related task-state updates, and run the minimum relevant validation.35- Finally: Write a Conventional Commit message, commit, and re-check status and commit contents.3637## Step-by-Step Process38391. Run `git status --short --branch` and list all tracked and untracked changes.402. Read `git diff -- <path>` for every file you intend to commit; do not commit changes you do not understand.413. If no commit discipline is documented, bootstrap the minimum grouping and validation checklist from `references/build-when-missing.md`.424. Identify whether the change completes, changes, or invalidates a tracked task; if yes, include the corresponding task-state update in the same logical commit.435. Group by logical boundary: docs, tests, implementation, harness, ledger, and task state should not be mixed unless they describe the same logical change or repository rules require the same commit.446. Run the smallest validation command that matches each group; fix failures before committing.457. Use `git add <exact paths>`; avoid `git add .` unless the whole worktree contains only this change.468. Write a Conventional Commit subject, and use the body for validation, skip reasons, task IDs, or linked artifacts when needed.479. After committing, run `git show --stat --oneline HEAD` and `git status --short`.4849## Checks5051- Scope: each commit has one logical purpose.52- Ownership: no user-owned changes or temporary generated files are included by accident.53- Task coupling: task-state updates are present when the commit fulfills, changes, or invalidates a tracked task; unrelated task churn is absent.54- Validation: the commit has matching pre-commit validation.55- Message: the subject describes behavior, not "update files."56- Ledger: if the repository requires `agent_chats` in the same commit, it is staged with the change.5758## Output Format5960```markdown61# Atomic Commit Plan6263## Detected Mapping64- work-state:65- ledger:66- validation:6768## Worktree State69-7071## Commit Groups721. Subject:73 Paths:74 Task-state updates:75 Validation:7677## Excluded Changes78-7980## Final Checks81- First:82- Then:83- Finally:84```8586## Common Mistakes8788- Using `git add .` and bringing unrelated files into the commit.89- Mixing features, formatting, docs, refactors, and temporary fixes in one commit.90- Splitting a completed task's status update into a later unrelated commit.91- Committing before reading the diff.92- Writing commit messages such as "fix" or "update."93- Committing after validation fails.9495## Example Prompts9697- "Split these changes into atomic commits."98- "Commit only the harness docs and leave unrelated files unstaged."99- "Check git status and commit by logical group, including related task updates."