Back to Details

build-fix

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/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.
本工具包的自动迭代循环技能。它通过循环执行以下步骤将失败的
dotnet build
（或失败的
dotnet test
）修复至正常状态：运行、解析错误、按根本原因分类、应用针对性修复、重新运行。重复此过程直到状态正常或触发防护机制——这与经验丰富的开发者解决大量错误的方式相同，但有严格限制以避免无效操作。
这并非单次修复流程。它能处理修复一个问题后暴露下一个问题的连锁错误。

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"
  • 构建失败且存在多个编译错误
  • 代码变更或构建修复后测试失败
  • 完成涉及类型名称、命名空间或签名的重大重构后
  • 更新NuGet包后（尤其是大版本升级）
  • 合并分支并解决冲突但未编译后
  • 脚手架或代码生成后需要手动调整时
  • 用户说出以下指令时：“修复构建”“让它编译通过”“让测试通过”“一直修复直到正常”“持续修复”

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.
  2. 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.
  3. Categorize before fixing — Group errors by root cause and fix the highest-leverage first (one missing 
    using
    can erase a dozen downstream errors).
  4. 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.
  5. Atomicity — Each iteration leaves the codebase no worse than before. If iteration 3 fails, the code stays in iteration 2's state.
  1. 始终限制迭代次数 — 默认最多5次迭代，硬上限为10次（用户指令“一直修复”可额外增加3次，但绝不超过10次）。若5次迭代无法解决问题，则该问题需要人工判断，而非第6次重复尝试。
  2. 有进展才继续，否则退出 — 每次迭代必须减少错误/失败数量。尝试修复后错误无变化=陷入僵局：停止操作、报告情况并改用其他方法重新规划。绝不重复已失败的相同修复方案。
  3. 先分类再修复 — 按根本原因对错误分组，优先修复影响最大的问题（一个缺失的
    using
    指令可能消除十几个下游错误）。
  4. 每次迭代保持透明 — 报告修改内容及原因：
    第3/5次迭代：通过添加using System.Text.Json修复CS0246错误，剩余2个错误
    。绝不静默修改文件。
  5. 原子性 — 每次迭代结束后，代码库状态不会比之前更差。若第3次迭代失败，代码将保留第2次迭代后的状态。

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

核心流程：构建修复循环（最多5次迭代）

  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:
    CategoryCodesFix strategy
    Missing using/referenceCS0246, CS0234Add using, package, or project ref
    Type mismatchCS0029, CS1503Check expected type, cast or convert
    API changeCS0117, CS7036Check new signature, update call sites
    NullabilityCS8600–CS8604Add null check, 
    ?.
    or 
    ??
    Ambiguity / duplicateCS0104, CS0121, CS0111Qualify namespace, remove dupe
    Missing memberCS1061Check spelling, verify member exists
    Missing implementationCS0535Implement interface/abstract members
    Obsolete APICS0618Replace with recommended alternative
  4. Fix — Apply targeted fixes, root-cause/highest-leverage errors first
  5. Rebuild — Run 
    dotnet build
    again, compare error count
  6. 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.
  1. 构建 — 运行
    dotnet build
    ，捕获完整错误输出
  2. 解析 — 提取所有带文件、行号和消息的
    error CS####
    错误
  3. 分类 — 按根本原因分组：
    分类错误代码修复策略
    缺失using/引用CS0246、CS0234添加using指令、包引用或项目引用
    类型不匹配CS0029、CS1503检查预期类型，进行强制转换或转换
    API变更CS0117、CS7036检查新签名，更新调用位置
    可空性CS8600–CS8604添加空值检查、
    ?.
    或
    ??
    运算符
    歧义/重复CS0104、CS0121、CS0111限定命名空间，移除重复项
    缺失成员CS1061检查拼写，验证成员是否存在
    缺失实现CS0535实现接口/抽象成员
    过时APICS0618替换为推荐的替代方案
  4. 修复 — 应用针对性修复，优先处理根本原因/影响最大的错误
  5. 重建 — 再次运行
    dotnet build
    ，对比错误数量
  6. 评估 — 错误数量为0：运行
    dotnet test
    作为 sanity check，报告成功。错误数量减少：继续循环。错误数量不变：陷入僵局——退出并重新规划。错误数量增加：回滚本次迭代的修改，报告退化。

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

变体：测试修复循环（最多5次；若在构建修复流程后执行则最多3次）

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
  4. 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.
循环规则相同，安全防护机制相同，但以
dotnet test --no-build
作为运行器，并增加一个关键步骤——修复前诊断：
  1. 阅读测试代码——理解断言和设置逻辑
  2. 阅读生产代码——理解实际行为
  3. 判断错误位置：预期错误→修复测试；生产代码Bug→修复代码；设置不完整→修复设置；契约变更→更新测试以匹配新契约
  4. 绝不要通过弱化断言来让测试通过。 错误示例：
    Assert.Equal(expected, actual)
    → 
    Assert.NotNull(actual)
    。 正确示例：修复生产代码使原始断言通过。

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
  • 陷入僵局 — 修复后错误/失败数量不变，或数量波动（3→2→3）：报告无法修复的问题及人工需检查的内容
  • 退化 — 某次迭代引入的错误比修复的更多：回滚本次修改，报告情况
  • 连锁失败 — 修复一个错误连续两次引发3个以上新错误：当前方法有误，停止操作
  • 严重错误 — SDK版本错误、项目文件缺失、解决方案损坏或测试运行器本身失败：需人工干预，停止操作
  • 用户中断 — 完成当前迭代，报告进度，询问后续操作

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.
相同规则——有限迭代、进度检测、安全防护机制——适用于重构流程（
/de-sloppify
：每次目标修改后验证构建+测试，失败则回滚）和脚手架流程（
/scaffold
：生成代码后，运行嵌套的构建修复和测试修复循环）。嵌套循环的迭代次数更少（父循环5次→子循环3次），最大嵌套深度为2，总迭代次数上限为15次。

Invokes

调用对象

TypeNamePurpose
Skill
instinct-system
Capture fix patterns in MEMORY.md
Agent
dotnet-architect
Consulted for architectural error patterns
类型名称用途
Skill
instinct-system
在MEMORY.md中记录修复模式
Agent
dotnet-architect
咨询架构相关错误模式

MCP Tools Used

使用的MCP工具

  • 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
  • get_diagnostics
    — 限定在文件或项目范围内的编译器错误/警告
  • find_symbol
    — 定位移动或重命名的类型
  • find_references
    — 评估API变更的影响范围
  • get_project_graph
    — 修复引用错误的依赖顺序

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"
User: /build-fix

Claude: 正在运行dotnet build...
  在4个文件中发现12个错误。

  第1/5次迭代：
  - 6个错误：缺失命名空间（CS0246）——添加using指令
  - 3个错误：类型不匹配（CS1503）——更新方法签名
  - 3个错误：未实现接口（CS0738）——包API已变更

  正在重建... 剩余3个错误。

  第2/5次迭代：
  - 3个错误：xunit.v3升级后的CS0738错误
    - IAsyncLifetime.InitializeAsync现在返回ValueTask（v2中为Task），且DisposeAsync来自IAsyncDisposable
    - 将3个测试夹具更新为ValueTask签名

  正在重建... 0个错误。构建已正常。

  正在运行dotnet test... 全部47个测试通过。
  已添加至Memory > Packages："xunit.v3 IAsyncLifetime使用ValueTask签名"

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
  • /verify
    — 完整验证流程（构建+测试+格式化+诊断）
  • /tdd
    — 测试优先构建新功能时的红-绿-重构流程
  • /de-sloppify
    — 构建正常后清理代码质量问题