commit

Atomic Conventional Commits

Use this workflow whenever you create commits for a user. Optimize for precision, reviewability, and safety over speed.

The goal is a linear series of independently understandable commits where each commit represents exactly one logical change and uses a valid Conventional Commit message.

Non-negotiable rules

• Never use broad or destructive Git operations when a narrower operation can do the job.
• Never run git add ., git add -A, git add --all, or broad pathspecs.
• Never use git restore, git reset --hard, git clean, git checkout --, git switch, git rebase, git merge, or force-push commands unless the user explicitly approves the exact action.
• Never discard, overwrite, or revert user changes without explicit permission.
• Never bypass hooks. Do not use --no-verify.
• Treat untracked files as user-owned unless you created them during this run.
• Leave unrelated or ambiguous changes untouched.

Available helpers

• scripts/validate.py validates a Conventional Commit message before git commit.
• references/checklist.md contains the required staging, review, and scoring gates. Read it before the first commit in a session and whenever a commit is borderline.

Required workflow

1. Establish context safely:

   • Run git status --short.
   • Inspect only relevant diffs with precise paths, for example git diff -- path/to/file.
   • Use gh for repository context when helpful: gh issue view <number>, gh pr view <number>, gh pr diff <number>, or gh auth status.
   • Do not use gh to mutate issues, PRs, branches, or remotes unless the user explicitly asked for that action.

2. Partition work by intent:

   • Identify each distinct logical change.
   • Group implementation and tests for the same behavior in the same commit.
   • Separate refactors, formatting, renames, build changes, docs, tests-only changes, and functional changes unless they are inseparable.
   • If one staged set implies multiple intent statements, split it.

3. For each intended commit, write these two sentences before staging:

   • Intent: one sentence describing exactly what the commit accomplishes.
   • Coherence: one sentence explaining why the change cannot be split further without losing useful coherence.

4. Stage narrowly:

   • Prefer git add -p path/to/file when a file contains mixed concerns.
   • Use git add path/to/file only when every change in that file belongs to the commit intent.
   • Stage newly created files by exact path only.
   • After staging, run git diff --cached.

5. Validate before committing:

   • Review the staged diff as a human reviewer.
   • Ask: "Would a human reviewer understand this commit instantly?"
   • Apply every gate in references/checklist.md.
   • If any gate fails, unstage or revise only the affected paths or hunks with the smallest safe command available. Ask for user approval before any operation that would discard changes.

6. Validate the commit message:

   • Use this format: <type>[optional scope][!]: <description>
   • Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
   • Use a scope when it clarifies the affected area.
   • Use ! only for breaking changes and include a BREAKING CHANGE: footer.
   • Keep the header at 72 characters or fewer.
   • Prefer a description of 50 characters or fewer.
   • Write the subject in imperative, present tense, lowercase except proper nouns.
   • Do not end the subject with a period.
   • Never use vague subjects such as update, changes, fixes, or misc.
   • Wrap body and footer lines at 72 characters or fewer.

   Validate the proposed message before committing:

   python3 scripts/validate.py --message-file /path/to/message.txt
   

   If writing the message inline, validate with stdin:

   printf '%s\n' 'fix(api): reject empty tokens' | python3 scripts/validate.py
   

7. Commit:

   • Run the relevant tests or verification before committing whenever feasible.
   • Commit only after atomicity, staged diff, tests, and message validation all pass.
   • Use git commit --file /path/to/message.txt for multi-line messages or git commit -m "type(scope): subject" for single-line messages.
   • Let hooks run normally. If a hook fails, stop, inspect the output, fix the underlying issue, re-stage precisely, re-run validation, and retry.

8. Repeat for the next intent:

   • Run git status --short after each commit.
   • Ensure later commits do not repair avoidable breakage introduced by earlier commits.
   • Order commits so earlier commits do not depend on later commits.

Atomicity scoring

Every commit must score yes on all items before it is created:

Single responsibility: yes/no
Minimal diff: yes/no
Clear intent: yes/no
Conventional commit compliance: yes/no
Independently testable: yes/no

If any answer is no, do not commit. Split, revise, or ask the user how to handle the ambiguity.

Safe command examples

git status --short
git diff -- path/to/file
git add -p path/to/file
git add path/to/new-file
git diff --cached
git commit --file /tmp/commit-message.txt
gh issue view 123
gh pr view 456 --json title,body,files

Avoid convenience commands that operate on the whole worktree. When in doubt, choose the smallest path-specific or hunk-specific command and explain why.