| name | change-hygiene |
| description | Version-control and change-flow discipline — commits, branches, pull requests, code review flow, and history that stays useful. Use when committing, branching, opening or reviewing PRs, resolving merge conflicts, planning how a big change lands, or when the user says "commit", "PR", "pull request", "branch strategy", "git workflow", "merge", or "revert". |
Change Hygiene
Version control is not a backup system; it's your project's memory and undo button. Every discipline here serves two moments: the reviewer trying to verify your change today, and the debugger (human or AI) trying to understand it at 2 a.m. next year. Sloppy history taxes both, forever — and in AI-assisted development, where code volume is 10×, history hygiene is what keeps the firehose reviewable.
Commits — the unit of undo
- One logical change per commit, and the build passes at every commit. This is what makes
git bisect a superpower and revert a one-liner instead of surgery. "WIP", "fixes", "more changes" commits get squashed before they reach the shared branch.
- The message: subject line says what in imperative mood ("Reject payments exceeding invoice balance"), body says why and what alternative you rejected — the code already shows the what; only the message can carry the why (same rule as code comments, code-quality). A year later,
git log on a file should read as the file's biography.
- Never mix refactoring with behavior change in one commit — the single most valuable habit in this skill. A reviewer can verify "no behavior change" or "this one behavior changed", never both in one diff (legacy-code-changes, code-quality).
- Commit generated files, lockfiles yes (dependency-discipline); build artifacts, secrets,
.env no — and anything secret that ever touches history is burned: rotate it (threat-model-security), don't just delete the line.
Branches — short-lived or they rot
