---

name: push-checkpoint description: Run the every-10-pushes quality checkpoint — a scoped code review of everything since the last checkpoint, plus a test-and-lint debug pass. Use this skill whenever a hook reports that a push count hit a multiple of 10, whenever the user types /push-checkpoint, and whenever the user asks for a checkpoint, a periodic review, a "review the last batch of work" pass, or asks what has accumulated since the last review. Prefer this over an ad-hoc review whenever the request is about reviewing recent pushes as a batch.

Push Checkpoint

A periodic quality gate. Every 10 successful pushes, review what accumulated and confirm the project still builds clean — so problems surface on a cadence instead of piling up until release.

This skill does two things: a scoped review, then a debug pass. Do both, in order, and report once at the end.

How this gets triggered

.claude/hooks/push-counter.py runs after every Bash call, counts successful git push commands in .claude/state/push-count, and asks for this skill on every 10th. The user can also run /push-checkpoint at any time.

Skills cannot fire themselves on an event — the hook is what makes the cadence automatic. If the checkpoint never fires on its own, the hook is the thing to debug, not this file.

Step 0 — establish the range

Find the last checkpoint and scope all work to what came after it:

cat .claude/state/last-checkpoint 2>/dev/null || echo "(no previous checkpoint)"
git rev-parse HEAD

• If a SHA is recorded, the range is <sha>..HEAD.
• If not (first ever checkpoint), fall back to the last 10 commits: HEAD~10..HEAD, or the full history if the repo is shorter than that.

Confirm the range is non-empty before continuing:

git diff --stat <range>

If the range is empty, say so and stop — there is nothing to check, and the counter should still be reset in step 3.

Step 1 — review

Invoke the built-in code-review skill scoped to that range (pass the range as its target). Review the batch, not all of history.

Report findings ranked most-severe first. Apply a fix yourself only when it is small, local, and unambiguous — a clear bug, a typo, a missing guard. Anything larger gets described, not silently changed: this is a checkpoint, not a refactoring session.

Step 2 — debug

There is no /debug skill; this is the debug step. Run the project's own checks and triage anything that fails.

For this repository (Python):

python3 -m pytest -q
python3 -m ruff check .

If the project layout changes, run whatever the real checks are — prefer what pyproject.toml, a Makefile, or CI config actually defines over the commands above.

For each failure, find the root cause before proposing anything. Do not paper over a red test:

• Never skip, disable, or xfail a test to get green.
• Never loosen an assertion to match wrong output.
• A failure that reproduces on the base branch too is pre-existing — say so, and keep it separate from failures this batch introduced.

Fix what is small and certain. Escalate the rest with a concrete proposal.

Step 3 — record the checkpoint

Only after both steps are done:

git rev-parse HEAD > .claude/state/last-checkpoint

This is what keeps the next checkpoint scoped to the next batch. .claude/state/ is gitignored, so the counter and the checkpoint SHA stay local to each checkout.

Step 4 — report

One consolidated summary:

• Range — the commit span reviewed, and how many commits it covered.
• Review — findings by severity; what you fixed vs. what needs a decision.
• Debug — test and lint results; root cause for each failure; pre-existing failures called out separately.
• Verdict — is the tree healthy, or is there something to act on now?

Be direct about a bad result. A checkpoint that always says "all clear" is worthless — if tests fail, lead with that.