aspiers/ai-config / .agents/skills/incremental-commits
incremental-commits
VerifiedPlan dependency-aware atomic commits for changes that span multiple logical concerns. Use when a refactor, feature, or API change would benefit from reviewable, independently meaningful commit boundaries. To triage an already-dirty working tree and propose commits for existing uncommitted changes, use `planning-commits` instead.
Incremental Commits
Turn a multi-concern change into a reviewable sequence without forcing every multi-file edit into multiple commits.
Decide whether to split
Split when commits represent independently understandable concerns, improve review or rollback, or establish dependencies needed by later work. Keep one commit when separating the change would create misleading, broken, or meaningless intermediate states.
File count is evidence, not a rule. Avoid both catch-all commits and one-symbol micro-commits.
Plan the sequence
- Inventory the changed and expected files and identify logical concerns.
- Map dependencies between those concerns. Foundations and contracts usually precede consumers, but follow the actual code rather than a fixed layer template.
- Choose boundaries that are coherent and, when practical, buildable and testable on their own.
- Note any unavoidable temporary incompatibility and decide whether it makes a split less useful.
Implement and verify
For each planned commit:
- Change or stage only that concern.
- Run the smallest relevant checks required by the repository.
- Review the staged diff as a standalone change.
- Commit using the
git-commitskill. - Reassess later boundaries if implementation reveals a better grouping.
Run the final repository quality gates after the sequence. The history should explain the change in dependency order without requiring later commits to make an earlier commit truthful.
Common failure modes
- Monolith: unrelated behavior, cleanup, and dependency changes share one commit merely because they were developed together.
- Artificial sequence: a fixed “types, factories, API, consumers” pattern is imposed even though the repository has different boundaries.
- Micro-history: mechanical fragments cannot be reviewed or reverted meaningfully on their own.
- Broken middle: an intermediate commit fails required checks without a documented reason.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |