easysdd-issue-fix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-issue-fix

到这一步根因和方案已经确定（标准路径在

{slug}-analysis.md

里、快速通道在 report 阶段口头确认过），你的活是按方案改代码、验证效果、写下修复记录。

听起来直白，但 fix 阶段最容易出问题的不是改代码本身，而是改的过程中冒出的"顺手"冲动——顺手优化一下、顺手重构一点、顺手加个抽象。每一项单独看都说得通，但合在一个 PR 里就让别人分不清"这次到底为了修 bug 改了什么"。下面所有规则的目的都是让这种冲动停下来。

共享路径与命名约定看
easysdd/reference/shared-conventions.md
第 0 节和
easysdd-issue
的"文件放哪儿"节。

At this stage, the root cause and solution have been determined (the standard path is in

{slug}-analysis.md

, and the quick path was confirmed verbally during the report stage). Your task is to modify the code according to the solution, verify the effect, and write the repair record.

It sounds straightforward, but the most prone problem in the fix stage is not the code modification itself, but the "casual" impulse that arises during the modification—casually optimizing a bit, casually refactoring a little, casually adding an abstraction. Each item makes sense on its own, but putting them all in one PR makes it impossible for others to distinguish "what exactly was changed to fix the bug this time". The purpose of all the following rules is to stop this impulse.

For shared paths and naming conventions, refer to Section 0 of
easysdd/reference/shared-conventions.md
and the "Where to put files" section of
easysdd-issue
.

两种入口

Two Entry Points

标准路径入口（有 {slug}-analysis.md）

Standard Path Entry (with {slug}-analysis.md)

根因分析存在且方案已确认——读
```
{slug}-analysis.md
```
，确认 frontmatter 有
```
doc_type=issue-analysis
```
且
```
status=confirmed
```
，第 5 节"修复方案"用户选定了哪个方案
把上下文读全：
- 根因分析全文
- 问题报告全文
- 根因分析第 1 节定位到的所有代码文件
- ```
AGENTS.md
```
- 沉淀目录里与本 issue 相关的记录（统一搜
```
easysdd/compound/
```
  ，按需用
```
doc_type
```
  过滤）：
  - 查技巧：
```
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter status=active --query "{issue 关键词}"
```
    ——确认修复方式不违背已有库用法 / 模式建议
  - 查探索：
```
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --query "{issue 关键词}"
```
    ——确认修复点与已有证据不冲突
确认修复起点——告诉用户"我将按方案 X 修改 {文件列表}，开始修复"，等用户确认才动手

Root cause analysis exists and solution is confirmed——Read
```
{slug}-analysis.md
```
, confirm that the frontmatter has
```
doc_type=issue-analysis
```
and
```
status=confirmed
```
, and which solution the user selected in Section 5 "Repair Solution"
Read the full context:
- Full root cause analysis text
- Full problem report text
- All code files located in Section 1 of the root cause analysis
- ```
AGENTS.md
```
- Records related to this issue in the compound directory (search uniformly in
```
easysdd/compound/
```
  , filter by
```
doc_type
```
  as needed):
  - Trick search:
```
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter status=active --query "{issue keywords}"
```
    ——Confirm that the repair method does not violate existing library usage / pattern suggestions
  - Explore search:
```
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --query "{issue keywords}"
```
    ——Confirm that the repair point does not conflict with existing evidence
Confirm the repair starting point——Tell the user "I will modify {file list} according to Solution X, starting the repair", and wait for user confirmation before taking action

快速通道入口（无 {slug}-analysis.md，从 easysdd-issue-report 直接触发）

Quick Path Entry (without {slug}-analysis.md, triggered directly from easysdd-issue-report)

进入这个入口时，AI 在 report 阶段已经读过代码并对根因有把握。

向用户明确陈述根因："
```
{文件}:{行号}
```
的 {具体代码} 存在 {问题描述}"，让用户确认根因判断准确
给出修复方案——改哪里、怎么改（一两句话即可，不写成完整分析文档）
等用户明确说"对，就这样改"后才动手——不允许"我觉得对，直接改了"
读
```
AGENTS.md
```
补搜沉淀目录——快速通道也要用
```
search-yaml.py --dir easysdd/compound
```
查一遍，
```
--filter doc_type=trick
```
看同类技巧，
```
--filter doc_type=explore
```
避免误把已知边界条件当成新问题

When entering this entry, the AI has already read the code during the report stage and is confident about the root cause.

Clearly state the root cause to the user: "The {specific code} at
```
{file}:{line number}
```
has {problem description}", and let the user confirm that the root cause judgment is accurate
Provide a repair solution——Where to modify and how to modify (just one or two sentences, no need to write a complete analysis document)
Wait for the user to clearly say 'Yes, modify it this way' before taking action——"I think it's correct, modify directly" is not allowed
Read
```
AGENTS.md
```
Supplement search in the compound directory——The quick path also requires using
```
search-yaml.py --dir easysdd/compound
```
to search, check similar tricks with
```
--filter doc_type=trick
```
, and avoid mistaking known boundary conditions for new issues with
```
--filter doc_type=explore
```

实现期间的约束

Constraints During Implementation

只改根因分析里声明的文件

Only Modify Files Stated in the Root Cause Analysis

修复范围来自

{slug}-analysis.md

第 5 节"推荐方案"里的"影响面"。超出范围的文件——哪怕顺眼——不动。

发现范围外值得改的地方就记一条"顺手发现"，不改代码：

markdown

> 顺手发现：{文件:行号} {问题简述}。不在本次修复范围，可后续另开 issue。

为什么这么严？理由跟 feature-implement 一样——顺手改的代码不在分析里，验收时核对不上，后人 git blame 也分不清哪些改动是为了修这个 bug。

The repair scope comes from the "Impact Scope" in Section 5 "Recommended Solution" of

{slug}-analysis.md

. Do not modify files outside the scope—even if they look good.

If you find something worth modifying outside the scope, record it as a "casual discovery" without modifying the code:

markdown

> Casual discovery: {file:line number} {brief problem description}. Not within the scope of this repair, can open a separate issue later.

Why is this so strict? The reason is the same as feature-implement——casually modified code is not in the analysis, it cannot be checked during acceptance, and future developers cannot distinguish which changes were made to fix this bug via git blame.

改动最小化

Minimize Changes

修复的改动应该只针对根因，不引入新的抽象、新的接口、新的模式。如果发现"要把这个改好得先重构 X"——停下来，跟用户确认是否要在这个 issue 里做重构，还是拆成独立的工作。

为什么这么严？bug 修复天然是窄场景的动作。引入新抽象意味着这个抽象只有这一个使用点支撑——典型的过早抽象。要么先单独重构再修 bug，要么修完 bug 再单独重构，但别在一个 PR 里同时做。

The repair changes should only target the root cause, do not introduce new abstractions, new interfaces, or new patterns. If you find that "to fix this properly, you need to refactor X first"——stop, and confirm with the user whether to do the refactoring in this issue or split it into independent work.

Why is this so strict? Bug fixes are naturally narrow-scoped actions. Introducing a new abstraction means this abstraction is only supported by one usage point——a typical case of premature abstraction. Either refactor separately first then fix the bug, or fix the bug then refactor separately, but don't do both in one PR.

代码质量反射检查

Code Quality Reflection Check

修 bug 看似动作小，但 AI 写修复代码时一样会漂——在已经很长的文件里再塞一段特殊处理、在已经很重的类里再加一个方法、为了绕开某种边界情况加一个

if

分支。反射检查见

easysdd/reference/shared-conventions.md

第 7 节。

issue-fix 下这一节要比 feature-implement 更谨慎：触发了反射信号但结论是"该拆"时，默认不在本次 PR 里做——按"改动最小化"的逻辑记成顺手发现，另开工作收拾。唯一例外是"不拆就没法干净地修这个 bug"，那就停下来跟用户明确"修这个 bug 的前置是 {重构动作}，要不要合进来还是拆出去单独做"。

Although bug fixes seem small, AI can still drift when writing repair code——adding another special handling in an already long file, adding another method to an already heavy class, adding an

if

branch to bypass some boundary condition. For reflection checks, refer to Section 7 of

easysdd/reference/shared-conventions.md

In issue-fix, this section needs to be more cautious than feature-implement: when a reflection signal is triggered but the conclusion is 'should split', do not do it in this PR by default——record it as a casual discovery according to the "minimize changes" logic, and handle it in separate work later. The only exception is "cannot fix this bug cleanly without splitting", then stop and clearly tell the user "The prerequisite for fixing this bug is {refactoring action}, should it be included or split out to do separately".

每完成一处改动必须汇报

Report After Completing Each Change

修复汇报模板见同目录

reference.md

，不允许含糊汇报。汇报完后停下来等用户回复。

The repair report template is in the same directory

reference.md

, vague reports are not allowed. Stop and wait for the user's reply after reporting.

验证清单

Verification Checklist

修复代码改完后，在汇报里逐项核对：

复现步骤验证：按
```
{slug}-report.md
```
第 2 节的步骤走一遍，问题不再出现
期望行为验证：
```
{slug}-report.md
```
第 3 节描述的"期望行为"现在确实发生
影响面回归：
```
{slug}-analysis.md
```
第 4 节"潜在受害模块"——每个模块走一遍最基本的冒烟路径，确认没被修复引入新问题
前端改动浏览器验证（如果涉及）：AGENTS.md 硬要求，不能只靠 typecheck
相关测试通过：如果有测试覆盖到修复区域，跑一遍

After modifying the repair code, check each item in the report:

Reproduction Step Verification: Follow the steps in Section 2 of
```
{slug}-report.md
```
to confirm the problem no longer occurs
Expected Behavior Verification: The "expected behavior" described in Section 3 of
```
{slug}-report.md
```
now occurs as expected
Impact Scope Regression: "Potentially Affected Modules" in Section 4 of
```
{slug}-analysis.md
```
——Run the most basic smoke test for each module to confirm no new issues are introduced by the repair
Frontend Change Browser Verification (if applicable): Mandatory requirement in AGENTS.md, cannot rely solely on typecheck
Relevant Tests Pass: If there are tests covering the repair area, run them

修复未生效时：日志调试升级

When Repair Fails to Take Effect: Upgrade to Log Debugging

走完验证清单后如果发现问题仍然复现或行为与期望不符，别在原有猜测上反复试错——切换到日志调试模式，重新收集运行时证据。

为什么要切换？反复试错的本质是猜测在原假设下还有什么可能性，但如果原假设本身就错了，再多猜也是绕圈。日志会强制你看实际运行时数据，往往一眼就看出原假设哪里偏了。

日志调试步骤、用户取日志提示词和循环限制见同目录

reference.md

。

If after going through the verification checklist you find that the problem still reproduces or the behavior is inconsistent with expectations, do not repeatedly trial and error based on the original guess——switch to log debugging mode and re-collect runtime evidence.

Why switch? The essence of repeated trial and error is guessing what other possibilities exist under the original hypothesis, but if the original hypothesis itself is wrong, more guessing is just going in circles. Logs will force you to look at actual runtime data, which often reveals where the original hypothesis was wrong at a glance.

Log debugging steps, user prompt words for retrieving logs, and loop limits are in the same directory

reference.md

写 {slug}-fix-note.md

Write {slug}-fix-note.md

验证通过后在 issue 目录下建

{slug}-fix-note.md

（位置见

easysdd-issue

的"文件放哪儿"节），记录本次修复的完整闭环。标准路径模板和快速通道模板都在同目录

reference.md

。

After verification passes, create

{slug}-fix-note.md

in the issue directory (location refers to the "Where to put files" section of

easysdd-issue

) to record the complete loop of this repair. Both the standard path template and quick path template are in the same directory

reference.md

退出条件

Exit Conditions

所有改动文件已提交或列清单
验证清单全部勾选
```
{slug}-fix-note.md
```
已建并填写完整（标准路径用标准模板，快速通道用快速通道模板）
没有未处理的"顺手发现"（都进了后续 issue 列表）
没有范围外的改动（或已和用户确认）
用户明确确认修复完成

All modified files have been submitted or listed
All items in the verification checklist are checked
```
{slug}-fix-note.md
```
has been created and filled completely (use the standard template for the standard path, quick path template for the quick path)
No unresolved "casual discoveries" (all have been added to the subsequent issue list)
No changes outside the scope (or confirmed with the user)
User clearly confirms the repair is complete

收尾提交

Final Commit

按

easysdd/reference/shared-conventions.md

第 4 节"收尾提交（scoped-commit）"的规则执行。本阶段的特定要点：

提交范围：修复代码、
```
{slug}-fix-note.md
```
，以及本次确实一并更新的
```
{slug}-report.md
```
/
```
{slug}-analysis.md
```
修复闭环后告诉用户"修复验证已完成，
```
{slug}-fix-note.md
```
已落盘"，紧接着问是否需要 commit

Follow the rules in Section 4 "Final Commit (scoped-commit)" of

easysdd/reference/shared-conventions.md

. Specific points for this stage:

Commit Scope: Repair code,
```
{slug}-fix-note.md
```
, and
```
{slug}-report.md
```
/
```
{slug}-analysis.md
```
that were actually updated together this time
After the repair loop is completed, tell the user "Repair verification is completed,
```
{slug}-fix-note.md
```
has been archived", then immediately ask if commit is needed

退出后

After Exit

告诉用户："issue 修复完成，工作流闭环。问题报告（{slug}-report.md）+ 根因分析（{slug}-analysis.md）+ 修复记录（{slug}-fix-note.md）已存档。"

然后按

easysdd/reference/shared-conventions.md

第 3 节"issue-fix"收尾推荐顺序各问一句话（用户说"不用"立刻跳过）：

这次修复暴露了值得复用的坑点 / 经验 → "需要把这个坑沉淀成 learning 文档吗？（走
```
easysdd-learning
```
，会写入
```
easysdd/compound/
```
）"
这次修复沉淀出了长期约束、规约或技术决定 → "需要把这条决定归档吗？（走
```
easysdd-decisions
```
）"
最后补问一次是否需要代为提交本次修复。用户同意时按收尾提交规则执行到 commit 完成。

可以建议：

把 issue 目录下的文件和代码改动放在同一次提交里，方便日后追溯
"顺手发现"的后续 issue 另开一轮
```
easysdd-issue-report
```
处理，别在这个 PR 里塞

如果修复过程中发现问题实际上是功能缺失（不是 bug），建议用户另开

easysdd-feature

工作流处理，别在 issue 工作流里偷偷做新功能。

Tell the user: "Issue repair is completed, workflow is closed. Problem report ({slug}-report.md) + root cause analysis ({slug}-analysis.md) + repair record ({slug}-fix-note.md) have been archived."

Then ask one sentence each in the recommended closing order for "issue-fix" in Section 3 of

easysdd/reference/shared-conventions.md

(skip immediately if the user says "no"):

This repair exposed a pitfall / experience worth reusing → "Do you need to document this pitfall into a learning document? (Follow
```
easysdd-learning
```
, will be written into
```
easysdd/compound/
```
)"
This repair documented long-term constraints, conventions, or technical decisions → "Do you need to archive this decision? (Follow
```
easysdd-decisions
```
)"
Finally, ask again if you need to commit this repair on behalf of the user. When the user agrees, follow the final commit rules until the commit is completed.

You can suggest:

Put the files in the issue directory and code changes in the same commit for easy future tracing
Handle subsequent issues from "casual discoveries" in a new round of
```
easysdd-issue-report
```
, do not include them in this PR

If during the repair you find that the problem is actually a feature gap (not a bug), suggest the user open a separate

easysdd-feature

workflow to handle it, do not secretly implement new features in the issue workflow.

容易踩的坑

Common Pitfalls

修完代码没走验证清单就宣告"修好了"
顺手改了根因分析范围外的代码
修复引入了新的抽象 / 接口但没停下来跟用户确认
```
{slug}-fix-note.md
```
没建就宣告工作流完成
发现影响面回归有问题但在汇报里写"轻微影响，可以忽略"——要修到干净
前端有改动但没在浏览器跑，只 typecheck 就报通过
用户没明确说"修复完成"就结束工作流
修复未生效但继续在原假设上反复猜测试错，不切换到日志调试
日志调试结束后没清理临时 log 语句就提交代码
工作流收尾时没问用户是否需要代为 commit
用户没明确同意就直接
```
git commit
```

Declare "fixed" without going through the verification checklist after modifying the code
Casually modified code outside the scope of the root cause analysis
Introduced new abstractions / interfaces during repair but did not stop to confirm with the user
Declared workflow completed without creating
```
{slug}-fix-note.md
```
Found regression issues in the impact scope but wrote "minor impact, can be ignored" in the report——must fix until it's clean
Made frontend changes but did not run in the browser, only did typecheck and reported passing
Ended the workflow without the user clearly saying "repair completed"
When repair failed to take effect, continued to guess and trial and error based on the original hypothesis instead of switching to log debugging
Submitted code without cleaning up temporary log statements after log debugging
Did not ask the user if they need to commit on their behalf when closing the workflow
Directly
```
git commit
```
without the user's explicit consent