Chunked Impl

Chunked Implementation

This skill provides the outer loop — splitting a change into small chunks and landing each as its own commit — and delegates the inner loop of building each chunk to the tdd skill (https://github.com/mattpocock/skills/tree/main/skills/engineering/tdd), which drives a red-green-refactor cycle. The tdd skill must be installed and available; invoke it for the implementation of every chunk.

Deliver non-trivial changes as a sequence of small, independently verifiable commits. Each chunk is built test-first via red-green-refactor, ends in a green test run, and is then committed. Nothing is committed until tests are green. The refactor phase of the tdd loop is where the just-written code gets cleaned up before it lands.

This matters because small, tested commits make regressions easy to bisect, make reviews easier, and let the user stop, resume, or roll back at any point without losing context.

Precondition: the tdd skill must be installed

This skill cannot function without the tdd skill — it drives the red-green-refactor loop for every chunk. Before doing anything else, confirm the tdd skill is available (it appears in your list of available skills).

If the tdd skill is not available, stop immediately. Do not start planning chunks or writing code. Tell the user it's required and how to install it:

The chunked-impl skill depends on the tdd skill, which isn't installed. Install it from https://github.com/mattpocock/skills/tree/main/skills/engineering/tdd, then re-run this skill.

Only proceed to step 1 once the tdd skill is confirmed available.

Workflow

Follow these steps. Treat them as a loop, not a one-shot script.

1. Plan the chunks

Before writing any code, sketch the chunks out loud to the user and confirm direction. A chunk is:

• Small: ideally 5–50 lines of diff, done in one focused change.
• Self-contained: it compiles and its tests pass on its own.
• Meaningful: it represents one logical step (e.g., "add schema", "parse input", "wire handler", "add edge-case test").

Frame each chunk as one or a few observable behaviors — this list is what the tdd loop will turn into tracer-bullet tests in step 3, so describe behaviors ("rejects empty tokens"), not implementation steps ("add an if-statement").

Use TaskCreate to record the chunk list so both you and the user can see progress.

If the change is trivial (one-line fix, typo), say so and skip this skill — the overhead isn't worth it.

2. Verify the starting state is green

Before the first chunk, run the project's test command once to confirm the baseline is clean. If it's already failing, stop and surface that to the user — don't bury pre-existing failures under new commits. If the project has no test runner set up at all, stop and tell the user; offer to set up the test framework as the first chunk rather than proceeding untested (the tdd loop needs a way to run tests).

How to find the test command, in order:

1. Check CLAUDE.md / AGENTS.md / README.md for the canonical command.
2. Inspect package.json, Makefile, pyproject.toml, go.mod, Cargo.toml, etc.
3. Ask the user if it's ambiguous.

Record the command so every chunk uses the same one.

3. Build the chunk with the tdd skill (red-green-refactor)

Invoke the tdd skill and apply its red-green-refactor loop to this chunk, using the chunk's behaviors from step 1 as the behavior list:

• Red: write one test for the next behavior in the chunk; watch it fail.
• Green: write the minimal code to make that test pass.
• Repeat one behavior at a time (vertical slices / tracer bullets) until the chunk's behaviors are covered. Don't write all the chunk's tests up front — that's the horizontal-slice anti-pattern the tdd skill warns against.
• Refactor (mandatory pass — every chunk, no exceptions): once the chunk is green, do an explicit refactor review before you move on. The judgment of whether refactoring is needed is itself part of this pass, not a precondition for entering it — so always perform it. Scan the code this chunk just touched against concrete criteria — duplication to extract, a module to deepen, unclear names, a SOLID violation worth fixing — and state your judgment out loud: name what you checked, then either describe the cleanup you applied, or, when the code is already clean, give an explicit "refactor: nothing to clean up — already minimal" with the one-line reason it needs nothing. The verdict "no refactor needed" is a valid and expected outcome, but it must be a stated verdict, never a silent skip. Saying the outcome is what forces the pass to actually happen on the way to commit. Never refactor while red, re-run tests after each refactor step, and stay inside the chunk's scope — this pass cleans up the code this chunk wrote, it is not a license to roam.

Stay within the chunk's scope. Resist the urge to "fix one more thing while I'm here" — that's what the next chunk is for. If implementing the chunk balloons well past its planned size, that's a signal the chunk was too big — stop, return to step 1, and re-plan with smaller chunks.

4. Confirm the chunk is green

The tdd loop already runs tests as it goes; before committing, confirm the chunk is green as a whole. Prefer scoping to the affected package/file when the suite is slow (e.g., pytest path/to/test_foo.py, go test ./pkg/..., npm test -- path/to.test.ts). Run the full suite at least at the end of the chunk, and any time you touch shared code (type definitions, common utilities, config files, build/CI scripts).

• Green: proceed to step 5.
• Red: fix the issue in place before committing. Do not commit a red chunk. Do not disable tests to make them pass.

5. Commit

Stage only the files belonging to this chunk (git add <specific files>, not git add -A) and commit with a Conventional Commits v1.0.0 message. Use scopeless form (type: description) — the Conventional Commits scope is optional, and this project prefers to omit it. The subject line should be short and describe what changed; include a body with the why whenever the reason isn't obvious from the diff (non-trivial trade-offs, context the reader won't have, why this approach over alternatives). Skip the body only when the change genuinely speaks for itself.

feat: add tokenizer for quoted strings
fix: reject empty bearer tokens
test: cover discount edge cases
refactor: extract connection pool

Example with a body (why is non-obvious):

fix: reject empty bearer tokens

Previously an empty Authorization header passed validation and fell
through to the DB lookup, which returned the first row. Explicit
rejection avoids the lookup and closes the auth-bypass path.

One chunk = one commit. The tests and refactor from step 3 fold into the same commit — they're part of landing this chunk cleanly, not separate commits.

6. Update todos and continue

Mark the chunk done, then return to step 3 for the next chunk. Give the user a one-line status update that includes the refactor verdict from step 3 so the pass stays visible — e.g. "chunk 2/5 green, refactor: extracted validateToken, committed as abc1234" or "chunk 3/5 green, refactor: nothing to clean up, committed as def5678". Always carrying the verdict in the status line is the forcing function: producing the line requires having actually made the judgment.

Guardrails

• Never skip hooks (--no-verify) to force a commit through. If a pre-commit hook fails, treat it as a red test.
• Never amend a previous commit to fold in a new chunk — create a new commit so the history stays honest.
• Never refactor while tests are red — get the chunk to green first, then clean up.
• Never skip the refactor review — every chunk gets the explicit refactor pass from step 3 before it's committed, including the judgment of whether any cleanup is needed. A green-then-commit with no stated refactor verdict is exactly the silent skip this guards against; "nothing to clean up" is a fine verdict, an absent one is not.
• Never commit secret-bearing environment files (.env, .env.*, local credential files), even when the user asks. Commit only sanitized templates such as .env.example after verifying they contain placeholders instead of real secrets.
• Never commit generated artifacts unless the user has asked for them (build outputs, large binaries).
• Never git add -A / git add . — stage the chunk's files explicitly so unrelated working-tree changes don't sneak in.
• If the baseline is red, don't start. Surface it.
• If there's no test runner, tell the user. Offer to set it up as the first chunk rather than proceeding untested.
• Don't auto-push. Commits stay local unless the user asks to push.

When to stop and check in

Pause and ask the user when:

• A chunk's tests keep failing in ways that suggest the plan was wrong.
• You discover the change touches more surface area than the plan anticipated.
• A chunk needs a destructive or hard-to-reverse action (migrations, schema changes, dependency bumps).

A short check-in beats a long detour.