Commit Skill

Core philosophy

Every commit must:

• Represent one intent
• Touch one file (unless explicitly allowed)
• Use a controlled verb
• Include explicit scope in brackets
• Be short, readable, and reviewable

Commits are documentation, not narration.

---

Commit message format (MANDATORY)

<verb>(<scope>): <short message>

Examples

• refactor(main): simplify request validation
• fix(auth): handle missing token edge case
• chore(logging): remove unused formatter
• docs(api): clarify pagination params

---

Allowed verbs (STRICT SET)

Only use one of the following:

• refactor -> structural change, no behavior change
• fix -> bug fix
• feat -> new user-facing capability
• chore -> tooling, cleanup, non-prod logic
• docs -> documentation only
• test -> tests only
• perf -> performance improvement
• style -> formatting, lint-only changes

If unsure -> default to refactor.

---

Scope rules ((<scope>))

The scope MUST be one of:

• module name e.g but not strictly (auth, users, payments)
• layer (api, service, schema, db)
• branch name (main, dev)
• file stem (settings, config, router)

Avoid vague scopes:

• misc
• stuff
• update

---

File-by-file enforcement

Default rule

One commit = one file

If multiple files are staged:

1. Stop
2. Unstage everything
3. Stage only one file
4. Commit
5. Repeat

Multi-file commits are allowed only if:

• files are inseparable (e.g. interface + impl)
• explicitly requested by the user

---

Workflow to follow (ALWAYS)

Step 1: Inspect changes

git status
git diff

Step 2: Select ONE file

git add path/to/file.py

Step 3: Propose commit message

Before committing:

• State the verb
• State the scope
• State the intent in <= 8 words

Step 4: Stage and commit (MANDATORY)

Stage exactly one file and commit it. Do not wait for approval unless the user explicitly asks to review first.

git add path/to/file.py
git commit -m "refactor(main): extract config loading"

Step 5: Repeat for next file

---

Refactor-specific rules (IMPORTANT)

When using refactor:

• Do NOT claim behavior changes
• Do NOT mention performance unless measured
• Focus on structure, clarity, boundaries

Good:

• refactor(api): extract request parsing Bad:
• refactor(api): fix bug and improve speed

---

How to assist the user (assistant behavior)

When this skill is active:

• NEVER suggest bulk commits by default
• ALWAYS ask or infer which single file is being committed
• ALWAYS generate the commit message before committing
• ALWAYS stage the file and perform the commit without waiting for approval, unless the user requests review
• If message is vague -> rewrite it
• If scope is unclear -> infer from file path

If multiple files are changed:

• Propose one commit per file, sequentially

---

Anti-patterns to block

Do NOT allow:

• "updated stuff"
• "minor changes"
• "fixes"
• commits without scope
• commits with more than one verb
• commits that mix refactor + fix

If detected -> stop and correct.

---

Example interaction

User: I refactored auth/deps.py

Assistant: Suggested commit: refactor(auth): isolate dependency resolution

User: Commit it

Assistant:

• Ensures only auth/deps.py is staged
• Commits with the approved message

---

Mental model

If this commit appeared alone in a pull request, would a reviewer immediately understand why it exists from the message?

If not -> rewrite.

---

Why this is powerful (quick coaching insight)

You are doing three high-leverage things here:

1. Reducing cognitive debt
2. Increasing review velocity
3. Signaling seniority silently