---
name: commit
description: "Plan logical commit units from staged changes only, suggest commit titles, return the plan only, and create commits only after user approval (e.g. \"ok\", \"please commit\"). Use when the user asks to commit changes, plan/split commits, create logical commits, or use a refs footer (e.g. refs: #42)."
---

# Commit Planning and Splitting

When the user wants to commit **staged** changes (optionally with a footer like `refs: #42`), plan logical units from the **staged set only**, suggest titles, and—**only after approval**—create commits in dependency order. Unstaged and untracked files are ignored.

## Plan only until approved

- **On the commit/plan command**: Return **only the plan** (units, titles, files, footer). Do **not** run `git add` or `git commit`. Stop after showing the plan.
- **Commits require approval**: Run `git add` / `git commit` **only** when the user has sent an **approval signal** in a later message.
- **Approval signals**: Treat as approval and then create the commits when the user says things like: "ok", "please commit", "go ahead", "approved", "yes", "do it", "execute", or equivalent.
- **Flow**: First reply = plan + "Reply with 'ok' or 'please commit' to create these commits." After the user replies with an approval signal, create the commits and report.

## When to Apply

- User asks to "commit", "plan commits", "split into logical commits", or "change the staged changes and plan the order of commits"
- User provides a message footer (e.g. `refs: #42`) to append to every commit
- User has **staged** changes and wants to commit only those (or split them into multiple commits)

## Workflow

### Phase A — Plan (run on commit/plan command; then stop)

### 1. Inspect staged changes only

- **Only consider staged files.** Ignore unstaged and untracked changes.
- Run `git status` and `git diff --cached --stat` (or `git diff --cached --name-only`) to see **staged** files only.
- If nothing is staged, report that and stop.

### 2. Unstage if re-grouping

- If the user asked to "change the current staged changes" or "plan the order" (re-group the same staged set into multiple commits), run `git reset HEAD` so you can later stage per unit. The plan still uses **only the files that were staged** before the reset.

### 3. Plan units and order

Group **only the staged files** into **commit units** in **dependency order** (things that other units depend on come first).

| Priority | Unit type | Typical files |
|----------|-----------|---------------|
| 1 | Schema / data layer | Database migrations, model definitions, type definitions |
| 2 | Shared / foundations | Library code, shared utilities, helpers |
| 3 | Configuration | Config files, environment setup, build config |
| 4 | API / backend logic | API routes, services, middleware |
| 5 | UI / frontend | Components, pages, styles, i18n/localization |
| 6 | Tests | Unit tests, integration tests, test fixtures |
| 7 | Docs / tooling | Documentation, CI config, scripts |

- One logical unit = one commit
- Order so that no commit depends on a later commit (e.g. shared lib before code that imports it; types before components that use them)
- **Co-locate UI with its dependencies**: Components and their directly related assets (styles, i18n keys, etc.) should be in the **same unit** as the page or feature that uses them
- If a commit deletes obsolete code, keep that deletion in the same unit as the replacement when reviewable

### 4. Suggest commit title per unit

- **Title**: Short, imperative, no period (e.g. "Add user profile schema and types", "Add tag filtering to project view")
- **Body** (optional): Bullet points for non-trivial units
- **Footer**: If the user gave one (e.g. `refs: #42`), use the same footer on every commit

### 5. Check docs-sync for runtime behavior changes

If the staged set changes operator-facing runtime behavior (runner queueing, Android lifecycle, import/export, dispatch), check whether matching doc updates in `docs/operators/`, `docs/maintainers/`, or `infra/` are part of the staged set. If they're missing, flag it in the plan — the repo requires docs to ship in the same change series.

### 6. Show the plan, then stop

Output:

- Numbered list of units with **suggested title** and **files**
- Footer line if provided
- Docs-sync flag if applicable
- **Stop.** Do not run Phase B. Add: "Reply with 'ok' or 'please commit' to create these commits."

Example:

```
| # | Suggested title                         | Files |
|---|-----------------------------------------|-------|
| 1 | Add tag schema and types                | db/migrations/..., src/types/tag.ts |
| 2 | Add tag API routes                      | src/api/tags/route.ts, src/api/items/tags/route.ts |
| 3 | Add tag UI to item detail page          | src/components/TagPicker.tsx, src/pages/items/detail.tsx |

Footer: refs: #42

Reply with 'ok' or 'please commit' to create these commits.
```

**Do not run `git add` or `git commit` in Phase A.**

---

### Phase B — Execute (run only after user sends an approval signal)

When the user replies with an approval signal ("ok", "please commit", "go ahead", "approved", "yes", "do it", "execute", or equivalent), then:

### 7. Verify before committing

Run `npm run verify` once for the staged set (repo rule: lint, TypeScript compile, dependency audit before committing).

- If it fails, run `npm run --workspace @skytest/web verify:explain` to attribute the failure to its checker, report the attribution, and **do not commit** — unless the user explicitly waives verification.
- Skip only if the user already ran verify in this session on the same staged set.

### 8. Create commits in order

For each unit, in order (each unit contains only files from the originally staged set):

1. `git add <files>` for that unit only (only files that were staged and assigned to this unit)
2. Build message:
   - First line: suggested title
   - Blank line
   - Optional body (bullets)
   - Blank line (if body present)
   - Footer line if user provided it (e.g. `refs: #42`)
3. `git commit -m "<title>" [-m "<body>" -m "<footer>"]`
   Use multiple `-m` for body and footer so they become separate paragraphs.

### 9. Report

- Print `git log --oneline -<N>` for the new commits
- Confirm working tree is clean or list what's left uncommitted

## Commit message format

```
<Suggested title>

[Optional body lines]

refs: #42
```

- **Title**: One line, imperative, ~50 chars or less
- **Body**: Optional; use for "why" or short bullet list
- **Footer**: Exact string the user gave; one line, same on every commit

## Guidelines

- **Staged only**: Plan and commit **only** from the set of files that are currently staged. Ignore unstaged and untracked changes. If nothing is staged, report that and stop.
- **Plan first, commit after approval**: On the commit/plan command, output only the plan and ask for approval. Run `git add` / `git commit` only when the user sends an approval signal.
- **One commit per unit**: Each unit is one logical change
- **Dependency order**: Foundations and shared code before features that use them
- **Co-locate UI with its dependencies**: Always commit components and their related assets (styles, i18n, etc.) in the **same unit** as the page/feature that uses them. Shared items used by more than one feature go in the unit for the **first** feature that uses them.
- **Same footer everywhere**: If the user specifies a footer, add it to every new commit in this run
- **Skip unrelated paths**: Do not commit untracked tooling files unless the user asks
- **Repo root**: Run `git` from the repository root
