easysdd-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
All outputs of the entire issue workflow are gathered under
, 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 ,
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
and
respectively; do not mix them.
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
set to
/
/
respectively), which facilitates retrieval by severity, tags, and status using
.
Two paths
Standard path (for complex problems or unclear root causes)
| Phase | Sub-skill | Leader | Output |
|---|
| 1 Issue Report | | User describes, AI guides structuring | |
| 2 Root Cause Analysis | | AI reads code for analysis, user confirms | |
| 3 Repair Verification | | AI performs targeted repair based on analysis, user verifies | Code repair + + 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)
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
is produced, omitting
and
.
Judgment criteria: The decision to enter the fast track is made solely by the initial check of
. Once the standard path is entered and
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
After entering this skill, first Glob
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 | (judge whether to take the standard or fast track there) |
| exists, no | |
| exists, code not modified yet | |
| Code modified, no repair verification record yet | (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
workflow, as this workflow is not applicable.
Boundary with feature workflow
- 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.
Related documents
- — Root skill of the easysdd family, scenario routing is located there
easysdd/reference/shared-conventions.md
- — Project-wide code specifications, which must also be followed during issue repair
easysdd/architecture/DESIGN.md