Conventional Commits
Turn uncommitted changes into a series of atomic, conventional commits
ordered for review, using Hedgehog's commit vocabulary (hedgehog-loop).
When this runs
Normally the Loop commits one step at a time as it goes — schema, then
contract, then repository, and so on — so there's nothing to clean up.
This skill is for when that didn't happen cleanly:
- A Correction Protocol fix touched an upstream step and several
fast-forwarded dependents in one working-tree pass, needing to land as
separate commits (one per step, per the Correction Protocol's own
rule).
- Work happened outside the Loop's discipline (exploratory changes, a
session that didn't commit as it went) and needs reconstructing into
the step-shaped history Hedgehog expects.
What "atomic" means here
One commit = one build step, where that applies (one schema, one
contract, one repository, etc.) — not one file. A single step may span
several files (a Drizzle schema + its migration, a service + its test).
If work doesn't map onto a build step (tooling, config, docs), fall back
to normal atomic-commit judgment: one logical change per commit.
If a hunk can be removed without breaking the others in its commit, it
belongs in its own commit.
Steps
1. Survey the working tree
Run in parallel:
git status (no -uall)
git diff (unstaged)
git diff --staged (anything pre-staged)
git log -10 --oneline to confirm the project's existing commit style
- Run
hedgehog status for which steps/modules are in flight
Read every changed file's diff fully before grouping — you cannot group
changes you haven't read.
2. Group hunks into logical commits
For each hunk, ask: which build step is this part of, for which module?
Group by step first, module second. A hunk in the orders schema and a
hunk in the orders repository are different commits even though both
are "orders" — different steps.
Group together: a schema change with its Drizzle migration; a service
with its unit test (tests land with the step they test, not a trailing
"add tests" commit); config/tooling changes (lefthook, eslint boundaries,
env schema) isolated from any domain step.
Keep separate: different build steps, even for the same module; a
Correction Protocol fix from the unrelated new work it landed alongside;
different modules' changes.
3. Order the commits for review
- Build-sequence order. Schema before contract, contract before
repository, repository before service, service before controller —
the same dependency order the Loop builds in.
- Upstream fix before its fast-forwarded dependents, for a
Correction Protocol cleanup — the fix commit needs to make sense
before the commits that changed because of it.
- Mechanical before novel. Config, generated files, renames first.
4. Propose the plan, then execute
Output the plan as a numbered list using Hedgehog's commit format before
committing anything:
feat(orders): schema
feat(orders): contract
fix(orders): correct FK-by-ID reference dropped in schema step
feat(orders): repository
Then execute each commit:
- Stage exactly the hunks for that commit. Use
git add <path> for a
whole file; for partial-file staging, write a patch and
git apply --cached it.
- Verify with
git diff --staged that only the intended hunks are
staged.
- Commit with the conventional message.
- Verify clean state with
git status before the next commit.
If a pre-commit hook (lefthook: typecheck/lint/test) fails: fix the
issue, re-stage, create a NEW commit — a commit that fails the gate did
not happen, so amending would rewrite the wrong thing (see Hard rules).
5. Commit format
<type>(<scope>): <subject>
- type:
feat for build steps; also fix, chore, docs,
refactor, style, test, build, ci, perf as needed.
- scope: the domain module name (
orders, users, ...) for a build
step, or an infra area (db, contracts, auth, hooks, api,
worker, web, mobile, config) for bootstrap/tooling commits.
- subject for a build step: the step name itself —
schema,
contract, repository, service, api, queue, hooks,
screen-web — matching hedgehog-loop's step tables exactly. For
non-step commits, imperative and lowercase, under ~70 chars.
- Body only when the why is non-obvious — for a Correction Protocol
commit, the body is the explanation ("the commit messages are the
explanation").
6. Hard rules
- Never push. Commits only.
- Never
git add -A or git add . — specific paths or hunks only.
- Never amend. Always new commits.
- Never
--no-verify — a failing gate means the step isn't done, not
that the gate is wrong.
- Never commit files that look like secrets (
.env, credentials.*,
*.pem). Flag and skip.
- Never include
Co-Authored-By: Claude or any AI attribution trailer.
- Working tree clean: say so and stop.
- Changes are genuinely one step: one commit is correct, don't split for
its own sake.
7. When you're unsure how to split
If two hunks could plausibly belong to the same step or different steps,
ask the user once with the proposed plan and an alternative — the full
plan, not per-hunk.
1---2name: conventional-commits3description: Use when uncommitted changes need to be split into atomic, conventional commits ordered for review. Triggers on "commit this", "make commits", "clean up commits", "commit the changes". In Hedgehog, each Loop step is already meant to be its own commit — this skill matters most when a Correction Protocol fast-forward touches several steps at once and those fixes need splitting back into per-step commits.4metadata:5 source: https://skillmd.com/skills/skyf0xx/conventional-commits6---78# Conventional Commits910Turn uncommitted changes into a series of atomic, conventional commits11ordered for review, using Hedgehog's commit vocabulary (`hedgehog-loop`).1213## When this runs1415Normally the Loop commits one step at a time as it goes — schema, then16contract, then repository, and so on — so there's nothing to clean up.17This skill is for when that didn't happen cleanly:1819- A **Correction Protocol** fix touched an upstream step and several20 fast-forwarded dependents in one working-tree pass, needing to land as21 separate commits (one per step, per the Correction Protocol's own22 rule).23- Work happened outside the Loop's discipline (exploratory changes, a24 session that didn't commit as it went) and needs reconstructing into25 the step-shaped history Hedgehog expects.2627## What "atomic" means here2829One commit = one build step, where that applies (one schema, one30contract, one repository, etc.) — not one file. A single step may span31several files (a Drizzle schema + its migration, a service + its test).32If work doesn't map onto a build step (tooling, config, docs), fall back33to normal atomic-commit judgment: one logical change per commit.3435If a hunk can be removed without breaking the others in its commit, it36belongs in its own commit.3738## Steps3940### 1. Survey the working tree4142Run in parallel:43- `git status` (no `-uall`)44- `git diff` (unstaged)45- `git diff --staged` (anything pre-staged)46- `git log -10 --oneline` to confirm the project's existing commit style47- Run `hedgehog status` for which steps/modules are in flight4849Read every changed file's diff fully before grouping — you cannot group50changes you haven't read.5152### 2. Group hunks into logical commits5354For each hunk, ask: *which build step is this part of, for which module?*55Group by step first, module second. A hunk in the `orders` schema and a56hunk in the `orders` repository are different commits even though both57are "orders" — different steps.5859Group together: a schema change with its Drizzle migration; a service60with its unit test (tests land with the step they test, not a trailing61"add tests" commit); config/tooling changes (lefthook, eslint boundaries,62env schema) isolated from any domain step.6364Keep separate: different build steps, even for the same module; a65Correction Protocol fix from the unrelated new work it landed alongside;66different modules' changes.6768### 3. Order the commits for review69701. **Build-sequence order.** Schema before contract, contract before71 repository, repository before service, service before controller —72 the same dependency order the Loop builds in.732. **Upstream fix before its fast-forwarded dependents**, for a74 Correction Protocol cleanup — the fix commit needs to make sense75 before the commits that changed because of it.763. **Mechanical before novel.** Config, generated files, renames first.7778### 4. Propose the plan, then execute7980Output the plan as a numbered list using Hedgehog's commit format before81committing anything:8283```84feat(orders): schema85feat(orders): contract86fix(orders): correct FK-by-ID reference dropped in schema step87feat(orders): repository88```8990Then execute each commit:91- Stage exactly the hunks for that commit. Use `git add <path>` for a92 whole file; for partial-file staging, write a patch and93 `git apply --cached` it.94- Verify with `git diff --staged` that only the intended hunks are95 staged.96- Commit with the conventional message.97- Verify clean state with `git status` before the next commit.9899If a pre-commit hook (lefthook: typecheck/lint/test) fails: fix the100issue, re-stage, create a NEW commit — a commit that fails the gate did101not happen, so amending would rewrite the wrong thing (see Hard rules).102103### 5. Commit format104105```106<type>(<scope>): <subject>107```108109- **type**: `feat` for build steps; also `fix`, `chore`, `docs`,110 `refactor`, `style`, `test`, `build`, `ci`, `perf` as needed.111- **scope**: the domain module name (`orders`, `users`, ...) for a build112 step, or an infra area (`db`, `contracts`, `auth`, `hooks`, `api`,113 `worker`, `web`, `mobile`, `config`) for bootstrap/tooling commits.114- **subject** for a build step: the step name itself — `schema`,115 `contract`, `repository`, `service`, `api`, `queue`, `hooks`,116 `screen-web` — matching `hedgehog-loop`'s step tables exactly. For117 non-step commits, imperative and lowercase, under ~70 chars.118- Body only when the *why* is non-obvious — for a Correction Protocol119 commit, the body is the explanation ("the commit messages are the120 explanation").121122### 6. Hard rules123124- Never push. Commits only.125- Never `git add -A` or `git add .` — specific paths or hunks only.126- Never amend. Always new commits.127- Never `--no-verify` — a failing gate means the step isn't done, not128 that the gate is wrong.129- Never commit files that look like secrets (`.env`, `credentials.*`,130 `*.pem`). Flag and skip.131- Never include `Co-Authored-By: Claude` or any AI attribution trailer.132- Working tree clean: say so and stop.133- Changes are genuinely one step: one commit is correct, don't split for134 its own sake.135136### 7. When you're unsure how to split137138If two hunks could plausibly belong to the same step or different steps,139ask the user once with the proposed plan and an alternative — the full140plan, not per-hunk.