cs-issue-analyze

At this point, the user has clearly described the issue. Your task is to identify the root cause by actually reading the code — not by inferring in your mind or guessing based on the report. Reading code is the core action of this phase; any analysis written without doing this is worthless.

After analysis, do not start fixing directly — present 2-3 repair solutions to the user and let them choose. Reason: There are often multiple ways to fix a root cause, with varying impact scopes, side effects, and modification ranges. This is a decision that the user should make, not something the AI should decide for them.

See Section 0 of
codestable/reference/shared-conventions.md
and the "Where to place files" section of
cs-issue
for shared paths and naming conventions.

Startup Checks

1. Issue report exists and is confirmed

Read

{slug}-report.md

in the issue directory, confirm that the frontmatter has

doc_type=issue-report

and

status=confirmed

, and all 5 sections have content. If it is incomplete or the status is not confirmed, redirect to

cs-issue-report

first.

cs-issue-report

has determined to follow the standard path, complete the root cause analysis according to the standard path in this phase, and do not re-judge the fast track.

2. Breakpoint Recovery

{slug}-analysis.md

already exists, check which of the 5 sections have substantial content:

All filled but
```
status=draft
```
→ Last time you finished writing but didn't align with the user, jump to checkpoint
Partially filled → Report "Last analysis reached Step X, I will continue from Step Y", and fill in the missing sections

3. Read All Context

Full content of the issue report
```
AGENTS.md
```
Related files mentioned in the report (find using Glob / Grep, don't rely only on the description in the report)
```
codestable/architecture/DESIGN.md
```
(if cross-module issues are involved)
Archive Retrieval (as needed) — Only search if the module related to the issue has archive records (skip if the directory is empty or irrelevant to the issue). Search uniformly in
```
codestable/compound/
```
, filter by
```
doc_type
```
as needed:
- Full search:
```
python codestable/tools/search-yaml.py --dir codestable/compound --query "{issue keywords}"
```
- Only view tricks: Append
```
--filter doc_type=trick --filter status=active
```
  — If hit, mark the reference at the beginning of the analysis
- Only view explorations: Append
```
--filter doc_type=explore
```
  — If hit, mark the historical exploration conclusion
- Only view pitfalls (learning experiences): Append
```
--filter doc_type=learning --filter track=pitfall
```
  — If hit, mark the historical pitfall

Five Steps of Analysis

Read the code actually in each step, do not rely on speculation.

Step 1: Locate the Problematic Code

According to the "Involved modules / functions" and "Reproduction steps" in the report, find relevant code using Grep / Glob:

Search for function names, class names, file names mentioned in the report
Trace along the call chain (from the entry triggered by the user)
Focus on: conditional branches, boundary value handling, state updates, asynchronous logic, data flow

Record the key locations identified:

{file}:{line number} — {description of what this does}

Step 2: Restore the Failure Path

Compare the reproduction steps, walk through the code execution path in your mind (or run it actually):

What did the user trigger → Which function was called → How did the data flow → Where did it branch incorrectly
Describe the divergence point between the "correct path" and "failure path"
Divergence point = Root cause candidate

Step 3: Confirm the Root Cause

Single root cause vs multiple root causes: If there are multiple root causes, list them one by one and explain their priority
Root cause classification (helps locate the repair scope later):
- Logic error: Incorrect conditional judgment, missing boundary value handling
- State pollution: Side effects in some place affect subsequent processes
- Data format: Input / output format assumptions do not match reality
- Concurrency / race condition: Asynchronous order or shared state issues
- Configuration / environment: Depends on an unstable configuration item
- Missing defense: No handling of null / undefined / empty lists and other boundaries

Step 4: Impact Assessment

Impact scope: Does it only affect the scenario described in the report, or will it affect more scenarios?
Potential victims: Which other functions / modules may be affected by the same root cause?
Data integrity: Will this bug cause data corruption or state inconsistency?
Severity review: Compare with the P0/P1/P2/P3 in the report, is adjustment needed?

Why review severity? The user's judgment in the report phase is based on phenomena. After analysis, you can see the impact scope — often you will find the problem is more serious than it seems (a seemingly P2 small bug actually affects the integrity of core data) or less serious.

Step 5: Repair Solution Options

List 2-3 repair directions, explain each:

What to do: Where to modify, how to modify (describe at the code level, no need to write code)
Advantages: Why this modification is good
Disadvantages / risks: What side effects may be caused by this modification
Impact scope: Which files will be touched, will it affect other functions

Recommended solution: Pick one of the 2-3 options and explain the recommendation reason (usually: smallest modification scope + most direct root cause + least side effects).

Root Cause Analysis Template

After analysis, write into the file (see the "Where to place files" section of

cs-issue

for the path):

markdown

---
doc_type: issue-analysis
issue: {issue directory name}
status: draft
root_cause_type: logic | state-pollution | data-format | concurrency | config | missing-guard
related: [{slug-report.md relative path}]
tags: []
---

# Root Cause Analysis of {Issue Brief}

## 1. Issue Location

| Key Location | Description |
|---|---|
| `{file}:{line number}` | {What this does, why there is a problem} |
| `{file}:{line number}` | ... |

## 2. Failure Path Restoration

**Normal Path**:
{User does A → calls B → data passes through C → result D (meets expectation)}

**Failure Path**:
{User does A → calls B → takes wrong branch at C due to E → result F (does not meet expectation)}

**Divergence Point**: `{file}:{line number}` — {Why it went wrong here}

## 3. Root Cause

**Root Cause Type**: {Logic error / State pollution / Data format / Concurrency race condition / Configuration environment / Missing defense}

**Root Cause Description**:
{A paragraph explaining why this problem occurs, understandable to someone who hasn't seen the code}

**Multiple Root Causes**: {Yes / No. If yes, list and explain priority}

## 4. Impact Scope

- **Impact Scope**: {Only affects the reported scenario / Also affects X, Y, Z scenarios}
- **Potential Victim Modules**: {List other modules or functions that may be affected}
- **Data Integrity Risk**: {Yes / No. If yes, explain the risk content}
- **Severity Review**: {Maintain P? / Adjust to P?, reason}

## 5. Repair Solutions

### Solution A: {Solution Name}

- **What to do**: {Where to modify, how to modify}
- **Advantages**: {...}
- **Disadvantages / Risks**: {...}
- **Impact Scope**: {Which files will be modified, will it affect other functions}

### Solution B: {Solution Name}

- **What to do**: {...}
- ...

### Recommended Solution

**Recommended Solution {A / B}**, Reason: {Smallest modification scope / Most direct root cause / Least side effects + specific explanation}

checkpoint: Align with User

After writing

{slug}-analysis.md

, do not start fixing directly. Conduct an alignment:

Verbally summarize the "root cause" and "recommended solution" to the user (do not let the user read the entire file — TA is already waiting for conclusions)
Ask the user: "Is the root cause judgment accurate? Do you agree with the recommended repair solution, or do you want to choose another direction?"
Only trigger Phase 3 after the user clearly confirms the solution

Exit Conditions

YAML frontmatter exists,
```
doc_type=issue-analysis
```
,
```
issue
```
matches the current issue directory
All 5 sections of the root cause analysis are filled
Specific code locations (at
```
{file}:{line number}
```
granularity) are located
Failure path restoration is clear
Impact assessment is completed
At least 2 repair solutions are listed and a recommendation is given
User clearly confirms the solution: "Analysis is accurate, fix with Solution X"
After user confirmation,
```
status
```
in frontmatter is changed to
```
confirmed
```

After Exit

Tell the user: "Root cause analysis is ready, solution is confirmed. Next is Phase 3: Repair Verification. You can trigger the

cs-issue-fix

skill to start repairing."

Do not start modifying code on your own — same reason as other phases: Running continuously across phases without pausing will leave no time for the user to review.

Common Pitfalls

Writing root cause as "May be a problem somewhere" — Must locate to specific file:line number
Inferring root cause from issue description without reading code — Must actually use Grep / Read
Listing only one repair solution — Provide at least two options for the user
Starting to modify code directly after analysis — Must wait for user confirmation of the solution
Writing impact scope as "May affect other functions" — Specify which functions / modules exactly
Always maintaining the original severity level in review — Carefully check the impact scope, adjust if it really needs to be upgraded

cs-issue-analyze

NPX Install

Tags

SKILL.md Content (Chinese)

cs-issue-analyze

Startup Checks

1. Issue report exists and is confirmed

2. Breakpoint Recovery

3. Read All Context

Five Steps of Analysis

Step 1: Locate the Problematic Code

Step 2: Restore the Failure Path

Step 3: Confirm the Root Cause

Step 4: Impact Assessment

Step 5: Repair Solution Options

Root Cause Analysis Template

checkpoint: Align with User

Exit Conditions

After Exit

Common Pitfalls