--- name: git-commit-standards description: "Use when creating git commits or pull requests. Enforces conventional commit format and atomic change principles. Verified on Git 2.30+" author: "Claude Code Learning Flywheel Team" allowed-tools: ["Bash", "Read", "Grep"] version: 1.2.0 last_verified: "2025-12-31" tags: ["git", "workflow", "team-standards"] related-skills: [] verification: test_script: "tests/skills/test_git_commit_standards.py" command: "python3 tests/skills/test_git_commit_standards.py" frequency: "on-change" --- # Git Commit Standards ## 1. Context & Scope This skill defines the team's git commit and pull request standards, ensuring consistent history and easy rollback/debugging. **Trigger Conditions:** - When user asks to "commit changes" - When user asks to "create a pull request" - Before running `git commit` or `gh pr create` **Environment:** - Git: 2.30+ - GitHub CLI (optional): 2.20+ - Pre-commit hooks: Enabled (validates format) **Out of Scope:** - Branching strategy (see `git-workflow` skill) - Code review guidelines (see `code-review-process` skill) --- ## 2. Negative Knowledge (Read First) *Common mistakes that have caused problems in the past.* ### Failed Attempts Table | # | Attempted Strategy | Error/Symptom | Root Cause | Fix/Prevention | |---|-------------------|---------------|------------|----------------| | 1 | Used generic "fix bug" messages | Unable to identify which commit caused production issue | No context about WHAT was fixed | Use format: `fix(component): specific issue description` | | 2 | Committed multiple unrelated changes together | Had to revert feature A but it also reverted unrelated fix B | Atomic commit principle violated | One logical change per commit, use `git add -p` | | 3 | Used past tense "Added feature X" | Inconsistent with team convention, hard to scan history | Team uses imperative mood | Use "Add feature X" not "Added feature X" | | 4 | Forgot to reference issue number | PM couldn't track which commits belonged to which feature | No traceability to project management | Add `Refs: #123` footer to all commits | ### Common Pitfalls - **❌ Don't:** Write vague messages like "updates", "fixes", "changes" - **Why it fails:** 6 months later, impossible to understand intent - **✅ Do instead:** "fix(auth): prevent token expiry race condition" - **❌ Don't:** Commit WIP code directly to main branch - **Why it fails:** Breaks CI/CD, blocks other developers - **✅ Do instead:** Use feature branches, squash before merge - **❌ Don't:** Include passwords, API keys, or secrets in commits - **Why it fails:** Git history is permanent, secrets are exposed forever - **✅ Do instead:** Use .env files (gitignored), run `scripts/check_secrets.sh` pre-commit --- ## 3. Verified Procedure > **IMPORTANT:** This skill is a "Tool Wrapper" - DO NOT analyze commit message format yourself. > Use the deterministic validation script for accuracy and speed. ### Prerequisites Check ```bash # Run automated pre-commit validator python scripts/validate_commit_msg.py --check-setup # Expected output: "✅ Git hooks installed, conventional commit format enabled" ``` ### Step 1: Stage Changes Atomically **Description:** Group related changes together, exclude unrelated changes ```bash # Review what changed git status git diff # Stage specific files (atomic changes) git add path/to/changed/file.py # OR stage interactively (parts of files) git add -p path/to/file.py # Press 'y' to stage hunks that belong together # Press 'n' to skip unrelated changes ``` **Validation:** ```bash # Verify only intended changes are staged git diff --cached # Expected: Only logically related changes visible ``` ### Step 2: Write Conventional Commit Message **Description:** Format message according to team standards **Format:** ``` ():