playbooks

home / skills / tkersey / dotfiles / commit

commit skill

/codex/skills/commit

This skill helps you create surgical micro-commits with validation signals, ensuring minimal changes and clear review checkpoints during development.

npx playbooks add skill tkersey/dotfiles --skill commit

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
2.1 KB
---
name: commit
description: Create micro-commits (minimal incision) with at least one validation signal per commit. Use when requests say "split this into micro commits," "stage only the minimal change and commit," "keep commits tiny while checks pass," or when parallel workers/slices need isolated, reviewable commits.
---

# Commit

## Intent
Carve changes into surgical commits: one coherent change, minimal blast radius, and at least one feedback signal before committing.

## When to use
- “Split this into micro commits.”
- “Stage only the minimal change and commit it.”
- “Keep the commits tiny, keep checks passing.”

## Workflow (Surgeon’s principle)

### 1) Scope the incision
- Identify the smallest change that can stand alone.
- Isolate unrelated edits; avoid drive-by refactors/formatting unless required for correctness.

### 2) Stage surgically (non-interactive-first)
Inspect:
- `git status -sb`
- `git diff`

Stage what you intend (prefer file-level staging in non-interactive harnesses):
- `git add <paths...>`
- `git restore --staged <paths...>`

Verify:
- `git diff --cached` matches the intended incision.

If you truly need hunk-level staging but your environment can’t do interactive staging, ask the user to stage hunks locally or provide a patch you can apply.

### 3) Validate the micro scope
- Optional helper: `scripts/micro_scope.py` (staged vs unstaged size).
- If the staged diff is multi-concern, split it before running checks.

### 4) Close the loop (required)
- Select the tightest available signal and run it.
- If the repo’s test/check command is not discoverable, ask for the preferred command.
- Reference: `references/loop-detection.md`.

### 5) Commit
- Use a terse message; optimize for clarity, not poetry.
- Commit only after at least one signal passes.

### 6) Repeat
Repeat until the working tree is clean or the remaining changes are intentionally deferred.

## Guardrails
- Don’t widen scope without asking.
- Prefer the smallest check that meaningfully exercises the change.
- Don’t claim completion without a passing signal.

## Resources
- `scripts/micro_scope.py`
- `references/loop-detection.md`

Overview

This skill creates surgical micro-commits: minimal, coherent changes each accompanied by at least one validation signal before committing. It is designed for workflows that require isolated, reviewable commits or when parallel workers/slices need separate checkpoints.

How this skill works

The skill scopes the smallest standalone change, stages only that change, verifies the staged diff, runs a tight validation signal (tests or checks), and commits with a terse, clear message only after a passing signal. It repeats the process until the working tree is clean or remaining edits are intentionally deferred.

When to use it

  • When asked to split a large change into micro commits or 'split this into micro commits'.
  • When instructed to stage only the minimal change and commit it.
  • When you must keep commits tiny and ensure checks pass for each commit.
  • When parallel workers or feature slices require isolated, reviewable commits.
  • When you want minimal blast radius for code review or bisectability.

Best practices

  • Identify the smallest logical edit that can stand alone before staging.
  • Avoid unrelated edits or drive-by refactors unless necessary for correctness.
  • Stage at file-level in non-interactive environments; verify with git diff --cached.
  • Run the tightest meaningful validation (unit test, lint, or script) before committing.
  • Use concise, explicit commit messages and do not commit until a signal passes.

Example use cases

  • Breaking a multi-file change into independent commits, each with its own passing test.
  • Staging and committing a single config tweak while leaving formatting changes for later.
  • Producing reviewable commits for parallel feature branches handled by different reviewers.
  • Making a small fix that requires running a targeted lint or unit test before commit.
  • Preparing bisect-friendly commits by keeping each commit minimal and validated.

FAQ

What validation signal should I run for a micro-commit?

Prefer the smallest check that exercises the change: a focused unit test, a lint rule, or a script defined by the repo. If none are discoverable, ask for the preferred command.

How do I stage hunks if the environment is non-interactive?

Stage file-level changes with git add and ask the user to stage hunks locally or provide a patch you can apply if true hunk-level staging is required.