build-fix

/build-fix

What

The kit's autonomous iteration-loop skill. It drives a broken dotnet build (or failing dotnet test) to green by looping: run, parse failures, categorize by root cause, apply targeted fixes, re-run. It repeats until green or a guard fires — the same way an experienced developer works through a wall of red, but with hard limits that stop it from thrashing.

This is not a single-pass fix. It handles cascading errors where fixing one issue reveals the next.

When

• The build is broken and there are multiple compiler errors
• Tests are failing after code changes or a build-fix pass
• After a major refactor that touched type names, namespaces, or signatures
• After updating NuGet packages (especially major version bumps)
• After merging a branch with conflicts resolved but not compiled
• After scaffolding or code generation that needs manual adjustments
• User says: "fix the build", "make it compile", "make the tests pass",

"keep going until it works", "keep fixing"

How

Loop Discipline (applies to every loop)

1. Bounded iteration, always — Default max 5 iterations, hard cap 10

(user "keep going" extends by 3, never past 10). If 5 iterations cannot solve it, the problem needs human judgment, not a 6th identical attempt.

1. Progress or exit — Each iteration must reduce the error/failure count.

Same errors after a fix attempt = STUCK: stop, report, and re-plan with a different approach. Never retry the same fix that already failed.

1. Categorize before fixing — Group errors by root cause and fix the

highest-leverage first (one missing using can erase a dozen downstream errors).

1. Transparency per iteration — Report what changed and why:

Iteration 3/5: fixed CS0246 by adding using System.Text.Json, 2 remain. Never modify files silently.

1. Atomicity — Each iteration leaves the codebase no worse than before.

If iteration 3 fails, the code stays in iteration 2's state.

Primary Flow: Build-Fix Loop (max 5 iterations)

1. Build — Run dotnet build, capture full error output
2. Parse — Extract every error CS#### with file, line, and message
3. Categorize — Group by root cause:

1. Fix — Apply targeted fixes, root-cause/highest-leverage errors first
2. Rebuild — Run dotnet build again, compare error count
3. Evaluate — Zero errors: run dotnet test as a sanity check, report

success. Fewer errors: continue. Same errors: STUCK — exit and re-plan. More errors: revert the iteration, report REGRESSION.

Variant: Test-Fix Loop (max 5; 3 if it follows a build-fix pass)

Same loop, same guards, with dotnet test --no-build as the runner and one critical extra step — diagnose before fixing:

1. Read the test — understand the assertion and setup
2. Read the production code — understand the actual behavior
3. Decide where the bug lives: wrong expectation → fix the test; production

bug → fix the code; incomplete setup → fix the setup; contract changed → update the test to match

1. Never weaken an assertion to make a test pass.

BAD: Assert.Equal(expected, actual) → Assert.NotNull(actual). GOOD: fix the production code so the original assertion passes.

Fail-Safe Guards (immediate exit)

• STUCK — same errors/failures after a fix, or count oscillates

(3 → 2 → 3): report what could not be fixed and what a human should check

• REGRESSION — an iteration introduced more errors than it fixed: revert

its changes, report

• Cascading failures — fixing one error spawns 3+ new ones twice in a

row: the approach is wrong, stop

• Critical error — wrong SDK, missing project file, corrupted solution,

or the test runner itself fails: human intervention needed, stop

• User interruption — finish the current iteration, report progress, ask

how to proceed

Other Loops

The same discipline — bounded iterations, progress detection, fail-safe guards — governs refactor passes (/de-sloppify: verify build + tests after each target, revert on failure) and scaffolding (/scaffold: generate, then run nested build-fix and test-fix loops). Nested loops get a smaller budget (parent 5 → nested 3), max nesting depth 2, total budget 15.

Invokes

MCP Tools Used

• get_diagnostics — Compiler errors/warnings scoped to file or project
• find_symbol — Locate moved or renamed types
• find_references — Assess blast radius of a broken API change
• get_project_graph — Dependency order for fixing reference errors

Example

User: /build-fix

Claude: Running dotnet build...
  Found 12 errors across 4 files.

  Iteration 1/5:
  - 6 errors: Missing namespace (CS0246) — adding using directives
  - 3 errors: Type mismatch (CS1503) — updating method signatures
  - 3 errors: Interface not implemented (CS0738) — package API changed

  Rebuilding... 3 errors remaining.

  Iteration 2/5:
  - 3 errors: CS0738 after xunit.v3 upgrade
    - IAsyncLifetime.InitializeAsync now returns ValueTask (was Task in v2),
      and DisposeAsync comes from IAsyncDisposable
    - Updating 3 test fixtures to the ValueTask signatures

  Rebuilding... 0 errors. Build is green.

  Running dotnet test... All 47 tests passed.
  Added to Memory > Packages: "xunit.v3 IAsyncLifetime uses ValueTask signatures"

Related

• /verify — Full verification pass (build + test + format + diagnostics)
• /tdd — Red-green-refactor when building new features test-first
• /de-sloppify — Clean up code quality issues after the build is green