Immutable. This exact content is served forever at /api/v1/blob/ec648a0546df2407.
--- name: work-unit-commits description: "Structure commits as deliverable work units instead of file-type batches, with tests and docs kept beside the code they verify. Trigger: when implementing a change, preparing commits, splitting PRs, or planning chained or stacked PRs." 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. - 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. | ## 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 | ## PR Relationship Use work-unit commits as the foundation for chained PRs: 1. Build the smallest independent work unit. 2. Include verification for that unit. 3. Commit it with a Conventional Commit message. 4. 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`. 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 ```bash # Review the story before committing git diff --stat git diff --cached --stat # Check recent commit style git log --oneline -5 ```