SKILL.md
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.
- Focused test command and exact result are recorded.
- Runtime harness command/scenario and exact result are recorded, or explicit
N/Aexplains why no runtime boundary exists. - Rollback boundary names the exact files/behavior removable without 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:
- 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 onask-on-risk, auto-slice onauto-chain, requiresize:exceptionon over-budgetsingle-pr, or record acceptedsize:exceptiononexception-ok. - Count authored additions plus deletions for the
>400threshold. Exclude generated goldens from that authored count, but include every generated file in complete snapshot identity and receipt validation.
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.
Its implementation evidence MUST include:
- Focused test command and exact result.
- Runtime harness command/scenario and exact result, or explicit
N/Awith reason. - Rollback boundary stated independently of commit creation; uncommitted work units still require it.
- When fixing a bounded review ledger, group atomic work units inside the single correction transaction; work-unit count never creates another fix budget.
Commands
# Review the story before committing
git diff --stat
git diff --cached --stat
# Check recent commit style
git log --oneline -5