SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscs-issue-report

cs-issue-report

Office & productivity

View repository

Updated 10-15 20:30

About this skill

cs-issue-report

Required reading on startup

Before making any judgment or taking any action, first execute the CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not substitute by reading an external AI entry point (see .codestable/reference/execution-conventions.md）。

This stage does two things: turn the problem in the user's head into a structured record + determine whether to take the standard path or the fast track.

Core principle: record only the phenomenon, not the root cause. If the user says "I think it's a problem with component XX" — note down "user suspects component XX" as a clue, but do not follow along discussing the root cause. The root cause must be confirmed in stage 2 by actually reading the code, not guessed in your head. A report mixed with root-cause speculation will mislead stage 2 and make the analyst circle around the wrong clue.

For shared paths and naming conventions, see .codestable/reference/shared-conventions.md Section 0 and cs-issue 's "where files go".

Startup checks

  1. Confirm it is a bug, not a new feature request—— for someone describing "I want to add X feature", tell them to go to cs-feat
  2. Check whether there is a related issue directory——Glob .codestable/issues/, and if there is a similar problem, first confirm with the user whether to create a new one or update
  3. Fast-track judgment (the only formal decision point)—— follow the user's clue,read the relevant code(Grep / Read to locate):
    • Can determine the root cause at a glance(can give {文件}:{行号}, the fix is small, 1-2 changes, no risk of cross-module impact) → tell the user "I have seen where the problem is, and we can take the fast track: directly tell you the root cause and fix plan; once you confirm, I will fix it immediately; after the fix you verify, and only write one {slug}-fix-note.md". After agreeing, trigger cs-issue-fix(fast-track mode)
    • Cannot(there are multiple candidate root causes / uncertain / need more reproduction information) → take the standard path to make a complete problem report. After entering the standard path, by default there is no second re-judgment
  4. Determine the issue directory name—— agree on the slug with the user, use today for the date prefix (environment info currentDate). If the directory does not exist, create it. The fast track also needs an issue directory,{slug}-fix-note.md put there

5 must-answer questions

Ask them one by one in order,do not throw out 5 at once—— if you throw out multiple at once, the user will only answer the easiest one, and the deeper ones will be missed. Do an ambiguity check after each question; if it does not pass, keep asking.

1. What is the problem? What phenomenon is seen?

Expect specific abnormal behavior: "after clicking the submit button, a blank popup appeared" is a hundred times more useful than "the submit function has a problem".

Vague signals: "sometimes it errors", "it feels wrong" → ask follow-ups: "specifically when", "specifically what is wrong".

Red line:do not let the user describe the root cause. If "it should be because of XXX" appears — record the phenomenon, leave the root cause for stage 2.

2. How to reproduce?

Expect minimal reproduction steps: go to XX page → enter YY → click ZZ → see the problem phenomenon.

Vague signals: "not stably reproducible", "sometimes it works and sometimes it does not" → ask follow-ups about reproduction frequency and differences in conditions. If it is indeed unstable, write down the known trigger conditions and reproduction rate.

"Cannot reproduce" is also a valid answer — write "currently cannot reproduce stably, observed only once under X situation"; do not force steps together.

3. Expected behavior vs actual behavior

Expect two statements:

  • Expected: I thought that after doing A, B should happen
  • Actual: but C actually happened

Do not merge into one sentence. People who analyze it merged into one sentence like "the button doesn't work properly" don't know what "properly" looks like.

4. Environment information

Minimum collection:In which module / functional area it was found、Related files or functions (if the user knows them)。

Optional: operating system, browser version, runtime environment (dev / prod), whether related code has been changed recently.

If the user says "I don't know which file" — write "TBD" and check during phase 2 analysis.

5. Severity and priority

  • P0 Blocker: core functionality is completely broken, affects all users, must be fixed immediately
  • P1 Critical: core functionality is impaired but there is a workaround, fix as soon as possible
  • P2 Medium: non-core functionality or affects a small number of users, fix within the plan
  • P3 Minor: UI flaw / edge case / better implementation exists, fix when free

If the user is unsure, recommend one for them but let the user make the final call.

Problem report template

---
doc_type: issue-report
issue: {issue 目录名}
status: draft
severity: P0 | P1 | P2 | P3
summary: {问题现象一句话}
tags: []
---

# {问题简述} Issue Report

## 1. 问题现象

{用户描述的具体异常表现，纯现象描述，不含根因推测}

## 2. 复现步骤

1. {步骤 1}
2. {步骤 2}
3. 观察到：{问题现象}

复现频率：{稳定 / 概率（约 X%） / 暂无法稳定}

## 3. 期望 vs 实际

**期望行为**：{做了 A 应该发生 B}

**实际行为**：{但实际发生了 C}

## 4. 环境信息

- 涉及模块 / 功能：{模块名或功能描述}
- 相关文件 / 函数：{已知 file:line 或"待定"}
- 运行环境：{dev / staging / prod / 不确定}
- 其他上下文：{OS、浏览器、最近改动等，没有写"无"}

## 5. 严重程度

**{P0 / P1 / P2 / P3}** — {一句话理由}

## 备注

{可选：截图描述、日志片段等}

Exit conditions

  • frontmatter is complete (doc_type=issue-report / issue consistent / severity and summary non-empty / tags ≥ 1）
  • all 5 questions have specific answers (related files in the environment may be "TBD")
  • the problem symptom is a pure symptom description, with no root cause speculation mixed in
  • expected vs actual are written explicitly separately
  • reproduction steps are executable ("cannot reproduce reliably" is also explained)
  • the user explicitly says "the report is good, proceed to the next step"
  • frontmatter status: confirmed

After exit

Tell the user: "The problem report is ready. The next step is phase 2 root cause analysis, trigger cs-issue-analyze。"

Don't casually start analyzing root causes yourself — the manual checkpoint between phases is a hard workflow constraint.

Common pitfalls

  • The user says "it might be a problem with XX" and you follow along discussing root causes — wrong, that's phase 2
  • The reproduction steps are too vague ("do something in the user interface") and you let it pass — force out executable steps
  • Expected and actual are mixed in one paragraph — they must be explicitly separated
  • Severity is left blank — give a default value or write "None"
  • Listing all 5 questions as a checklist and dumping them on the user to fill in — converse question by question, otherwise the deep ones will all be missed