| name | isolate-and-integrate |
| description | Use when implementing or changing product code in a repository that protects a canonical branch. Do the work in a throwaway git worktree off the canonical branch, verify it against the full quality gate, and cherry-pick only the finished, verified commits back — never commit to the canonical branch directly. Trigger on requests to add, fix, or refactor code. |
Deliver a change in isolation, then cherry-pick it
Protect the canonical branch: it must only ever receive finished, verified
commits — never a work-in-progress edit.
The operation
- Cut a throwaway git worktree off the canonical branch, on a
purpose-named branch.
- Implement there, in the module that owns the behavior. Isolate pure logic
into dependency-free units so it can be unit-tested.
- Verify the full gate before committing: typecheck, lint, tests, build.
Treat lint warnings as failures — write code that passes the project's
constraints the first time (the lint config is the source of truth).
- Commit the finished work in the worktree.
- Cherry-pick the commits onto the canonical branch; re-run the gate there.
- Discard the worktree.
On a cherry-pick conflict, resolve it on the canonical side and continue — never
hand-edit the canonical branch to paper over a botched integration.
The concrete commands, branch-naming, per-worktree setup, and commit conventions
are project-specific — read the project's CLAUDE.md for them. This skill is the
method, not the invocation.
When the owner is unclear
For an unfamiliar or cross-cutting change, orient first (the
orient-before-edit skill): find and confirm the owning module before cutting
the worktree.
When the gate exposes an unrelated red
While running the gate inside the worktree, an unrelated, pre-existing
failure may surface. Do not widen the scope of the current branch to
absorb it. Stop, surface the finding, open a sibling problem ticket
(fix-as-poc skill), land that fix on its own worktree, then git rebase
and continue. The discipline of "1 worktree = 1 purpose" is what keeps
each cherry-pick reviewable.
The one exception
A direct commit to the canonical branch is allowed only to seed an empty
repository (no base commit exists to branch from). After the first commit,
everything goes through a worktree.
