cs-issue
Intuitively, fixing a bug is "find the wrong place and fix it", but this intuitive path repeatedly creates the same troubles:
- The problem description only exists in your mind and is forgotten after the fix — three months later, the same bug reappears with no reproduction steps retained
- You start fixing without analyzing the root cause — you fix the surface phenomenon, while the deep problem remains and waits to break out next time
- The scope of repair expands — you find one bug and casually modify five places, introducing new problems with no way to trace which modification caused them
- No acceptance closed loop — how to determine if the fix is successful? What has been fixed? There is no record
The issue workflow inserts a buffer between "seeing the problem" and "starting to modify code":
Problem found → Clear documentation (report) → Root cause analysis (analyze) → Targeted repair + Verification (fix)
This skill itself does not generate any content; it only checks which stage the current issue has reached and decides which sub-skill to trigger.
Where to store files
All artifacts of the entire issue workflow are gathered under
, with an independent directory for each issue:
codestable/
└── issues/
└── {issue}/
├── {slug}-report.md ← Problem report for Phase 1
├── {slug}-analysis.md ← Root cause analysis for Phase 2
└── {slug}-fix-note.md ← Repair record for Phase 3 (mandatory artifact)
The directory is named
YYYY-MM-DD-{English slug}
:
- The date is the day the problem was found / reported and remains unchanged
- The slug uses lowercase letters, numbers, and hyphens, making it easy to identify the problem at a glance (e.g., ,
null-pointer-on-empty-list
Why gather all artifacts 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 needing to search around. Issue and feature directories are separately located in
and
; do not mix them.
is the
mandatory artifact for Phase 3 — it must be written regardless of whether the repair is simple or complex. The repair record is not a formality but a retrospective credential: without it, when a similar problem arises next time, you can only reverse-engineer what was modified from the git log.
All issue documents must include YAML frontmatter (with
set to
/
/
respectively) to facilitate retrieval by severity, tags, and status using
.
Two paths
Standard path (for complex problems or unclear root causes)
| Phase | Sub-skill | Leader | Output |
|---|
| 1 Problem 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 fix + + 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 the AI from jumping directly from the problem to code and deviating before the user notices.
Fast track (for simple problems with clearly identifiable root causes)
All three of the following conditions must be met to enter the fast track:
- After reading the code, the AI is highly confident about the root cause (can clearly specify 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 fixes → 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 in
. Once the standard path is entered and
is confirmed, no secondary judgment will be made in subsequent phases — to avoid inconsistent path decisions across the report / analyze / fix phases.
When the fast track cannot be used:
- 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 retain 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 rely solely on the user's verbal description — you must read the existing files to get accurate information.
| Current Status | Trigger Which Sub-skill |
|---|
| Problem just discovered, no files yet | (determine standard or fast track there) |
| exists, does not | |
| exists, code not modified yet | |
| Code modified, no repair verification record | (proceed to verification step) |
| Uncertain | Read existing files 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
- Issues deal with "something that should work but is broken" — bugs in existing code, abnormal behavior, documentation errors, performance issues
- Features deal with "something that never existed and needs to be added" — new functions, new capabilities
Gray area: If you find that new capabilities are needed to truly solve the problem during issue repair — first complete the problem documentation and analysis using the issue workflow, then start the feature workflow as needed. Do not secretly implement new features within an issue, 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
codestable/reference/system-overview.md
codestable/reference/shared-conventions.md
- — Full project code specifications, which must also be followed during issue repair
codestable/architecture/DESIGN.md