commit-work

Skill: Commit Work

Purpose

Produce git commits that are easy to review and safely deliverable: containing only the intended changes, with reasonable commit granularity, and messages that clearly explain what was done + why. This skill integrates with AI Cortex's INDEX synchronization constraint; when a commit involves changes in the skills/ directory, it verifies whether INDEX.md has been updated.

Core Objective

Primary objective: Generate one or more git commits with clear messages, logical scope, and verified quality, ready to push.

Success criteria(all requirements must be met):

✅ Reviewed changes: Run "git diff" before staging, and run "git diff --cached" before each commit
✅ Logical scope: Each commit contains only related changes; unrelated changes are split into separate commits
✅ Conventional commit format: All commit messages follow the type(scope):summary format, with a clear body
✅ Quality verification: Run the appropriate tests, lint, or build commands and all checks pass
✅ No sensitive data: No secrets, tokens, debug code, or unintended changes included
✅ INDEX synchronization(AI Cortex project): When skills / rules / spec / protocol change, synchronize the corresponding INDEX.md

AcceptanceTest: Can a reviewer understand what changed and why solely from the commit message, without reading the diff?

Scope boundaries (Scope Boundaries)

This skill is responsible for：

Reviewing uncommitted changes
Splitting mixed changes into logical commits
Staging changes using patch mode when needed
Writing conventional commit messages
Running pre-commit quality checks
Synchronizing the AI Cortex registry (INDEX.md)

This skill is not responsible for：

Code review of existing commits (use the "review-diff" skill)
Rewriting git history or rebasing (use git rebase commands)
Resolving merge conflicts (use the git merge/rebase workflow)
Creating pull requests or pushing to remote (separate workflow)

Handoff point: When all changes are committed and verified, hand off to the push/PR workflow or the next development task.

Use cases (Use Cases)

The user asks to commit work, stage changes, or produce a commit message
Mixed changes need to be split into logical, reviewable commits
Create commits that follow the conventional commit format
Ensure commits meet project quality standards before pushing
When working in the AI Cortex project, ensure skills/INDEX.md / rules/INDEX.md / specs/INDEX.md / protocols/INDEX.md are synchronized with the corresponding assets

Behavior (Behavior)

Workflow (Checklist)

If CLAUDE.md or .ai-cortex/config.yamlexists, preferentially read the test_command within it for quality verification; otherwise infer from the project build configuration. See docs/guides/project-config.md。

Inspect the working tree before staging
- Rungit status
- Run "git diff" (unstaged changes)
- If there are many changes:git diff --stat for an overview
Pre-commit review recommended (halt-and-suggest)
- Suggest the user first run /review-diff(or /orchestrate-code-review); this skill does not directly invoke other skills
- After the user runs it and returns findings, continue with staging
- If the user skips this step: proceed directly to the next step (non-blocking)
Decide commit boundaries (split if needed)
- Divide by logical concern:
  - Features and refactoring
  - Backend and frontend
  - Formatting and logic
  - Tests and production code
  - Dependency bumps and behavior changes
- If changes are mixed within one file, plan to use patch staging
Stage only what belongs to the next commit
- Prefer patch staging for mixed changes:git add -p
- To unstage a hunk/file: git restore --staged -p or git Restore --staged <path>
- Stage related changes together
Review what will actually be committed
- Run "git diff --cached"
- Sanity checks:
  - No secrets or tokens
  - No accidental debug logging
  - No unrelated formatting changes
  - No commented-out code blocks
Describe the staged changes in 1-2 sentences
- Answer: "What changed?" + "Why?"
- If you cannot describe it clearly, the commit may be too large or mixed; return to step 3
Write the commit message
- Use conventional commits (required):

     type(scope): short summary
     
     body (what/why, not implementation diary)
     
     footer (BREAKING CHANGE) if needed
     ```

   - 更喜欢多行消息的编辑器：`git commit -v`
   - Use `references/commit-message-template.md` if helpful
   - 保持摘要的必要性和具体性（“添加”、“修复”、“删除”、“重构”）

8) **运行最小相关验证**
   - 在继续之前运行存储库最快的有意义的检查（单元测试、lint 或构建）
   - 确保提交不会破坏现有功能

9) **同步 INDEX.md（仅限 AI Cortex 项目）**
   - 如果提交影响 `skills/` 目录：
     - 校验 `skills/INDEX.md` 已为新增 / 修改 / 删除技能同步更新
     - 校验 INDEX 项与目标 SKILL.md 的 description 一致
   - 如果提交影响 `rules/` / `specs/` / `protocols/` 目录：
     - 同步对应 `INDEX.md`

10) **重复下一次提交，直到工作树干净**

### 交互（互动）政策

- 询问用户是否想要单个或多个提交（默认：针对不相关的更改进行多个小提交）
- 确认提交风格需求（该技能需要常规提交）
- 询问任何特定于项目的规则：最大主题长度、所需范围等。
- 对于 AI Cortex 项目：确认是否同步对应 INDEX.md

## 输入与输出 (Input & Output)

### 输入（输入）要求

- 包含未提交更改的 git 存储库
- 用户意图：应该致力于哪些工作
- 可选：提交样式首选项、范围规则

### 产出（Output）合约

提供：

- 最终提交消息，包含类型、范围和清晰的描述
- 每次提交的简短摘要，解释发生了什么变化以及原因
- 用于暂存和审查的命令（至少：`git diff --cached`）
- 运行任何测试或验证命令
- 对于 AI Cortex 项目：确认对应 INDEX.md 已同步

## 限制（限制）

### 硬边界（Hard Boundaries）

- 在未审查分阶段更改的情况下不要提交（`git diff --cached`）
- 不要在一次提交中混合不相关的更改
- 不要编写模糊的提交消息（“修复内容”、“更新”、“WIP”）
- 如果测试或 linter 可用，请勿跳过验证步骤
- 不要提交秘密、令牌或敏感数据
- 对于 AI Cortex 项目：在未同步对应 INDEX.md 的情况下，请勿提交资产变更

### 技能边界 (Skill Boundaries)（避免重叠）

**不要做这些（其他技能可以处理它们）**：

- **现有提交的代码审查**：审查已提交的差异 → 使用“review-diff”技能
- **Git 历史重写**：变基、压缩、修改旧提交 → 直接使用 git rebase/amend 命令
- **合并冲突解决**：解决合并/变基期间的冲突 → 使用 git merge/rebase 工作流程
- **拉取请求创建**：创建 PR、请求审查、管理 PR 工作流程 → 使用特定于平台的 PR 工具
- **代码实施**：编写正在提交的代码更改→使用开发/实施技能

**何时停止并交接**：

- 用户问“你能审查这个提交吗？” → 对现有提交使用“review-diff”技能
- 用户问“你能推这个吗？” → 提交完成，移交推送 / PR 工作流
- 用户问“你可以重新调整这些提交的基础吗？” → 提交完成，移交给 git rebase 工作流程
- 提交并验证所有更改 → 技能完成，准备好推送或下一个任务

## 自检（Self-Check）

### 核心成功标准（必须满足所有标准）

- [ ] **已审查的更改**：在暂存之前运行“git diff”，在每次提交之前运行“git diff --cached”
- [ ] **逻辑范围**：每次提交仅包含相关更改；不相关的更改分为单独的提交
- [ ] **常规提交格式**：所有提交消息均遵循“类型（范围）：摘要”格式，正文清晰
- [ ] **质量验证**：运行适当的测试、lint 或构建命令并且所有检查均已通过
- [ ] **无敏感数据**：不包含秘密、令牌、调试代码或意外更改
- [ ] **INDEX 同步**（AI Cortex 项目）：技能 / 规则 / spec / protocol 改动时同步对应 INDEX.md

### 流程质量检查

- [ ] **提交前审查**：为 AI Cortex 项目运行“review-diff”技能，以检查是否存在意外更改、安全问题或重大更改
- [ ] **使用补丁暂存**：当更改混合在单个文件中时使用`git add -p`
- [ ] **提交边界清晰**：可以用 1-2 句话描述每个提交的目的
- [ ] **消息质量**：摘要是必要且具体的；正文解释了内容和原因（不是实现细节）
- [ ] **Breaking changes marked**: Used `!` or `BREAKING CHANGE:` footer if applicable
- [ ] **记录的命令**：列出用于暂存、审查和验证的命令

### 验收测试

**审阅者可以仅从提交消息中了解更改的内容和原因，而不阅读差异吗？**

如果否：提交消息不清楚。修改消息以解释内容和原因。

如果是：提交已准备好推送。

## 示例（示例）

### 示例 1：简单的功能添加

**场景**：向 utils.js 添加新函数

**命令**：

```bash
git status
git diff
# Review shows only the new function, no other changes
git add utils.js
git diff --cached
# Verify staged changes are correct
npm test
git commit -m "feat(utils): add formatDate helper function

Add formatDate to handle ISO 8601 date formatting consistently
across the application. Returns formatted string or null for
invalid inputs."

Output：

Commit:feat(utils)：添加 formatDate 辅助函数
Summary: Added a date formatting utility to centralize date handling logic
Command:git diff、git diff --cached、npm test

Example 2: Mixed changes that need to be split (edge case)

Scenario: Modified auth.js, fixed a bug and refactored, and updated tests

Command：

git status
git diff --stat
# Shows auth.js and auth.test.js changed

# Run review-diff first (AI Cortex)
# [review-diff identifies: bug fix in line 45, refactor in lines 100-150]

# Split into logical commits
# Commit 1: Bug fix only
git add -p auth.js
# Select only the bug fix hunk
git diff --cached
npm test
git commit -m "fix(auth): prevent null pointer in token validation

Check for null token before accessing properties to avoid
runtime errors when token is missing."

# Commit 2: Refactor
git add -p auth.js
# Select refactor hunks
git diff --cached
npm test
git commit -m "refactor(auth): extract token parsing to separate function

Move token parsing logic into parseAuthToken() for better
testability and reuse across auth module."

# Commit 3: Tests
git add auth.test.js
git diff --cached
npm test
git commit -m "test(auth): add tests for token validation edge cases

Cover null token, malformed token, and expired token scenarios."

Output：

Commit 1: "fix(auth): prevent null pointer in token validation" - fixed the crash when the token is null
Commit 2: "refactor(auth): extract token parsing into a separate function" - improved code organization
Commit 3: "test(auth): add tests for token validation edge cases" - increased test coverage
Command:git add -p、git diff --cached (×3)、npm test (×3)

Example 3: New AI Cortex skill (including INDEX sync)

Scenario: Add a new skill for the AI Cortex project analyze-logs

Command：

git status
# Shows: skills/analyze-logs/SKILL.md (new), skills/INDEX.md (modified)

git diff skills/INDEX.md
# 确认 INDEX 行新增并与 SKILL.md description 一致

git add skills/analyze-logs/ skills/INDEX.md
git diff --cached

git commit -m "feat(skills): add analyze-logs for log parsing

新增 analyze-logs 技能，支持按模式匹配解析应用日志并提取错误。
含常见日志格式的 3 个示例。

同步更新 skills/INDEX.md。"

Output：

Commit:feat(skills): add analyze-logs for log parsing
Summary: Add log analysis skill + INDEX sync
Command:git status、git diff --cached
INDEX sync: ✓ skills/INDEX.md already contains the new line

About this skill

Purpose

Core Objective

Scope boundaries (Scope Boundaries)

Use cases (Use Cases)

Behavior (Behavior)

Workflow (Checklist)

Example 2: Mixed changes that need to be split (edge case)

Example 3: New AI Cortex skill (including INDEX sync)