git-commit

name	git-commit
description	Complete git commit workflow including pre-commit review, staging, message generation, and verification. Use when creating commits or preparing changes for commit.

Git Commit Workflow

Prerequisites

Check what changed to determine review/test needs:

git diff --name-only
git diff --cached --name-only

File Types Changed	Run Tests
C++ (.cpp, .h)	Yes
Python (.py)	Yes
Build system (CMakeLists.txt)	Yes
Docs only (.md)	Skip
Config only (.gitignore, .json)	Skip

Pre-Commit Testing

When tests are needed, follow the testing skill for the full strategy: see .claude/skills/testing/SKILL.md — "Pre-Commit Testing Strategy" section.

Stage Changes

Stage related changes together, never stage build artifacts (build/, *.o, outputs/).

git add path/to/file1.cpp path/to/file2.h
git diff --staged  # Review before committing

Commit Message Format

Subject Line

Type: concise description (under 72 characters, imperative mood, no period)

Types:

Type	Usage
Add	new feature or file
Fix	bug fix
Update	enhancement to existing feature
Refactor	restructuring without behavior change
Support	tooling, profiling, CI infrastructure
Sim	simulation-specific changes
CI	CI/CD pipeline changes

Body (required for multi-file changes)

Separate from subject by a blank line. Explain what changed and why. Use bullet points for multiple items. Wrap at 72 characters.

When to include a body:

• Changes touch 3+ files
• The "why" is not obvious from the subject alone
• There are trade-offs, side effects, or migration notes

Good examples:

Add: paged attention kernel with batch support

- Implement batch-level KV-cache slot allocation in orchestration
- Add softmax_prepare kernel for cross-batch score normalization
- Golden test covers batch_size=4 with variable sequence lengths

Fix: resolve cross-pipeline race in softmax_prepare

PIPE_V and PIPE_S barriers were missing between score accumulation
and softmax normalization, causing sporadic mismatches on hardware
when AICore pipelines overlapped.

Support: restructure .ai-instructions into .claude/skills and rules

- Move coding conventions to .claude/rules/ (auto-loaded)
- Move git-commit and testing workflows to .claude/skills/ (on-demand)
- Rename test-sim/test-device commands to test-example-* for clarity
- Add test-runtime-* commands for runtime-scoped testing
- Add pre-commit testing strategy with npu-smi and nproc detection

Simple changes (body optional):

Fix: typo in vector_example golden.py

Bad examples:

x  Added new feature.              # Past tense, has period
x  fix bug                         # Lowercase type
x  WIP                             # Not descriptive
x  Chore: update gitignore         # Invalid type
x  Support: update stuff           # Vague, no body for multi-file change

Co-Author Policy

Never add AI co-author lines. Commits reflect human authorship only.

Exception — squash with multiple human authors: When squashing commits from different people (e.g., updating someone else's PR), preserve all other human authors with Co-authored-by: trailers — one per author. This is passed in by commit-and-push when it detects other authors before squashing.

Fix: resolve cross-pipeline race in softmax_prepare

Co-authored-by: Alice <[e-mail]>
Co-authored-by: Bob <[e-mail]>

Pre-Commit Hook Policy

All pre-commit hook errors must be fixed before committing — including pre-existing ones. When a hook (check-headers, cpplint, markdownlint, clang-format, etc.) reports errors in files touched by your commit, fix every error even if it existed before your changes. The principle: any file you modify must leave the commit with zero hook violations.

• Never use SKIP=... or --no-verify to bypass failing hooks
• clang-format / markdownlint: if hooks auto-fix files, re-stage and re-commit
• check-headers: add missing copyright headers to files that lack them
• cpplint: fix all reported issues (copyright, include_subdir NOLINT, casts, etc.)
• If a fix is non-trivial (e.g., large refactor to eliminate C-style casts), add NOLINT comments only as a last resort and document why

Post-Commit Verification

git log -1              # Check message
git show HEAD --stat    # Verify staged files

Fix unpushed commits only:

git commit --amend -m "Corrected message"

Checklist

• Only relevant files staged (no build artifacts)
• Tests passed (if code changed) or skipped (if docs/config only)
• Message format: Type: description (under 72 chars, imperative, no period)
• Body included for multi-file changes (what + why)
• No AI co-authors