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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.3 KB |
SKILL.md
View on GitHub---
name: incremental-commits
description: Plan 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
1. Inventory the changed and expected files and identify logical concerns.
2. Map dependencies between those concerns. Foundations and contracts usually
precede consumers, but follow the actual code rather than a fixed layer
template.
3. Choose boundaries that are coherent and, when practical, buildable and
testable on their own.
4. Note any unavoidable temporary incompatibility and decide whether it makes
a split less useful.
## Implement and verify
For each planned commit:
1. Change or stage only that concern.
2. Run the smallest relevant checks required by the repository.
3. Review the staged diff as a standalone change.
4. Commit using the `git-commit` skill.
5. 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 |