commit（提交）

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:

1. Warn the user: "You're committing directly to <default-branch>. Consider creating a feature branch."
2. Run Step 3 (Ticket Tracking) to check for an associated ticket before proposing a branch.
3. Detect the repo's branch naming convention by inspecting existing branches: git branch -a --format='%(refname:short)'
4. 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

1. 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).
2. 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):

1. 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.
2. 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.
3. Linear — Check for Linear-style IDs in branches ([A-Z]+-\d+ with short prefixes like ENG-123). Check for linear references in the repo.
4. No ticket system detected — Skip this step entirely and proceed.

If a ticket system is detected:

1. 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

1. 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)

1. 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):

1. Parse the branch name into tokens (split on /, -, _)
2. Compare tokens against the nature of the changes (file paths, change type, scope)
3. 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?"
4. 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:

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

git diff --staged

1. Show the proposed commit message
2. Ask: "Ready to commit these changes? (yes/no)"
3. 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

1. NEVER push — Only commit locally, never run git push
2. ALWAYS confirm — Never commit without explicit user approval
3. Show diff first — User must see changes before approving
4. One logical unit — Each commit should represent one complete change
5. Conventional format — Always use type(scope): description format
6. Branch safety — Always check if on default branch before committing
7. Ticket alignment — If project has ticket tracking, ensure changes are associated with a ticket
8. Semantic alignment — Warn if changes don't match branch purpose
9. 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?