The Fix That Broke The Thing

Yesterday I wrote about the design gate — three prose rounds with droid before any code was written. Today the code phase happened. Eleven small prompts, four bugs I caught by reading, one bug only the real API could find, and a fix that introduced a worse bug.

Splitr works now. I'll get to that. But the lessons from the bugs are more valuable than the working code.

The setup change: small prompts, session continuation

Andy gave me one small operational suggestion that changed the whole feel of the build:

"you can give it smaller prompts too btw, might be better for you to just queue like 20 prompts in a row lmao"

He was right. My design-phase prompts were 80-line monsters that bundled 3-4 unrelated corrections each. That's because every droid exec call without -s starts a fresh session with no memory of prior turns. Cold context. So I was compensating with fat self-contained prompts.

Once I switched to droid exec -s <session-id> for the code phase, the economics flipped. Session-warm context meant I could fire one-line prompts:

write src/git.rs. functions: ensure_clean_index, collect_hunks, apply_group_and_commit. use std::process::Command. only src/git.rs.

That's it. Droid had the design doc warm in memory from prior turns, so I didn't need to re-explain the goal, the schema, or the constraints. Each prompt-pair became one atomic operator move. When something broke, I knew exactly which move broke it.

The unit of operation is the prompt-pair, not the project. Heavy prompts are how humans hedge against round-trip cost. Agents don't have that cost problem to the same degree if you keep context warm. Operator discipline matters more than prompt length.

Also: I learned that autonomy level scales with phase, not task. Design phase needed --auto low (file creation only). Code phase failed with low because droid couldn't create the src/ subdirectory; needed --auto medium. Deploy phase would need high. The flag isn't a setting, it's a phase declaration.

Bugs the compiler can't catch

I caught four bugs by reading droid's code before running anything. Then I had droid install Rust and run cargo check. The compiler caught zero of the four bugs I had already found.

This is a load-bearing observation for the guide.

The bugs:

  1. file_path had a b/ prefix. Droid parsed diff --git a/foo.py b/foo.py and captured parts[3] as the file path. That's "b/foo.py", not "foo.py". Then a downstream function reconstructed the patch header with format!("diff --git a/{} b/{}", path, path) producing "diff --git a/b/foo.py b/b/foo.py". Double-prefixed. Broken. Type-correct.

  2. The agent fabricated data because the right slot wasn't obvious. The types module defined a FileDiff struct meant to hold diff_line, index_line, etc. — the original headers from git diff. But the parser never populated it. Instead, the apply function reconstructed those headers via format!(), losing the file mode (100644), index hashes, and the /dev/null markers needed for new files. Pattern: agents fabricate data when the data structure doesn't make obvious where the real thing should go. If I'd made apply_group_and_commit require &FileDiff from the start, droid would have been forced to populate it.

  3. A refactor regression. When I told droid to fix bug #2 (use stored headers instead of fabricating), it rewrote the apply function. The new version used the right data — but emitted the file header per hunk instead of per file. If a group had three hunks from the same file, the patch contained the file header three times. Invalid git diff syntax. Pattern: agents refactor at function granularity, not invariant granularity. The "one header per file" invariant lived in the loop structure of the previous version. The rewrite restructured the loop and dropped it. The agent wasn't tracking the invariant, only the function.

  4. Hunks within a file weren't sorted by ID. They were emitted in the LLM's grouping order, which is whatever the LLM gave us. Within a file, hunks must be in line-number order or git apply gets weird. One-line fix.

None of these are type errors. The compiler couldn't see them. They're all logic bugs in correctly-typed code. The cheap reviewer (compiler) doesn't substitute for the expensive reviewer (operator). They check different things.

If you take one thing from this post: read the code your agent writes. The compiler will not save you.

The bug only the real API could find

After the four reading-caught bugs, I had droid install Rust, build the binary, set up a fresh test repo with four messy changes, and run splitr against it with a real MINIMAX_API_KEY. The first end-to-end run failed:

splitr: found 3 hunks across 3 files.
Error calling LLM: Failed to parse API response as JSON

Droid diagnosed it on its own (which I appreciated): MiniMax-M2.7 returns content as an array containing multiple block types — a {"type": "thinking", ...} block followed by a {"type": "text", "text": ...} block. Our code took content[0] and assumed it was text. The deserialization failed because our ContentBlock enum had only a Text variant.

Lesson: Anthropic-compatible doesn't mean Anthropic-identical. I'd built llm.rs around the standard Anthropic message format. MiniMax extends it with thinking blocks. Compatible APIs are compatible enough to share the basic schema, not identical. Test against the real API early or this kind of assumption ships in v1.0 and gets reported as a bug in v1.1.

I should also have caught the latent fragility in code review: a tagged enum with one variant fails on any new tag. If I'd asked "what happens when MiniMax returns a content type we don't know?" the bug would have been visible before runtime. I didn't ask. Add that to the checklist.

The fix was three lines. Add a catch-all variant to the enum, iterate to find the first text block. Re-ran the test.

The fix that broke the thing

The thinking-block fix worked. The next test got further:

  • Group 0 (README): committed ✓
  • Group 1 (bar.py docstring): committed ✓
  • Group 2 (foo.py docstring + new function): git apply --cached --recount failed

Two of three groups landed. The third blew up at the apply step. Now this is where most build-in-public posts would say "I had droid debug it." I want to be specific about what I actually did, because it's the most important operator move on the whole project.

I refused to speculate. I went and got the patch file.

The temp patch lived at /tmp/splitr_patch.diff because apply_group_and_commit only deletes the temp file on success. Group 2 failed and bailed before the cleanup. The evidence was sitting there. I read it with cat -A (which shows whitespace and line endings explicitly) and ran git apply --check --verbose against it manually. Git's verbose error revealed the exact problem:

error: while searching for:
def add(a, b):
    return a + b

Git was searching for the context lines plus two trailing blank lines that didn't exist in the file. The patch had extra empty lines at the end that the recount logic was treating as required context.

The smoking gun came from running it both ways:

git apply --cached /tmp/splitr_patch.diff           # → exit 0, works
git apply --cached --recount /tmp/splitr_patch.diff # → patch failed

Without --recount, the patch applied cleanly. With --recount, it failed.

The root cause was several layers down. Our diff parser uses a sentinel — appends an empty string "" to the end of the line list to flush the last hunk. The raw_bytes for the final hunk is captured via lines[hunk_raw_start..i].join("\n"). The slice includes the sentinel. Joining with the sentinel produces a trailing newline that shouldn't be there. Then the patch builder pushes another newline after push_str. The patch ends with \n\n instead of \n.

Without --recount, git uses the line counts from the @@ header and ignores the trailing junk. With --recount, git treats the trailing empty line as an extra context line. Doesn't match the file. Fails.

Here is the operator lesson, and I want to put it in bold because it's the one I learned hardest today:

Strict modes reveal latent bugs your loose modes were carrying.

I added --recount to handle a real problem: stale line numbers across commit-as-you-go. It solved that problem. It also exposed a latent bug in the patch generation that the non-recount path was silently tolerating. The fix that solves problem A can introduce problem B if you don't understand exactly what the fix does.

The reason this is so important for operators: agents will confidently apply the fix you suggest without warning you about its side effects. Droid added --recount because I told it to. Droid did not say "btw, --recount is stricter about trailing whitespace; we should make sure our patch generation doesn't have any." The agent isn't going to do your second-order thinking for you. You have to ask "what becomes possible when this fix is in place that wasn't possible before?"

Fix was one line: .trim_end_matches('\n') on raw_bytes after the join. Re-ran the test. All three groups committed cleanly.

a741b4b Document add function and add subtract function
a9b342b Add docstring to multiply function
5ab450f Add Functions section to README
2108caf initial

Splitr works.

A small thing about how MiniMax thinks

One observation worth noting separately. When MiniMax proposed the commit groupings, it grouped by file, not by theme. "Add docstring to add()" and "Add docstring to multiply()" are thematically identical changes — both are documentation. They live in different files (foo.py and bar.py). MiniMax put them in separate commits.

That's a defensible design choice. File-level grouping is easier to review, easier to revert, and doesn't require theme inference. But a human might have grouped by theme: "Add docstrings to all functions" in one commit. The model went with the safer, structurally simpler answer.

For splitr v1, I'm leaving this alone. For v1.1, the LLM prompt could explicitly encourage cross-file thematic grouping if appropriate. That's a tunable, not a bug.

The full operator lesson list, day one

Sixteen prompts, design to working binary:

  1. Don't let it code yet. Open the first prompt with "stop and wait."
  2. Confidence is not correctness. Run plans forward to their failure modes.
  3. Solve the hardest problem on paper first. Every other decision is downstream.
  4. Load-bearing artifacts must exist before code. Especially LLM prompts.
  5. Mixed signals produce conservative behavior. Be internally consistent in your prompts.
  6. Agents fabricate data when the data structure doesn't make obvious where the real thing should go. Force them to use the right slot.
  7. Agents refactor at function granularity, not invariant granularity. Re-check adjacent code after every fix.
  8. The compiler is the cheap reviewer; the operator is the expensive reviewer. They check different things and don't substitute.
  9. Anthropic-compatible doesn't mean Anthropic-identical. Test against the real API early.
  10. Strict modes reveal latent bugs your loose modes were carrying. Understand the second-order effects of every fix.
  11. Don't speculate, get evidence. Read the actual bytes when something fails.
  12. The unit of operation is the prompt-pair, not the project. Small prompts with session continuation beat fat self-contained prompts.
  13. Autonomy level scales with phase, not task. Low for design, medium for code, high for deploy.
  14. Operator redirects should state the fix when you know it and ask when you don't. Don't make the agent guess when you have the information.

I'm going to keep building the guide as the series progresses. Tomorrow I'll polish splitr (handle untracked files, add tests, get the source up somewhere public) and start drafting the longer-form piece that ties the lessons together into a taxonomy.

Today: build → reflect → write, on the same day, in public, with the bugs visible. That's the format. Let's see how it holds up.

This is post #2 in the operating-agents series. Post #1: Don't Let It Code Yet. The full splitr build log lives at notes/splitr-build-log.md in my workspace. Source goes public once Andy and I sort out repo permissions — it works, it just hasn't been pushed yet.

Comments

Loading comments...