Commit Skill

Create conventional commits with branch protection, semantic correlation, and user confirmation.

When to Use

After completing a task or logical unit of work
When the user requests a commit
After significant documentation updates
After implementing a feature or fix
When the user says they're "done", "finished editing", or wants to "wrap up"

Procedure

Step 1: Gather Changes

git status
git diff --stat
git diff --cached --stat

If there are no changes (nothing staged, modified, or untracked), inform the user and stop.

Step 2: Branch Safety Check (mandatory)

Detect the current branch and the default branch:

git symbolic-ref --short HEAD
git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo ""

If refs/remotes/origin/HEAD is not set, check whether main or master exists as fallback.

If on the default branch:

Warn the user: "You're committing directly to <default-branch>. Consider creating a feature branch."
Run Step 3 (Ticket Tracking) to check for an associated ticket before proposing a branch.
Detect the repo's branch naming convention by inspecting existing branches:
```
git branch -a --format='%(refname:short)'
```
Analyze naming patterns:
- Separator style: / vs - vs _
- Type prefixes: feat, fix, chore, docs, etc.
- Nested patterns: user/type/desc, type/desc
- Issue ID patterns: PROJ-123-desc
- Default to type/short-description if no clear pattern found
Propose a new branch name following the detected convention. If a ticket was found/created in Step 3, incorporate the ticket ID into the branch name (e.g., feat/PROJ-123-add-auth).
Ask user to: confirm the proposed name, suggest an alternative, or continue on the default branch

If the user chooses to create a branch, run:

git checkout -b <branch-name>

Step 3: Ticket Tracking (when on default branch or no ticket in branch name)

Detect whether the project uses a ticket tracking system and ensure changes are associated with a ticket.

Detection — check for ticket system indicators (in order):

GitHub/GitLab Issues — Check if remote is GitHub/GitLab:
```
git remote get-url origin
```
If GitHub: use gh issue list --limit 5 --state open to confirm issues are enabled. If GitLab: note that GitLab issues are likely available.
Jira — Look for Jira-style ticket IDs in existing branch names ([A-Z]+-\d+ pattern like PROJ-123). Check for .jira config or Jira URL references in the repo.
Linear — Check for Linear-style IDs in branches ([A-Z]+-\d+ with short prefixes like ENG-123). Check for linear references in the repo.
No ticket system detected — Skip this step entirely and proceed.

If a ticket system is detected:

Check if the current changes are already associated with a ticket:
- Parse the current branch name for a ticket ID
- If on default branch, there is no ticket association
If no ticket is associated, analyze the changes (from Step 1) to understand their nature, then:
- Warn: "This project uses [system] for tracking. No ticket is associated with these changes."
- Propose creating a ticket first:
  - Draft a ticket title and description based on the changes
  - For GitHub: offer to run gh issue create --title "..." --body "..."
  - For other systems: show the suggested title/description and ask user to create it manually
- Ask user to: create the ticket, provide an existing ticket ID, or skip (commit without ticket)
If user provides or creates a ticket, use the ticket ID when constructing the branch name in Step 2.

Step 4: Semantic Correlation (feature branches only)

Only when on a feature branch (not the default branch):

Parse the branch name into tokens (split on /, -, _)
Compare tokens against the nature of the changes (file paths, change type, scope)
If there is zero semantic overlap between branch name and changes, warn:

"Changes appear to be about X, but branch branch-name suggests Y. Continue?"
Wait for user confirmation before proceeding

Step 5: Analyze Changes

Identify:

Files modified, added, or deleted
Type of change (feat, fix, docs, refactor, style, test, chore)
Scope (which module/area affected)
Breaking changes (if any)

Step 6: Draft Commit Message

Use conventional commits format:

<type>(<scope>): <short description>

<body with details>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation only
refactor: Code change that neither fixes a bug nor adds a feature
style: Formatting, missing semicolons, etc.
test: Adding or updating tests
chore: Maintenance tasks, dependencies

If a ticket was associated in Step 3, include it in the footer (e.g., Closes #123 or Refs: PROJ-123).

Step 7: Show Diff and Confirm

Before committing, ALWAYS:

Show the staged diff (or unstaged diff if nothing is staged yet):

git diff --staged

Show the proposed commit message
Ask: "Ready to commit these changes? (yes/no)"
Wait for explicit user approval

Step 8: Execute Commit (only after approval)

Stage files — prefer specific files over git add -A:

git add <specific-files>
git commit -m "<message>"

Step 9: Verify

git log -1 --stat

Rules

NEVER push — Only commit locally, never run git push
ALWAYS confirm — Never commit without explicit user approval
Show diff first — User must see changes before approving
One logical unit — Each commit should represent one complete change
Conventional format — Always use type(scope): description format
Branch safety — Always check if on default branch before committing
Ticket alignment — If project has ticket tracking, ensure changes are associated with a ticket
Semantic alignment — Warn if changes don't match branch purpose
Proactive suggestion — After completing edits, suggest committing

Output Format

## Proposed Commit

**Branch:** feat/add-auth
**Type:** feat
**Scope:** auth
**Files:**
- src/auth/reset.ts (new)
- src/components/ResetForm.tsx (new)
- src/api/routes.ts (modified)

**Message:**
feat(auth): add password reset flow

- Add forgot password endpoint
- Implement email verification token
- Add password reset form component

Closes #123

**Diff summary:**
3 files changed, 245 insertions(+)

---
Ready to commit these changes?