contextual-commit

To write git commit messages that capture why code changed, use a structured format with a Conventional Commit subject and typed body lines for intent, decisions, rejections, constraints, and learnings. This preserves development reasoning directly alongside the diff.

A conventional commit format for documenting decisions pairs a standard subject line with scoped action lines in the body. These typed lines summarize intent, chosen approaches, discarded alternatives, and constraints to help future maintainers understand the rationale.

You document rejected alternatives and constraints in a git commit by adding typed, scoped action lines to the commit body. This structured approach explicitly records what was discarded and which limitations existed without fabricating missing context.

You can generate contextual commit messages for staged changes, but the skill advises caution with unstaged changes. It provides context-aware guidance on when to write action lines and warns against fabricating missing context when development reasoning is unavailable.

Your git diff does not explain intent because diffs only document what changed. To capture why decisions were made, you need structured commit messages with typed body lines that record intent, constraints, and discarded alternatives alongside the code changes.

You need contextual commit messages when finishing features, fixing bugs, or documenting multi-step decisions. They record user intent, chosen approaches, discarded alternatives, and important constraints so replaying or reflecting on the session is easier for future maintainers.