Commit

Create conventional commit messages that explain the why, not the what.

The commit message helps:

Workflow

git diff --cached

If nothing is staged, stop and tell the user to stage changes first.

Extract scopes already used in the project to stay consistent:

git log --oneline --no-merges | sed -n 's/^[^ ]* [a-z]*(\([^)]*\)).*/\1/p' | sort | uniq -c | sort -rn

Use one of these scopes if it fits. Only invent a new scope if none matches.

Identify:

If needed, use Read to explore touched files for better architectural understanding.

Skip questions if the why is obvious:

Bug fix with explicit error message
Typo / formatting
Adding tests for existing code
Rename with clear reason in the code
The conversation already provides full context (e.g. you just helped implement the change)

Ask 1-2 questions if you need to clarify:

Questions must be specific to the diff — mention what you see and ask why:

"You're migrating from bash to Node.js — was it for performance, maintainability, something else?"
"You're adding retry with backoff on API X — what was the issue in prod?"
"You're replacing moment.js with date-fns — bundle size problem?"

Never ask vague questions like "Why this change?" or "What was the problem?".

type(scope): short description

One or two paragraphs explaining the context and motivation.
Each paragraph is between 125 and 250 characters.

Answer: What problem? Why now? Why this approach?

Forbidden patterns (the diff already shows the what):

Do not rely on the LLM to respect line length. Wrap the body (not the title) at 80 characters using fmt:

echo "<body>" | fmt -w 80

Always use a HEREDOC to avoid escaping issues:

git commit -F - << 'EOF'
type(scope): description

Wrapped body paragraph.
EOF