work-unit-commits

name	work-unit-commits
description	Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.
license	Apache-2.0
metadata	{"author":"gentleman-programming","version":"1.0"}

When to Use

Load this skill when deciding what belongs in each commit or PR.

Use it for:

• Splitting a feature into reviewable work.
• Preparing commits before opening a PR.
• Turning a large change into chained or stacked PRs.
• Keeping reviewer cognitive load healthy.

Critical Rules

Rule	Requirement
Commit by work unit	A commit represents a deliverable behavior, fix, migration, or docs unit.
Do not commit by file type	Avoid models, then services, then tests if none works alone.
Keep tests with code	Tests belong in the same commit as the behavior they verify.
Keep docs with the user-visible change	Docs belong with the feature or workflow they explain.
Tell a story	A reviewer should understand why each commit exists from its diff and message.
Future PR-ready	Each commit should be a candidate chained PR when the change grows.

Work Unit Checklist

Before committing, confirm:

• The commit has one clear purpose.
• The repo still makes sense after applying only this commit.
• Tests or docs for this unit are included when relevant.
• Rollback is reasonable without reverting unrelated work.
• The commit message explains the outcome, not the file list.

Split Examples

Weak split	Better work-unit split
add models	feat(auth): add token validation domain model and tests
add services	feat(auth): wire token validation into login flow
add tests	Tests included with each behavior commit
update docs	Docs included with the user-facing change they explain

Decision Gates

Question	Split into separate commits?
Does this commit work if the next one never lands?	✅ Yes — split
Do tests/docs belong to a behavior in this commit?	❌ No — keep together
Are these changes in different layers but same behavior?	❌ No — keep together
Are these two independent behaviors that happened to be done together?	✅ Yes — split
Would reverting this commit undo unrelated work?	✅ Yes — split

Output Contract

Return an ordered list of commits for the change, each with:

• <type>(<scope>): <description> — what the commit delivers
• Files included
• Why it belongs together (one sentence)

Gotchas

• Splitting by file type (models → services → tests) creates commits where none of them work alone — split by behavior
• Leaving docs out of the commit that adds the feature means docs arrive in a separate PR review cycle — keep together
• Commit messages that describe the file list ("update UserService and tests") don't explain WHY — describe the outcome
• Micro-commits for every line change add noise — one meaningful behavior = one commit

Commands

git diff --stat
git diff --cached --stat
git log --oneline -5