Immutable. This exact content is served forever at /api/v1/blob/6d1ec334136b27a2.
--- name: gentle-ai-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. - 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: - [ ] 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`. - 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 ```bash # Review the story before committing git diff --stat git diff --cached --stat # Check recent commit style git log --oneline -5 ```