X-Financial/.codex/skills/git-checkpoint-commit/SKILL.md

name, description

name	description
git-checkpoint-commit	Use when a coding task finishes a verified bug fix, key feature, risky refactor checkpoint, local backup commit, checkpoint commit, 提交备份, 本地提交, or when an active session has accumulated about five meaningful edit rounds and should create a scoped local git commit without pushing.

Git Checkpoint Commit

Overview

Use this skill to keep a local git backup loop during active development. The goal is to commit verified, task-scoped progress at meaningful checkpoints without mixing unrelated user changes or pushing remotely.

Trigger Rules

Create a local checkpoint commit when any condition is true:

• A bug fix is implemented and the targeted regression check passes.
• A key feature slice is implemented and the smallest relevant verification passes.
• A risky refactor reaches a behavior-preserving checkpoint.
• The current session has reached about five meaningful edit rounds since the last commit.
• The user asks for 提交, 本地提交, 备份, checkpoint, commit, or 形成提交循环.

Do not use this skill when the user explicitly says not to commit, when the change is exploratory and unverified, or when the only available commit would include unrelated dirty files.

Workflow

1. Inspect the working tree with git status --short.
2. Identify files or hunks owned by the current task.
3. Run the smallest relevant verification first.
   • In X-Financial, run backend tests inside x-financial-main when backend code is involved.
   • Use targeted frontend tests/builds for web-only changes.
4. Commit only the task-owned files.
5. Report the commit hash and verification evidence.
6. Reset the session edit counter to zero after a successful checkpoint.

Safety Rules

• Never commit unrelated user changes just to make the tree clean.
• Never push as part of this skill.
• Never rewrite history, amend old commits, or run destructive git commands.
• If the same file contains unrelated hunks, split the staging carefully with git add -p or a narrower manual patch.
• If the index already contains staged changes, inspect them first; do not mix them into a checkpoint unless they belong to the same current task.
• If verification cannot run, say why in the commit body or final report and prefer a chore(checkpoint) message rather than a confident fix or feat.

Commit Style

Use normal semantic messages for completed, verified work:

• fix(workbench): keep application preview after draft save failure
• feat(reimbursements): add attachment association job polling
• refactor(claims): split draft flow serialization

Use checkpoint messages for interim backup points:

• chore(checkpoint): backup attachment association flow
• chore(checkpoint): backup after five edit rounds

Keep the subject concise. Add body lines only when the verification state or scope needs clarity.

Helper Script

Use scripts/checkpoint_commit.py when a path-scoped local commit is enough:

python3 .codex/skills/git-checkpoint-commit/scripts/checkpoint_commit.py \
  --message "chore(checkpoint): backup workbench AI flow" \
  web/src/composables/workbenchAiMode/useWorkbenchAiExpenseFlow.js \
  web/tests/workbench-ai-mode-switch.test.mjs

Preview before committing:

python3 .codex/skills/git-checkpoint-commit/scripts/checkpoint_commit.py \
  --dry-run \
  web/src/utils/expenseApplicationPreview.js

The script refuses to commit the whole tree unless --allow-all is passed. Use --allow-all only when the current task truly owns every dirty file.

Common Mistakes

• Mistaking backup for verification. Verify first, then commit.
• Staging . in a dirty worktree. Stage explicit paths or hunks.
• Combining documentation cleanup, feature work, and unrelated local edits in one checkpoint.
• Continuing indefinitely after multiple verified slices. Commit once the counter reaches five meaningful edit rounds.