git

<skill id="git"> <purpose> Git is the safety net. Every commit is a checkpoint you can return to. Atomic commits. Descriptive messages. Feature branches for tier 2+. Never commit broken code to main. </purpose> <prerequisite> Check git status before any work. Note branch, clean/dirty, remote sync. </prerequisite> <reference> Skill-specific: skills/git/reference/git-research.md </reference>

<core_principles>

1. ATOMIC COMMITS: One logical change per commit. Never mix feature + refactor + fix.
2. CONVENTIONAL FORMAT: {type}({scope}): {description} - feat, fix, refactor, docs, test, chore
3. IMPERATIVE MOOD: "add feature" not "added feature" or "adding feature"
4. BRANCH PER FEATURE: Tier 2+ work gets feature/{name} or fix/{name} branch
5. COMMIT OFTEN: Every working state gets a commit. Max 30 min between commits. </core_principles>

<branch_strategy>

• main: Always deployable. Never commit directly for tier 2+.
• feature/{name}: New functionality
• fix/{name}: Bug fixes
• refactor/{name}: Code restructuring

Profile-gated workflow: local: direct to main OK, branches optional github: feature branches for tier 2+, PRs optional github-oss: feature branches always, PRs REQUIRED before merge github-production: feature branches always, PRs REQUIRED, review REQUIRED </branch_strategy>

<commit_messages> Good:

• feat: add user authentication endpoint
• fix: resolve race condition in cache invalidation
• refactor: extract validation logic to separate module

Bad:

• fixed stuff
• WIP
• updates </commit_messages>

<anti_patterns>

• Committing to main directly for multi-file changes
• "WIP" commits that never get squashed
• Mixing unrelated changes in one commit
• Force pushing to shared branches
• Skipping commit messages
• Including AI tool attribution in commit messages (Co-Authored-By, "Generated with Claude Code", etc.) </anti_patterns>

<!-- Updated 2026-03-30: Claude Code best practices, Anthropic prompt engineering guide -->

<agentic_git_discipline> Agentic workflows introduce new git failure modes. Mitigate them:

Pre-task snapshot: Before any agent starts work, record the HEAD commit SHA in AgentDB. If the task needs rollback, you know exactly where to return.

# Record before agent work
git rev-parse HEAD  # save this to AgentDB

# Rollback if needed
git reset --hard <saved-sha>

Dirty-state check: If git status shows uncommitted changes at task start, stop. Prior agent left state. Commit, stash, or discard before proceeding — never silently overwrite.

Branch-per-agent for tier 2+: Each agent working on distinct features gets its own branch. Merging branches (not rebasing) preserves intent and makes conflicts explicit.

Squash before merge: Agent commits tend to be fine-grained and mechanical. Squash to one meaningful commit per feature before merging to main. Message should describe the feature, not the implementation steps.

No force-push to shared branches: An agent force-pushing destroys another agent's or human's commits silently. Use --force-with-lease only, never bare --force. </agentic_git_discipline>

<!-- Updated 2026-04-04: AI code review best practices, https://collinwilkins.com/articles/ai-code-review-best-practices-approaches-tools.html -->

<diff_sizing> Diff size is the single biggest lever for AI code review quality:

• 50-200 lines: optimal — AI catches logic errors, security issues, edge cases
• 200-500 lines: acceptable — AI catches obvious issues, misses subtle interactions
• 500+ lines: degraded — AI overwhelmed, misses important context, feedback generic
• 1000+ lines: near-useless — context saturation, review becomes superficial

Rule: if a diff exceeds 500 lines, split the PR before requesting AI review.

AI review before human review: Run AI review (~90 seconds) before requesting human review. Developer fixes cheap issues first, humans see a cleaner diff and focus on intent and design. Sequence: AI review → fix → human review. Not parallel. </diff_sizing>

</skill>