hitl

Pipeline: spec-it → slice-it → build-it / hitl → ship-it.

The user just took the wheel. After a stretch of agent-driven commits, they made their own commits to nudge the codebase toward what they actually want. Now they're handing it back. Your job: read what they changed, treat it as the new source of truth, and finish the work around it.

Mental model

The user's HITL commits are the spec. They corrected something — direction, taste, naming, structure, behavior. That correction is now load-bearing.
The agent commits before HITL are drafts. They are negotiable. If they conflict with the user's edits, the user's edits win.
Your job is to make the whole branch coherent with the HITL commits as anchors. Not to re-do the work, not to re-litigate it.

Phase 1 — Find the HITL commits

Search the branch's commit history (since it diverged from the base branch) for HITL markers. Match liberally — case-insensitive, in subject or body:

HITL, hitl, HITL phase, HITL: …, (hitl), [hitl], human-in-the-loop, etc.

Commands:

git merge-base HEAD origin/main          # or the actual base branch
git log <base>..HEAD --oneline
git log <base>..HEAD --grep='hitl' -i    # also try '--grep=human-in-the-loop' -i

If you find zero HITL commits: stop and ask the user which commits they consider the human-edited ones. Do not guess from diffs alone.

If you find some: list them back to the user in one line each (<sha> <subject>) so they can confirm before you proceed. Keep this brief.

Phase 2 — Read the HITL commits in full

For each HITL commit:

git show <sha> — read the full diff and the message.
Note what changed and why (the message often hints at intent).
Note what is now frozen: file regions, naming, signatures, structure, behavior choices.

Build a mental list of frozen anchors. These are the constraints for the rest of the work.

Phase 3 — Diagnose the gap

Compare:

The state of the branch as of the last HITL commit (the user's intended direction).
The state of the branch at HEAD (which may equal the last HITL commit, or have agent commits after it).
What the original task/plan was trying to achieve (read recent non-HITL commit messages and any plan/PRD context the conversation provides).

Identify what's left to do so the branch lands in a coherent, finished state that respects the HITL anchors. Examples of typical gaps:

The user renamed a concept; call sites elsewhere still use the old name.
The user simplified a component; downstream code still expects the old API.
The user removed a layer; tests or types still reference it.
The user reshaped data; serialization, validation, or storage didn't follow.
The user's edits exposed an inconsistency in a sibling module that was never updated.

Phase 4 — The freeze rule

HITL commits are frozen. You may not revert, undo, or "fix" what the user did inside them, even if you think it's wrong, suboptimal, or inconsistent.

The only exception is a major technical blocker: the HITL change makes something genuinely impossible (won't compile, breaks an invariant the runtime requires, contradicts another HITL change, etc.). In that case:

Stop. Do not modify the HITL commit's content.
Surface the blocker to the user with a precise description of what conflicts and why.
Propose options. Let the user choose.

Taste, style, and "I'd have done it differently" are not blockers. Adapt the surrounding code to fit.

Phase 5 — Stitch

Make the rest of the codebase coherent with the frozen anchors. Be proactive:

Update call sites, types, tests, fixtures, translations, and docs to match the HITL shape.
Drop or rewrite agent-era code that is now redundant or contradicted.
If an agent commit before HITL is now dead code, remove it cleanly rather than leaving it stranded.
Keep the public surface (exports, routes, schemas) consistent with what the HITL commits imply.

Use the conventions from the project's CLAUDE.md (lint, format, naming, commit style). Match them — don't introduce a new style.

Phase 6 — When to ask

Default to acting. Only ask the user when there's a genuine fork in the road that the HITL commits don't resolve and that materially changes the outcome. Examples worth asking:

Two HITL commits imply different directions and you can't tell which to favor.
A frozen anchor forces a choice with visible product impact (e.g. a removed field is referenced by an external consumer).
The remaining work could be scoped narrowly (just stitch) or broadly (also redo adjacent agent work) — and the answer changes meaningfully.

Don't ask:

Naming nits, formatting, file placement, import order.
"Should I update the tests?" — yes, always.
"Should I keep this old code?" — if it's contradicted by HITL, no.
Anything you can verify by reading the code or running a check.

When you do ask, batch questions into one short message. Don't drip-feed.

Phase 7 — Verify

Before declaring done, run the project's standard checks (typecheck, lint, test — detect from CLAUDE.md and package.json the way the ship-it skill does). Fix what you broke; surface unrelated pre-existing failures.

Phase 8 — Report

One concise message to the user:

Which commits you treated as HITL anchors.
What you stitched (one line per area touched).
Anything you deliberately did not change because it was frozen.
Any blockers you hit, if any.

Then stop. Do not push or open a PR — that's the ship-it skill's job.

Red flags — STOP if you catch yourself thinking any of these

Thought	Reality
"The user's HITL change is wrong, let me fix it"	Frozen. Adapt around it.
"I'll just revert this HITL commit and redo it cleaner"	Never. New commits only, around the anchors.
"I'll ask the user to confirm each small adaptation"	Be proactive. Ask only at genuine forks.
"The agent commits before HITL look fine, I'll keep them as-is"	Check whether HITL contradicts them. If so, rewrite them.
"I'll just match the HITL style and not touch the rest"	Stitching means making the whole branch coherent, not just the diff.
"Tests are failing because of HITL, the user should fix that"	No — the user's edits are the spec; you fix the tests to match.