Required reading on startup
Before making any judgment or action, first run CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not replace by reading an external AI entry point (see .codestable/reference/execution-conventions.md）。
The instinct for fixing bugs is "find the wrong place, change it, done," but this instinctive path repeatedly creates the same trouble:
- The problem description is changed only in your head and then forgotten—when the bug reappears three months later, there are no reproduction steps on file
- Acting before analyzing the root cause—changing surface symptoms while the deep problem waits to erupt next time
- Fix scope creep—finding one bug and casually changing five places, introducing new problems with no traceability
- No acceptance loop—how do you judge it is fixed? What was fixed? No record
The issue workflow inserts a buffer between "seeing the problem" and "starting to change code":
发现问题 → 清晰记录（report）→ 根因分析（analyze）→ 定点修复 + 验证（fix）
This skill does not write anything; it only looks at which step the current issue has reached and decides which sub-skill to trigger.
Where to put the file
.codestable/issues/{YYYY-MM-DD}-{slug}/
├── {slug}-report.md ← 阶段 1 问题报告
├── {slug}-analysis.md ← 阶段 2 根因分析
└── {slug}-fix-note.md ← 阶段 3 修复记录（必出产物）
Date taken fromthe day the problem was discovered / reportedOnce set, do not change. The slug should make it obvious at a glance what the problem is (auth-token-leak、null-pointer-on-empty-list）。
{slug}-fix-note.md is phase 3 required output—it must be written whether the fix is simple or complex. It is not a ritual, it is a retrospective record: without it, the next time a similar problem comes you can only reverse-engineer it from git log.
All issue documents carry YAML frontmatter (doc_type are respectively issue-report / issue-analysis / issue-fix) to facilitate search-yaml.py retrieval by severity / tags / status.
Two paths
Standard path (problem is complex or root cause is unclear)
| Phase | Sub-skill | Lead | Output |
|---|---|---|---|
| 1 Problem report | cs-issue-report |
User describes, AI guides | {slug}-report.md |
| 2 Root cause analysis | cs-issue-analyze |
AI reads code and analyzes, user confirms | {slug}-analysis.md |
| 3 Fix verification | cs-issue-fix |
AI performs targeted fix per analysis, user verifies | Code + {slug}-fix-note.md + scoped-commit |
There is a human checkpoint between phases—so the user has one clear gate at the end of each phase, preventing the AI from running all the way from problem to code before discovering it went off track.
Fast track (problem is simple, root cause is obvious at a glance)
Belowall simultaneously satisfiedbefore entering:
- After reading the code, the AI is highly confident about the root cause (can clearly point out file:line + reason)
- The fix change is very small (1-2 places)
- No risk of cross-module impact
The process is compressed into: AI reads code → directly states root cause + fix plan → user confirms → AI fixes → user verification passes → AI writes {slug}-fix-note.md. Only one fix-note.mdis produced, saving report and analysis.
Decision criterion: whether to enter the fast track is formally decided solely by the startup check of cs-issue-report . Once on the standard path, by default there is no second re-judgment—avoiding the three phases each saying something different about the path.
Cannottake the fast track: there are multiple root cause candidates / the fix scope involves multiple modules / it needs to be reproduced first to locate / the user wants a complete analysis archived.
Routing
Upon entering this skill, first Glob .codestable/issues/; only by reading the existing files yourself do you have the full picture.
| Current state | Which sub-skill to trigger |
|---|---|
| Just discovered the problem, there are no files at all | cs-issue-report(there, decide whether to go standard or fast) |
report.md already exists, has not analysis.md |
cs-issue-analyze |
analysis.md already exists, the code has not been changed yet |
cs-issue-fix |
| The code has been changed, but the verification record has not been fixed yet | cs-issue-fix(go through verification) |
| Uncertain | Read the existing files yourself and match them against the table above |
What the user is describing isa new feature requirement rather than a bug → tell the user to go through cs-feat。
Boundary with the feature workflow
- issue: something that should have been fine is broken—bugs in existing code / abnormal behavior / documentation errors / performance problems
- feature: something that has never existed is to be added—new features / new capabilities
Gray area: during the process of fixing an issue, it is discovered that a new capability is needed to truly solve it—first use the issue workflow to finish the recording and analysis, then open a feature as appropriate. Do not secretly implement new features in an issue, for the same reason that a feature does not secretly fix bugs in a PR: when changes are mixed together, it is impossible to tell exactly what scope was changed this time.
Related documents
.codestable/reference/system-overview.md— CodeStable system overview.codestable/reference/shared-conventions.md— Shared conventions across stages.codestable/attention.md— CodeStable startup notes and project hard constraints.codestable/requirements/CONTEXT.md+requirements/adrs/— Domain terminology and finalized decisions that may need to be checked during root cause analysis