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.
- Applying SDD tasks without accidentally producing a PR above 400 changed lines.
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. |
| SDD workload guard |
If SDD tasks forecast a >400-line change, group commits into chained PR slices before implementation. |
| Budget is not code-golf |
Never shrink a diff by deleting comments, blank lines, docs, or tests, or by compressing code, to fit the review budget (400 by default, or the session review_budget_lines). Slice by work unit or report the overage. |
Work Unit Checklist
Before committing, confirm:
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 |
PR Relationship
Use work-unit commits as the foundation for chained PRs:
- Build the smallest independent work unit.
- Include verification for that unit.
- Commit it with a Conventional Commit message.
- If the PR approaches 400 changed lines, promote commits or groups of commits into chained PRs.
SDD Relationship
When sdd-tasks produces a Review Workload Forecast:
- Low risk: keep work-unit commits inside one PR.
- Medium risk: commit by work unit and monitor changed lines before PR creation.
- High risk: follow SDD
delivery_strategy — ask on ask-on-risk, auto-slice on auto-chain, require size:exception on over-budget single-pr, or record accepted size:exception on exception-ok.
- Splitting is bounded: after one honest slicing pass, if no cohesive work-unit split fits the budget, stop and report the smallest honest count with a
size:exception recommendation. Do not iterate shrinking the code to reach the number.
Each SDD work unit should map cleanly to a commit or PR with:
- clear start state,
- clear finished state,
- verification in the same unit,
- rollback that does not remove unrelated work.
Commands
# Review the story before committing
git diff --stat
git diff --cached --stat
# Check recent commit style
git log --oneline -5
1---2name: gentle-ai-work-unit-commits3description: Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.4license: Apache-2.05---67## When to Use89Load this skill when deciding what belongs in each commit or PR.1011Use it for:1213- Splitting a feature into reviewable work.14- Preparing commits before opening a PR.15- Turning a large change into chained or stacked PRs.16- Keeping reviewer cognitive load healthy.17- Applying SDD tasks without accidentally producing a PR above 400 changed lines.1819## Critical Rules2021| Rule | Requirement |22|------|-------------|23| Commit by work unit | A commit represents a deliverable behavior, fix, migration, or docs unit. |24| Do not commit by file type | Avoid `models`, then `services`, then `tests` if none works alone. |25| Keep tests with code | Tests belong in the same commit as the behavior they verify. |26| Keep docs with the user-visible change | Docs belong with the feature or workflow they explain. |27| Tell a story | A reviewer should understand why each commit exists from its diff and message. |28| Future PR-ready | Each commit should be a candidate chained PR when the change grows. |29| SDD workload guard | If SDD tasks forecast a >400-line change, group commits into chained PR slices before implementation. |30| Budget is not code-golf | Never shrink a diff by deleting comments, blank lines, docs, or tests, or by compressing code, to fit the review budget (400 by default, or the session `review_budget_lines`). Slice by work unit or report the overage. |3132## Work Unit Checklist3334Before committing, confirm:3536- [ ] The commit has one clear purpose.37- [ ] The repo still makes sense after applying only this commit.38- [ ] Tests or docs for this unit are included when relevant.39- [ ] Rollback is reasonable without reverting unrelated work.40- [ ] The commit message explains the outcome, not the file list.4142## Split Examples4344| Weak split | Better work-unit split |45|------------|------------------------|46| `add models` | `feat(auth): add token validation domain model and tests` |47| `add services` | `feat(auth): wire token validation into login flow` |48| `add tests` | Tests included with each behavior commit |49| `update docs` | Docs included with the user-facing change they explain |5051## PR Relationship5253Use work-unit commits as the foundation for chained PRs:54551. Build the smallest independent work unit.562. Include verification for that unit.573. Commit it with a Conventional Commit message.584. If the PR approaches 400 changed lines, promote commits or groups of commits into chained PRs.5960## SDD Relationship6162When `sdd-tasks` produces a Review Workload Forecast:6364- Low risk: keep work-unit commits inside one PR.65- Medium risk: commit by work unit and monitor changed lines before PR creation.66- High risk: follow SDD `delivery_strategy` — ask on `ask-on-risk`, auto-slice on `auto-chain`, require `size:exception` on over-budget `single-pr`, or record accepted `size:exception` on `exception-ok`.67- Splitting is bounded: after one honest slicing pass, if no cohesive work-unit split fits the budget, stop and report the smallest honest count with a `size:exception` recommendation. Do not iterate shrinking the code to reach the number.6869Each SDD work unit should map cleanly to a commit or PR with:7071- clear start state,72- clear finished state,73- verification in the same unit,74- rollback that does not remove unrelated work.7576## Commands7778```bash79# Review the story before committing80git diff --stat81git diff --cached --stat8283# Check recent commit style84git log --oneline -585```
Gentleman-Programming