implement-patch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implement Patch

实现补丁

When to Use

使用时机

Use after independent validation confirms one claim. Read the record contract. Before target commands, follow its project guidance.

在独立验证确认一个结论后使用。阅读记录契约。执行目标命令前，请遵循其项目指导。

When NOT to Use

不要使用的情况

Do not use for speculative bug hunting, proof of a completed patch, or a change that cannot be exercised by the local compiler or runtime.

不要用于推测性 bug 排查、对已完成补丁的验证，或无法通过本地编译器或运行时进行检验的变更。

Procedure

流程

Before editing, run
```
uv run --no-project <script> check --before-repair <run-dir>
```
with the record validator. If this check fails, stop and return its errors for an INCONCLUSIVE report. The gate requires
```
finding.repair_scope
```
with a usable case plan and a consistent attempt count. Use the declared scope as the repair brief. Identify the broken invariant and search within its boundary for every instance of the same violation. Read the threat model only to preserve intended behavior; it is not a gate.
Run the project's existing suite and record its results. Write a regression test that fails on the baseline for the named bug and any fixed variant. Observe the failure. Fix the invariant within the repair brief with the smallest reviewable change.
Run the regression test and full existing suite again. Compare before and after failures. Fix new failures or explain a pre-existing one from receipts.
Record every variant as
```
fixed
```
or
```
not_fixed
```
with a reason. Produce exactly one local commit. Never push or open a PR. From the baseline, write
```
fix.patch
```
for production changes and
```
tests.patch
```
for test changes in
```
patch/attempt-N/
```
.
Write
```
patch.json
```
with the two commit SHAs, changed-file and line counts, variants, suite results, and your agent identity. If the attempt produced no commit, record
```
patch_commit: null
```
and return it as failed. Manifest the entire attempt directory, including both patch files and the record, using
```
uv run --no-project <script> manifest <patch-attempt-dir>
```
. Check it with the record validator.
Patch record schema:

json

{
  "schema_version": 1,
  "attempt": 1,
  "baseline_commit": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "patch_commit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "files_changed": 2,
  "lines_added": 3,
  "lines_removed": 1,
  "variants": [],
  "suite_before": {"command": "pytest", "passed": 9, "failed": 1, "skipped": 0},
  "suite_after": {"command": "pytest", "passed": 10, "failed": 0, "skipped": 0},
  "agent": "patcher-1"
}

编辑前，运行
```
uv run --no-project <script> check --before-repair <run-dir>
```
并使用记录校验器。如果此检查失败，请停止操作并返回其错误，以生成 INCONCLUSIVE 报告。该校验关卡要求
```
finding.repair_scope
```
包含可用的案例计划和一致的尝试次数。将声明的范围用作修复简报。识别被破坏的不变量，并在其边界内搜索同一违规行为的所有实例。读取威胁模型只是为了保留预期行为；它不是校验关卡。
运行项目现有的测试套件并记录结果。编写回归测试，使其在基线版本上针对指定 bug 和任何已修复的变体失败。观察失败情况。在修复简报范围内修复不变量，并采用最小且便于审查的变更。
再次运行回归测试和完整的现有测试套件。比较修复前后的失败情况。修复新出现的失败，或根据 receipts 解释预先存在的失败。
将每个变体记录为
```
fixed
```
或
```
not_fixed
```
，并附上原因。恰好生成一个本地提交。绝不 push 或创建 PR。以基线为起点，为生产代码变更写入
```
fix.patch
```
，为测试变更写入
```
tests.patch
```
，放入
```
patch/attempt-N/
```
。
编写
```
patch.json
```
，其中包含两个提交 SHA、变更文件数和行数、变体、测试套件结果和 Agent 身份。如果本次尝试未产生提交，则记录
```
patch_commit: null
```
并将该尝试作为失败返回。使用
```
uv run --no-project <script> manifest <patch-attempt-dir>
```
为整个尝试目录生成 manifest，其中包括两个补丁文件和记录。使用记录校验器进行检查。
补丁记录 Schema:

json

{
  "schema_version": 1,
  "attempt": 1,
  "baseline_commit": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "patch_commit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "files_changed": 2,
  "lines_added": 3,
  "lines_removed": 1,
  "variants": [],
  "suite_before": {"command": "pytest", "passed": 9, "failed": 1, "skipped": 0},
  "suite_after": {"command": "pytest", "passed": 10, "failed": 0, "skipped": 0},
  "agent": "patcher-1"
}

Rationalizations to Reject

应拒绝的简化做法

Shortcut	Required action
Only the reported line matters.	Search for the same invariant violation.
Minimal means the fewest lines.	Make the smallest reviewable invariant-level fix.
Tests pass after the patch.	Show the regression test failed before it.

捷径	必需操作
只关注报告的那一行。	搜索相同的不变量违规。
“最小”意味着行数最少。	进行最小且便于审查的不变量级修复。
补丁后测试通过。	证明回归测试在补丁前失败。