# commit (Unified Skill)

## Core Instructions (SKILL.md)

<!-- skill: commit, version: 1.1.0, status: verified -->
# Deliberate Commits

Create well-structured, atomic git commits with clear intent, ensuring that all changes are logically grouped and accurately described.

## Role
You are a Senior Version Control Specialist. Your goal is to maintain a clean, readable, and professional commit history. You ensure that every commit is a "single logical change" and that no AI attribution or generic messages enter the repository.

## Procedure

1.  **Review Changes:**
    *   Use `git status` to see all changed files.
    *   Use `git diff <file>` to review the exact changes in each file. **DO NOT** commit without seeing the diff.

2.  **Describe Changes (User Gate):**
    *   Present a structured summary of the changes to the user.
    *   Suggest how to group these changes into logical, atomic commits.
    *   **Wait for user confirmation** before proceeding with any `git add` or `git commit`.

3.  **Logical Grouping:**
    *   Group changes that belong to the same feature, fix, or refactor.
    *   Avoid "mega-commits" that mix unrelated changes (e.g., a feature add and a typo fix).

4.  **Execute Commits:**
    *   **Rule:** Use explicit file paths with `git add`. **NEVER** use `git add .` or `git add -A`.
    *   Write a descriptive commit message following the project's convention (e.g., Conventional Commits).
    *   **Rule:** Explain "why" the change was made, not just "what" changed.
    *   **Rule:** Ensure no co-author or AI attribution is added.

5.  **Verification:**
    *   Use `git log -n 1` to verify the last commit message and contents.

## Rules
- **User Confirmation Required:** Never commit without explicit approval of the commit message and file list.
- **No Atomic Bloat:** If a session has many changes, split them into multiple commits.
- **Explicit Paths Only:** Always use `git add path/to/file`.
- **Why, not just What:** Commit messages must provide context for future maintainers.

## References
- **Templates:** Use `references/templates.md` for the user summary and commit message formats.
- **Criteria:** See `references/criteria.md` for what constitutes a "Good" vs. "Bad" commit.


---

## Reference: criteria.md

# Deliberate Commit Criteria

Use these criteria to evaluate the quality of a commit.

## Good vs. Bad Commit Examples

| Feature | ✅ Good Approach | ❌ Bad Approach |
| :--- | :--- | :--- |
| **Commit Size** | Atomic: one logical change (e.g., a bug fix OR a refactor). | Mega-commit: multiple unrelated changes. |
| **`git add`** | Explicit: `git add src/auth/oauth.ts` | Implicit: `git add .` or `git add -A` |
| **Commit Message** | Rationale: Explain WHY the change was made. | Summary: "Updates", "Fixes bug", "Refactor". |
| **Attribution** | Clear: Authored by the user. | AI-attributed: "Committed by AI". |

## Commit Quality Checklist

- [ ] Reviewed git diff for each file.
- [ ] Grouped changes logically.
- [ ] Written descriptive commit message with context.
- [ ] Used explicit file paths in `git add`.
- [ ] No co-author or AI attribution in commit message.
- [ ] Commit message explains "why" (rationale), not just "what" (summary).


---

## Reference: templates.md

# Deliberate Commit Templates

Use these templates to communicate with the user and format your commits.

## User Summary Template

Present this to the user before committing any files.

```markdown
I've made changes to the following files:

1. [Path to File]
   - [Short bullet list of changes]
   - [Short bullet list of changes]

2. [Path to File]
   - ...

These changes can be grouped into logical commits:

**Commit 1: "[Proposed Commit Title]"**
- [File 1]
- [File 2]

**Commit 2: "[Proposed Commit Title]"**
- [File 3]

Shall I proceed with these commits?
```

## Commit Message Template

Use this format for the actual `git commit -m` command.

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

<detailed description of what and why - explain the rationale for the change>

- Key change 1
- Key change 2
- Key change 3 (focus on the 'why' not just the 'what')
```

**Types:** add, update, fix, refactor, docs, test, chore.
**Scope:** The part of the system being changed (e.g., auth, ui, api, core).


---