Commit Summary

Commit Summary

Generate accurate Conventional Commits from real git diffs.

Authorized Scope

Apply this engine only within the user's requested task and existing explicit authorization. Loading or delegating to it grants no additional authority. Preserve report-only restrictions and the caller's target, host, provider, and cost limits. Existing approval satisfies a gate only for the same actions and scope; obtain approval before expanding them. Forward these limits to delegates.

Contract

Inputs:

• Repository root
• Staged changes, unstaged changes, or approved paths to stage
• Optional commit type, scope, and breaking-change context

Outputs:

• Commit message candidate
• Logical commit grouping when changes are mixed
• Created commit hash after approval, if requested

Creates/Modifies:

• No changes in message-only mode
• May stage files and create commits after approval

External Side Effects:

• None unless another workflow pushes the commit later

Confirmation Required:

• Before staging files
• Before creating a commit
• Before amending or squashing existing commits

Delegates To:

• github-pr-publish when the commit should be pushed and opened as a PR
• git-safety when secrets or sensitive files appear in the diff

Workflow

1. Inspect repository state:

   git status -sb
   git log --oneline -5
   git diff --stat
   git diff --cached --stat
   

2. Determine whether changes are already staged:

   • If staged changes exist, generate the message from git diff --staged.
   • If nothing is staged, inspect unstaged changes and propose logical groups.
   • If unrelated changes are mixed, recommend separate commits.

3. Guard against unsafe commits:

   • Do not stage secrets, .env, credentials, private keys, local databases, build caches, or large generated artifacts.
   • If sensitive files appear, stop and delegate to git-safety.
   • Do not include unrelated formatting churn in a feature/fix commit unless it is required by the change.

4. Choose the Conventional Commit type:

   • feat: user-visible feature or capability
   • fix: bug fix
   • docs: documentation only
   • style: formatting only, no behavior change
   • refactor: code restructuring without behavior change
   • perf: performance improvement
   • test: tests only
   • build: build system, package manager, dependencies
   • ci: CI/CD workflow changes
   • chore: maintenance with no user-facing behavior
   • revert: revert a previous commit

5. Detect scope:

   • Prefer package, app, domain, or subsystem names already used in history.
   • Omit scope if it would be vague (misc, stuff, changes).

6. Detect breaking changes:

   • Public API contract changes
   • CLI flags or output changes
   • Database/schema migrations requiring user action
   • Removed config keys, env vars, routes, events, or exported symbols

   Format as type(scope)!: summary and include a BREAKING CHANGE: footer.

7. Generate the commit message:

   type(scope): imperative summary
   
   Optional body explaining why and any non-obvious implementation detail.
   
   Optional footer such as:
   BREAKING CHANGE: migration required because ...
   Refs: #123
   

8. If the user asked to commit, show the exact message and proceed within that authorization. Obtain approval only if the selected files or operation exceed the request:

   git add <approved-paths>
   git diff --staged --stat
   git commit -m "<subject>" -m "<body-or-footer>"
   

Quality Bar

• Subject is imperative and under 72 characters.
• Body explains why when the diff alone is not enough.
• Message does not overstate behavior.
• Commit contains one logical change.
• Verification commands are not placed in the commit message unless the repo convention asks for them.

Gotchas

• git add . can stage unintended files. If .gitignore does not exclude node_modules, .env*, or build artifacts, always prefer git add <specific-paths>. Verify with git diff --staged --stat before committing.
• Breaking-change footer is case-sensitive. The token must be exactly BREAKING CHANGE: (with a space, all caps) for tools like semantic-release and conventional-changelog to detect it. BREAKING-CHANGE: is not equivalent.
• Amended commits rewrite history. Never amend a commit that has already been pushed to a shared branch. If the commit exists on the remote, create a new fix commit instead.
• Co-authored-by trailers conflict with repo conventions. Some repos (including this project) explicitly forbid Co-Authored-By trailers. Check the repo's agent instruction file (AGENTS.md, CLAUDE.md, or equivalent) or recent commit history for the project convention before adding them.

Examples

• feat(auth): add password reset flow
• fix(api): handle null provider response
• ci(actions): restrict pull request token permissions
• refactor(utils): extract date formatting helper
• docs: update GitHub project board workflow

What Did I Get Done procedure

Read what-did-i-get-done procedure when compiling an activity summary over a requested date range. Apply the authorized scope and mode of this entry point to every step. Resolve other skills through this distribution’s active catalog; resolve resources relative to the installed skill directory.