easysdd-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

easysdd-issue

修 bug 直觉上是"找到错的地方改了就完事"，但这个直觉路径反复制造同样的麻烦：

问题描述只在脑子里，改完就忘了——三个月后同样的 bug 再现，没有任何复现步骤留存
根因没分析就动手——改了表面现象，深层问题还在等下次爆发
修复范围扩散——发现一个 bug 顺手改了五处，引入新问题，无法追溯到底是哪一改引入的
没有验收闭环——怎么判断改好了？改好了什么？没有记录

issue 工作流在"看到问题"和"动手改代码"之间塞了一道缓冲：

发现问题 → 清晰记录（report）→ 根因分析（analyze）→ 定点修复 + 验证（fix）

本技能本身不写任何东西，只看一下当前 issue 走到哪一步、决定该触发哪个子技能。

Intuitively, fixing a bug is just "finding the wrong part and modifying it", but this intuitive path repeatedly causes the same troubles:

The problem description only exists in your mind and is forgotten after modification—three months later, the same bug reappears with no reproduction steps saved
Starting modification without analyzing the root cause—only fixing the surface phenomenon, while the deep problem remains and waits for the next outbreak
Uncontrollable expansion of repair scope—finding one bug and modifying five places casually, introducing new problems with no way to trace which modification caused them
No acceptance closed loop—how to judge if the fix is successful? What has been fixed? No records

The issue workflow inserts a buffer between "seeing the problem" and "starting to modify code":

Discover problem → Clear documentation (report) → Root cause analysis (analyze) → Targeted repair + Verification (fix)

This skill itself does not write anything; it only checks which step the current issue has reached and decides which sub-skill to trigger.

文件放哪儿

Where to place files

整套 issue 流程的产物聚在

easysdd/issues/

下，每个 issue 一个独立目录：

easysdd/
└── issues/
    └── {issue}/
        ├── {slug}-report.md           ← 阶段 1 的问题报告
        ├── {slug}-analysis.md         ← 阶段 2 的根因分析
        └── {slug}-fix-note.md         ← 阶段 3 的修复记录（必出产物）

目录命名是

YYYY-MM-DD-{英文 slug}

：

日期取发现 / 提报问题当天，定了不动
slug 用小写字母、数字、连字符，能一眼看出是什么问题（
```
auth-token-leak
```
、
```
null-pointer-on-empty-list
```
这种）

为什么所有产物聚在一起？跟 feature 一样的逻辑——后人查"上次那个 bug 当时怎么定位的"，三份文件都在一处不用东找。issue 和 feature 的目录分别在

easysdd/issues/

和

easysdd/features/

，别交叉。

{slug}-fix-note.md

是阶段 3 的必出产物——无论修复简单还是复杂都要写。修复记录不是仪式，是回溯凭证：没有它，下次类似问题来了你只能从 git log 里反推当时改了什么。

所有 issue 文档都要带 YAML frontmatter（

doc_type

分别为

issue-report

issue-analysis

issue-fix

），便于

search-yaml.py

按 severity、tags、status 检索。

All outputs of the entire issue workflow are gathered under

easysdd/issues/

, with an independent directory for each issue:

easysdd/
└── issues/
    └── {issue}/
        ├── {slug}-report.md           ← Issue report for Phase 1
        ├── {slug}-analysis.md         ← Root cause analysis for Phase 2
        └── {slug}-fix-note.md         ← Repair record for Phase 3 (mandatory output)

The directory is named

YYYY-MM-DD-{English slug}

The date is taken as the day the problem was discovered / reported and remains unchanged
The slug uses lowercase letters, numbers, and hyphens, allowing you to tell what the problem is at a glance (such as
```
auth-token-leak
```
,
```
null-pointer-on-empty-list
```
)

Why gather all outputs together? The same logic as features—when future developers check "how that bug was located last time", all three documents are in one place without searching around. Directories for issues and features are located in

easysdd/issues/

and

easysdd/features/

respectively; do not mix them.

{slug}-fix-note.md

is the mandatory output of Phase 3—it must be written regardless of whether the repair is simple or complex. The repair record is not a formality; it is a retrospective credential. Without it, when a similar problem arises next time, you can only infer what was modified from the git log.

All issue documents must include YAML frontmatter (with

doc_type

set to

issue-report

issue-analysis

issue-fix

respectively), which facilitates retrieval by severity, tags, and status using

search-yaml.py

两条路径

Two paths

标准路径（问题复杂或根因不明时）

Standard path (for complex problems or unclear root causes)

阶段	子技能	主导者	产出
1 问题报告	`easysdd-issue-report`	用户描述，AI 引导结构化	`{slug}-report.md`
2 根因分析	`easysdd-issue-analyze`	AI 读代码分析，用户确认	`{slug}-analysis.md`
3 修复验证	`easysdd-issue-fix`	AI 按分析定点修复，用户验证	代码修复 + `{slug}-fix-note.md` + 收尾提交确认

阶段间有人工 checkpoint，理由跟 feature 一样：让用户在每个阶段结束有一次明确把关，防止 AI 一口气从问题跑到代码、跑出来用户才发现走偏。

Phase	Sub-skill	Leader	Output
1 Issue Report	`easysdd-issue-report`	User describes, AI guides structuring	`{slug}-report.md`
2 Root Cause Analysis	`easysdd-issue-analyze`	AI reads code for analysis, user confirms	`{slug}-analysis.md`
3 Repair Verification	`easysdd-issue-fix`	AI performs targeted repair based on analysis, user verifies	Code repair + `{slug}-fix-note.md` + final submission confirmation

There are manual checkpoints between phases, for the same reason as features: to allow users to explicitly review at the end of each phase, preventing AI from running straight from the problem to code and users only realizing it has gone off track after the fact.

快速通道（问题简单、根因一眼确定时）

Fast track (for simple problems with clearly identifiable root causes at a glance)

下面三条同时满足才进快速通道：

AI 读完代码后对根因高度有把握（能明确指出文件:行号 + 原因）
修复改动范围很小（只涉及 1-2 处）
没有跨模块影响风险

流程压缩成：

AI 读代码 → 直接告知根因 + 修复方案 → 用户确认 → AI 修复 → 用户验证通过 → AI 写 {slug}-fix-note.md

只产出一份

{slug}-fix-note.md

，省掉

{slug}-report.md

和

{slug}-analysis.md

。

判定口径：是否进快速通道由

easysdd-issue-report

的启动检查做唯一正式判定。一旦进入标准路径并确认

{slug}-report.md

，后续阶段默认不再二次改判——避免 report / analyze / fix 三个阶段对路径各说各话。

什么时候不能走快速通道：

根因有多个候选，需要排查
修复范围不确定或涉及多个模块
需要先复现问题才能定位
用户希望留下完整的分析存档

All three of the following conditions must be met to enter the fast track:

AI is highly confident about the root cause after reading the code (can clearly point out the file:line number + reason)
The scope of repair changes is very small (only involves 1-2 places)
No risk of cross-module impact

The process is compressed to:

AI reads code → Directly informs root cause + repair plan → User confirms → AI repairs → User verifies success → AI writes {slug}-fix-note.md

Only one

{slug}-fix-note.md

is produced, omitting

{slug}-report.md

and

{slug}-analysis.md

Judgment criteria: The decision to enter the fast track is made solely by the initial check of

easysdd-issue-report

. Once the standard path is entered and

{slug}-report.md

is confirmed, no secondary judgment will be made in subsequent phases—avoiding inconsistent judgments on the path among the report / analyze / fix phases.

When you cannot take the fast track:

Multiple root cause candidates exist and require investigation
The repair scope is uncertain or involves multiple modules
The problem needs to be reproduced first for localization
The user wants to keep a complete analysis archive

路由：用户现在该走哪个子技能

Routing: Which sub-skill should the user proceed with now

进入本技能后先 Glob

easysdd/issues/

，看有没有相关的 issue 目录。不要只听用户口头描述——自己读已有文件才有数。

当前状态	触发哪个子技能
刚发现问题，还没有任何文件	`easysdd-issue-report` （在那里判断走标准还是快速）
`{slug}-report.md` 已存在，没有 `{slug}-analysis.md`	`easysdd-issue-analyze`
`{slug}-analysis.md` 已存在，代码还没改	`easysdd-issue-fix`
代码已改，还没修复验证记录	`easysdd-issue-fix` （走验证环节）
不确定	自己读已有文件，按上表对号入座

如果用户描述的是新功能需求而不是 bug，告诉用户走

easysdd-feature

工作流，本工作流不适用。

After entering this skill, first Glob

easysdd/issues/

to check if there is a relevant issue directory. Do not only rely on the user's verbal description—you must read the existing files to get the full picture.

Current Status	Trigger Which Sub-skill
Just discovered the problem, no files yet	`easysdd-issue-report` (judge whether to take the standard or fast track there)
`{slug}-report.md` exists, no `{slug}-analysis.md`	`easysdd-issue-analyze`
`{slug}-analysis.md` exists, code not modified yet	`easysdd-issue-fix`
Code modified, no repair verification record yet	`easysdd-issue-fix` (proceed to verification step)
Uncertain	Read existing files yourself and match according to the table above

If the user describes a new feature requirement instead of a bug, inform the user to use the

easysdd-feature

workflow, as this workflow is not applicable.

与 feature 工作流的边界

Boundary with feature workflow

issue 处理"本来应该好的东西坏了"——已有代码里的 bug、异常行为、文档错误、性能问题
feature 处理"从来没有的东西要加进来"——新功能、新能力

灰色地带：修 issue 的过程中发现需要新增能力才能真正解决问题——先用 issue 工作流把问题记录和分析做完，再视情况开 feature 工作流。不要在 issue 里偷偷做新功能，理由跟 feature 不在 PR 里偷偷修 bug 一样：混着改让人分不清这次到底改了什么范围。

Issue handles "something that should work but is broken"—bugs in existing code, abnormal behaviors, documentation errors, performance issues
Feature handles "something that never existed and needs to be added"—new functions, new capabilities

Gray area: Discovering that new capabilities need to be added to truly solve the problem during issue repair—first complete the problem recording and analysis using the issue workflow, then start the feature workflow as appropriate. Do not secretly implement new features in issues, for the same reason that features should not secretly fix bugs in PRs: mixing modifications makes it unclear what scope was changed this time.

easysdd-issue

Original

Translation

easysdd-issue

easysdd-issue

文件放哪儿

Where to place files

两条路径

Two paths

标准路径（问题复杂或根因不明时）

Standard path (for complex problems or unclear root causes)

快速通道（问题简单、根因一眼确定时）

Fast track (for simple problems with clearly identifiable root causes at a glance)

路由：用户现在该走哪个子技能

Routing: Which sub-skill should the user proceed with now

与 feature 工作流的边界

Boundary with feature workflow

相关文档

Related documents