Commit Best Practices

This skill ensures your commits are logical, atomic, and structured perfectly. A commit is not just a save point; it is a communication tool for future developers (and AI agents) to understand the history and intent of a codebase.

🧠 Mindset & Philosophy

• Communicate Intent, Not Just Mechanics: The code already tells us what changed. The commit message must tell us why it changed.
• Atomic Commits: A commit should do exactly one thing. If a commit fixes a bug AND adds a feature, it should be two commits. This makes reverting, rebasing, and reviewing significantly easier.
• The Audience is the Future: Write commit messages as if you are explaining the change to someone debugging an issue at 3 AM six months from now.

🚫 Anti-Patterns

• Avoid describing what the code does in the body. Do not write "I added an if statement on line 42." Write "Added a null check to prevent a crash when the user profile is missing."
• Avoid using emojis in commit messages. This ensures compatibility across all terminal environments and maintains a uniform, professional, greppable git history.
• Avoid using vague subjects. "Fix bug", "Update files", "WIP" are useless. They provide zero context when looking at git log --oneline.
• Avoid bundling unrelated changes. If you noticed a typo in README.md while working on the auth system, commit the typo fix separately from the auth feature.
• Avoid committing without reviewing your own diff first. Always run git diff --cached or review the staged changes to ensure no debugging statements (console.log, print) or secrets are accidentally included.

📝 Procedures & Workflow