pr-and-commit-hygiene
Skill0 starsChanged 4 months agoMITView on GitHub
How to shape commits and pull requests so they are easy to review — small coherent diffs, structural changes separated from behavioral ones, commit messages that carry the why. Use when committing, opening a PR, or splitting up a large change.
In this repository32 other files it gives its agents.
- architect-modeSkill
- architecture-bundleSkill
- code-like-a-localSkill
- decision-making-guardrailsSkill
- decision-recordsSkill
- delivery-bundleSkill
- fable-modeSkill
- finish-the-turnSkill
- incident-response-playbookSkill
- launch-readiness-gateSkill
- lead-developer-modeSkill
- lead-with-outcomeSkill
- lean-tool-useSkill
- migration-refactor-safetySkill
- plan-before-implementationSkill
- product-delivery-bundleSkill
- product-minded-engineer-modeSkill
- reliability-bundleSkill
- reliability-incident-modeSkill
- review-quality-gateSkill
- run-guardrails-on-code-changesSkill
- security-bundleSkill
- security-minded-engineer-modeSkill
- senior-operating-systemSkill
- staff-engineering-bundleSkill
- staff-engineer-modeSkill
- stakeholder-communicationSkill
- surgical-questionsSkill
- systematic-debuggingSkill
- test-disciplineSkill
- truthful-reportingSkill
- verify-by-exercisingSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
If a PR needs the word "also" in its description, it's usually two PRs.
- Distinctive: line 19
Do the structural change first as its own commit or PR ("no behavior change" — a claim the reviewer can verify by running tests), then the …
- Distinctive: line 39
Do not mix drive-by refactors, reformatting, or renames into a behavior change.
- Distinctive: line 40
Do not write commit messages that restate the diff and omit the reason.
- Distinctive: line 41
Do not open a PR whose verification you cannot describe.
- Distinctive: line 42
Do not force the reviewer to reverse-engineer which of 800 lines is the real change.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
PR and commit hygiene
Review is the bottleneck of team delivery, and diff shape is what sets review speed. A change that is easy to review gets better review, sooner.
Keep changes small and coherent
- One logical change per PR. "Fix the timeout bug" and "rename the client module" are two PRs even if you did them in the same sitting.
- If a PR needs the word "also" in its description, it's usually two PRs.
- Large features ship as a sequence of small, individually shippable PRs — each one leaving the codebase working — not one monolith at the end.
Separate structural from behavioral changes
- A rename, move, or reformat mixed into a behavior change makes both unreviewable: the real change hides inside hundreds of mechanical lines.
- Do the structural change first as its own commit or PR ("no behavior change" — a claim the reviewer can verify by running tests), then the behavioral change as a small readable diff on top.
Commit messages carry the why
The subject line says what changed; the body says why — the context that has nowhere else to live. Code comments shouldn't justify changes to reviewers (that discipline is code-like-a-local), which makes the commit message exactly where that reasoning belongs.
- Bad:
fix bug/update handler/address review comments - Good: a subject naming the change, and a body with why it was needed, what alternative was rejected, and any non-obvious consequence.
The test: could a teammate running git log on this file in a year reconstruct why the code is this way?
Write the PR description for the reviewer
- Lead with the outcome: what does this change do, and why now.
- Say how it was verified — the command run, the tests added, the flow exercised.
- Point the reviewer at the risky part ("the retry logic in
worker.pyis the piece worth scrutiny; the rest is plumbing"). - Note what's deliberately out of scope, so the reviewer doesn't relitigate it.
Non-negotiables
- Do not mix drive-by refactors, reformatting, or renames into a behavior change.
- Do not write commit messages that restate the diff and omit the reason.
- Do not open a PR whose verification you cannot describe.
- Do not force the reviewer to reverse-engineer which of 800 lines is the real change.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.