cs-issue
liuzhengdongfortest/codestable
Bug-fix workflow router: triage issues into report → analyze → fix stages with structured documentation.
What is cs-issue?
Entry point for bug-fix workflows that guides issues from discovery through verification, producing three artifacts (report, analysis, fix-note). Routes to appropriate sub-skills based on existing artifacts and problem complexity, with a fast-track option for simple, well-understood bugs.
- Routes incoming bug reports to correct sub-skill (report/analyze/fix) based on existing artifacts
- Distinguishes between standard multi-stage workflow and fast-track for simple, localized bugs
- Reads existing issue files to determine current workflow stage and next action
- Enforces structured issue documentation with YAML frontmatter for searchability
- Prevents scope creep by separating bug fixes from feature requests
- Requires reading .codestable/attention.md before any action to ensure project context
How to install cs-issue
npx skills add https://github.com/liuzhengdongfortest/codestable --skill cs-issue- CodeStable project structure with .codestable/ directory initialized
- Completion of cs-onboard or existing .codestable/attention.md file
- Read access to .codestable/reference/ documentation and requirements/
How to use cs-issue
- 1.Check .codestable/issues/ directory to see if issue already has report/analysis/fix-note files
- 2.Read existing files to determine current workflow stage
- 3.If no files exist, trigger cs-issue-report to create initial problem report
- 4.If report exists but no analysis, trigger cs-issue-analyze for root-cause investigation
- 5.If analysis exists but code unchanged, trigger cs-issue-fix for implementation and verification
- 6.If unsure of current state, read existing files and match against routing table in skill documentation
Use cases
- User reports 'there's a bug in auth' → router creates issue directory and triggers report stage
- Analysis already exists but code hasn't been modified → router triggers fix stage directly
- Simple one-line bug with obvious root cause → router takes fast-track, skips report/analysis, goes straight to fix
- User describes new feature request → router redirects to cs-feat workflow instead
- Team needs to audit past bug fixes → router's YAML frontmatter enables severity/tag-based search
- Development teams using CodeStable workflow system
- Developers handling bug reports and maintenance work
- Teams needing structured issue tracking with analysis before coding
- Projects requiring audit trails and fix verification records
cs-issue FAQ
Use fast-track only when: (1) root cause is immediately clear from code inspection, (2) fix requires 1-2 changes only, (3) no cross-module impact risk. Otherwise use standard path. The decision is made once in cs-issue-report and not revisited.
Redirect to cs-feat workflow. A bug is existing code that's broken; a feature is new capability that doesn't exist yet. Don't mix them in the same issue.
Each file serves as a checkpoint and audit trail. Report captures the problem statement, analysis documents root cause, fix-note records what changed and verification results. Without them, similar bugs recur with no historical context.
Use a short, descriptive identifier like 'auth-token-leak' or 'null-pointer-on-empty-list' that makes the issue type immediately obvious. Date is fixed to discovery date and never changes.
Only if you meet all fast-track criteria (clear root cause, minimal changes, no cross-module risk). Otherwise, analysis is mandatory—it prevents repeated bugs and provides future reference.
Full instructions (SKILL.md)
Source of truth, from liuzhengdongfortest/codestable.
name: cs-issue description: 修 bug 的子流程入口，把"发现问题"走到验证修复闭环，留下 report / analysis / fix-note 三份文件。触发：用户说"修 bug"、"有个问题"、"修复 XX"。只做路由，根据已有产物走 report / analyze / fix。简单问题走快速通道。
cs-issue
启动必读
开始任何判断或动作前，先读取 .codestable/attention.md；缺失则视为骨架不完整，提示先补齐或运行 cs-onboard，不要回退到外部 AI 入口文件。
修 bug 直觉是"找到错的地方改了完事"，但这个直觉路径反复制造同样的麻烦：
- 问题描述只在脑子里改完就忘——三个月后 bug 再现没复现步骤留存
- 根因没分析就动手——改了表面现象深层问题等下次爆发
- 修复范围扩散——发现一个 bug 顺手改五处引入新问题，无法追溯
- 没验收闭环——怎么判断改好了？改好了什么？没记录
issue 工作流在"看到问题"和"动手改代码"之间塞缓冲：
发现问题 → 清晰记录（report）→ 根因分析（analyze）→ 定点修复 + 验证（fix）
本技能不写任何东西，只看当前 issue 走到哪步、决定触发哪个子技能。
文件放哪儿
.codestable/issues/{YYYY-MM-DD}-{slug}/
├── {slug}-report.md ← 阶段 1 问题报告
├── {slug}-analysis.md ← 阶段 2 根因分析
└── {slug}-fix-note.md ← 阶段 3 修复记录（必出产物）
日期取发现 / 提报问题当天定了不动。slug 能一眼看出是什么问题（auth-token-leak、null-pointer-on-empty-list）。
{slug}-fix-note.md 是阶段 3 必出产物——无论修复简单还是复杂都要写。它不是仪式，是回溯凭证：没有它下次类似问题来你只能从 git log 反推。
所有 issue 文档带 YAML frontmatter（doc_type 分别为 issue-report / issue-analysis / issue-fix）便于 search-yaml.py 按 severity / tags / status 检索。
两条路径
标准路径（问题复杂或根因不明）
| 阶段 | 子技能 | 主导 | 产出 |
|---|---|---|---|
| 1 问题报告 | cs-issue-report | 用户描述，AI 引导 | {slug}-report.md |
| 2 根因分析 | cs-issue-analyze | AI 读代码分析，用户确认 | {slug}-analysis.md |
| 3 修复验证 | cs-issue-fix | AI 按分析定点修复，用户验证 | 代码 + {slug}-fix-note.md + scoped-commit |
阶段间有人工 checkpoint——让用户在每阶段结束有一次明确把关，防止 AI 一口气从问题跑到代码跑出来才发现走偏。
快速通道（问题简单、根因一眼确定）
下面同时满足才进：
- AI 读完代码后对根因高度有把握（能明确指出 file:line + 原因）
- 修复改动很小（1-2 处）
- 无跨模块影响风险
流程压缩成：AI 读代码 → 直接告知根因 + 修复方案 → 用户确认 → AI 修复 → 用户验证通过 → AI 写 {slug}-fix-note.md。只产出一份 fix-note.md，省掉 report 和 analysis。
判定口径：是否进快速通道由 cs-issue-report 的启动检查做唯一正式判定。一旦进标准路径默认不再二次改判——避免三个阶段对路径各说各话。
不能走快速通道：根因有多个候选 / 修复范围涉及多模块 / 需要先复现才能定位 / 用户希望留完整分析存档。
路由
进入本技能先 Glob .codestable/issues/，自己读已有文件才有数。
| 当前状态 | 触发哪个子技能 |
|---|---|
| 刚发现问题，没有任何文件 | cs-issue-report（那里判断走标准还是快速） |
report.md 已存在，没 analysis.md | cs-issue-analyze |
analysis.md 已存在，代码还没改 | cs-issue-fix |
| 代码已改，还没修复验证记录 | cs-issue-fix（走验证） |
| 不确定 | 自己读已有文件按上表对号 |
用户描述的是新功能需求而不是 bug → 告诉用户走 cs-feat。
与 feature 工作流的边界
- issue：本来应该好的东西坏了——已有代码里的 bug / 异常行为 / 文档错误 / 性能问题
- feature：从来没有的东西要加进来——新功能 / 新能力
灰色地带：修 issue 过程中发现需要新增能力才能真正解决——先用 issue 工作流把记录和分析做完，再视情况开 feature。不在 issue 里偷偷做新功能，理由跟 feature 不在 PR 里偷偷修 bug 一样：混着改分不清这次到底改了什么范围。
相关文档
.codestable/reference/system-overview.md— CodeStable 体系总览.codestable/reference/shared-conventions.md— 跨阶段共享口径.codestable/attention.md— CodeStable 启动注意事项和项目硬约束.codestable/requirements/CONTEXT.md+requirements/adrs/— 根因分析时可能要查的领域术语与拍板决策
Related skills
More from liuzhengdongfortest/codestable and the wider catalog.
cs-issue-analyze
Analyze bug root causes by reading code and reports, then present 2-3 fix options for user approval.
cs-issue-fix
Fix confirmed bugs by implementing the validated solution, verify the fix, and document in {slug}-fix-note.md.
cs-issue-report
Structured issue reporting through dialogue—capture reproducible bugs and route to fast-track or standard analysis.
cs-learn
Capture engineering lessons—pitfalls and best practices—into searchable learning docs for your team.
cs-libdoc
Generate reference documentation for library public APIs with checklist tracking, sourced directly from code.
cs-note
把"短到不值得起一份文件、但 AI 每次启动 CodeStable 技能都必须知道"的项目碎片知识追加到 `.codestable/attention.md` 的固定分节里——比如编译特殊 flag、运行前要先起的服务、路径陷阱、命令别名、环境变量约定。触发：用户说"记一笔"、"加到 attention.md"、"项目要 X 才能编译"、"以后每次都得 Y"，或刚踩到一个一句话能讲清的项目特殊设置。