---
name: small-steps-builder
description: Builds software in small verifiable increments - one change, run it, commit, repeat - keeping the app runnable at every step and recovering cleanly when a step breaks things. Use when implementing a feature or app through a multi-step build with an agent.
---

# Small Steps Builder

Large unverified changes are the main way agent-built projects rot. Work in increments where each one is small, runs, and is saved before the next begins.

## The loop

Repeat for every step:

1. Pick the next smallest change that adds one visible behavior. If the plan step is bigger than roughly 50 to 100 changed lines or touches more than 3 files, split it.
2. State the change and the check in one or two lines before editing: "Add the `/health` route; check: curl returns 200".
3. Make only that change. Do not tidy unrelated code on the way.
4. Run it. Use the strongest check available, in this order: automated tests, the type checker or linter, starting the app and exercising the feature, reading the output. "It compiles" is not a check for behavior.
5. If the check passes, commit (agree once at the start that you will commit after each green step) with a message describing the one change. If the project is not a git repo, ask the user whether to initialize one.
6. Tell the user in one line what now works, then move to the next step.

## Keep it runnable

- The main branch state after every commit must start and pass existing tests.
- Prefer a thin working slice over finished layers: one route that reads from the real database beats a complete data layer with no route.
- Stub what is not built yet (a fixed response, a TODO screen) so the app still runs, and list stubs so they are not forgotten.
- Add a test with the feature when the behavior is core or easy to get wrong. A smoke test that boots the app is worth adding at step 1.
- Do not install a dependency mid-step without telling the user why. One dependency per step, committed with the step that uses it.

## When a step breaks things

1. Stop adding code. Read the actual error output completely.
2. Check what changed: `git status` and `git diff`. The cause is almost always inside the current step.
3. If the fix is obvious and small, fix it and rerun the same check.
4. If a second attempt fails, stop guessing. Revert only the current step's changes with `git restore <files>` for tracked files you changed in this step, or `git stash` to keep them aside. Confirm with the user before discarding work they might want, and never run a hard reset without asking.
5. Retry the step in a smaller form: first the part that works in isolation, then the integration.
6. If three attempts fail, report: what you tried, the exact error, and your best hypothesis. Ask for direction instead of changing approach silently.

## Commit hygiene

- One logical change per commit. Message in imperative mood: "add login form validation".
- Never commit secrets, `.env` files, build output or the dependency folder. Check `git status` before staging and add a `.gitignore` early.
- Stage files by name instead of adding everything when untracked files you did not create are present.
- Do not push unless the user asked for it.

## Example of a good step sequence

```
1. app boots and GET /health returns 200            check: curl -i localhost:3000/health
2. create the notes table and a migration           check: migration runs on an empty database
3. POST /notes stores a note                        check: test posts one and reads it back
4. GET /notes lists notes                           check: test with zero and with three notes
5. notes page renders the list                      check: open the page, see three notes
```

Each line is one commit. If a line needs the word "and" between two behaviors, split it.

## Pitfalls

- Batching: "I'll do steps 3, 4 and 5 together" is how bugs become impossible to locate. Do not.
- Fixing a failing test by weakening it. Fix the code, or tell the user the test expectation looks wrong.
- Leaving the app broken at the end of a turn. If you must stop mid-step, revert to the last working commit state or leave a clear note about what is half-done.
- Declaring success without running the check. Say what you ran and what it printed.

## Report back

After each step: the change, the check you ran and its result, the commit message, and the next step. After a failed step: the error, what you reverted, and what you need.

Source: [AnyModel skills catalog](https://anymodel.org/en/skills) · License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
