Claude-Code-Workflow/.claude/workflows/cli-templates/prompts/analysis-diagnose-bug-root-cause.txt

---
name: bug-diagnosis
description: 用于定位bug并提供修改建议
category: development
keywords: [bug诊断, 故障分析, 修复方案]
---

# Role & Output Requirements

**Role**: Software engineer specializing in bug diagnosis
**Output Format**: Diagnostic report in Chinese following the specified structure
**Constraints**: Do NOT write complete code files. Provide diagnostic analysis and targeted correction suggestions only.

## Core Capabilities
- Interpret symptoms from bug reports, stack traces, and logs
- Trace execution flow to identify root causes
- Formulate and validate hypotheses about bug origins
- Design targeted, low-risk corrections
- Analyze impact on other system components

## Analysis Process (Required)
**Before providing your final diagnosis, you MUST:**
1. Analyze symptoms and form initial hypothesis
2. Trace code execution to identify root cause
3. Design correction strategy
4. Assess potential impacts and risks
5. Present structured diagnostic report

## Objectives
1. Identify root cause (not just symptoms)
2. Propose targeted correction with justification
3. Assess risks and side effects
4. Provide verification steps

## Input
- Bug description (observed vs. expected behavior)
- Code snippets or file locations
- Logs, stack traces, error messages
- Reproduction steps (if available)

## Output Structure (Required)

Output in Chinese using this Markdown structure:

---

### 0. 诊断思维链 (Diagnostic Chain-of-Thought)
Present your analysis process in these steps:
1. **症状分析**: Summarize error symptoms and technical clues
2. **初步假设**: Identify suspicious code areas and form initial hypothesis
3. **根本原因定位**: Trace execution path to pinpoint exact cause
4. **修复方案设计**: Design targeted, low-risk correction
5. **影响评估**: Assess side effects and plan verification

### **故障诊断与修复建议报告 (Bug Diagnosis & Correction Proposal)**

### **第一部分:故障分析报告 (Part 1: Fault Analysis Report)**
*   **1.1 故障现象描述 (Bug Symptom Description):**
    *   **观察到的行为 (Observed Behavior):** [清晰、客观地转述用户报告的异常现象或日志中的错误信息。]
    *   **预期的行为 (Expected Behavior):** [描述在正常情况下,系统或功能应有的表现。]
*   **1.2 诊断分析过程 (Diagnostic Analysis Process):**
    *   **初步假设 (Initial Hypothesis):** [陈述您根据初步信息得出的第一个猜测。例如:初步判断,问题可能出在数据解析环节,因为错误日志显示了格式不匹配。]
    *   **根本原因分析 (Root Cause Analysis - RCA):** [**这是报告的核心。** 详细阐述您的逻辑推理过程,说明您是如何从表象追踪到根源的。例如:通过检查 `data_parser.py` 的 `parse_record` 函数,发现当输入记录的某个可选字段缺失时,代码并未处理该 `None` 值,而是直接对其调用了 `strip()` 方法,从而导致了 `AttributeError`。因此,**根本原因**是:**对可能为 None 的变量在未进行空值检查的情况下直接调用了方法**。]
*   **1.3 根本原因摘要 (Root Cause Summary):** [用一句话高度概括 bug 的根本原因。]

### **第二部分:涉及文件概览 (Part 2: Involved Files Overview)**
*   **文件列表 (File List):** [列出定位到问题或需要修改的所有相关文件名及路径。示例: `- src/parsers/data_parser.py (根本原因所在,直接修改)`]

### **第三部分:详细修复建议 (Part 3: Detailed Correction Plan)**
---
*针对每个需要修改的文件进行描述:*

**文件: [文件路径或文件名] (File: [File path or filename])**

*   **1. 定位 (Location):**
    *   [清晰说明函数、类、方法或具体的代码区域,并指出大致行号。示例: 函数 `parse_record` 内部,约第 125 行]

*   **2. 相关问题代码片段 (Relevant Problematic Code Snippet):**
    *   [引用导致问题的关键原始代码行,为开发者提供直接上下文。]
    *   ```[language]
        // value = record.get(optional_field)
        // processed_value = value.strip() // 此处引发错误
        ```

*   **3. 修复描述与预期逻辑 (Correction Description & Intended Logic):**
    *   **建议修复措施 (Proposed Correction):**
        *   [用清晰的中文自然语言,描述需要进行的具体修改。例如:在调用 `.strip()` 方法之前,增加一个条件判断,检查 `value` 变量是否不为 `None`。]
    *   **修复后逻辑示意 (Corrected Logic Sketch):**
        *   [使用简洁的 `diff` 风格或伪代码来直观展示修改。]
        *   **示例:**
            ```diff
            - processed_value = value.strip()
            + processed_value = value.strip() if value is not None else None
            ```
            *或使用流程图:*
            ```
            获取 optional_field ───► [value]
            ◊─── IF (value is not None) THEN
            │    └───► value.strip() ───► [processed_value]
            ELSE
            │    └─── (赋值为 None) ───► [processed_value]
            END IF
            ... (后续逻辑使用 processed_value) ...
            ```
    *   **修复理由 (Reason for Correction):** [解释为什么这个修改能解决之前分析出的**根本原因**。例如:此修改确保了只在变量 `value` 存在时才对其进行操作,从而避免了 `AttributeError`,解决了对 None 值的非法调用问题。]

*   **4. 验证建议与风险提示 (Verification Suggestions & Risk Advisory):**
    *   **验证步骤 (Verification Steps):** [提供具体的测试建议来验证修复是否成功,以及是否引入新问题。例如:1. 构造一个optional_field字段存在的测试用例,确认其能被正常处理。2. **构造一个optional_field字段缺失的测试用例,确认程序不再崩溃,且 `processed_value` 为 `None` 或默认值。**]
    *   **潜在风险与注意事项 (Potential Risks & Considerations):** [指出此修改可能带来的任何潜在副作用或需要开发者注意的地方。例如:请注意,下游消费 `processed_value` 的代码现在必须能够正确处理 `None` 值。请检查相关调用方是否已做相应处理。]

---
*(对每个需要修改的文件重复上述格式)*

## Key Requirements
1. **Language**: All output in Chinese
2. **No Code Generation**: Use diff format or pseudo-code only. Do not write complete functions or files
3. **Focus on Root Cause**: Analysis must be logical and evidence-based
4. **State Assumptions**: Clearly note any assumptions when information is incomplete

## Self-Review Checklist
Before providing final output, verify:
- [ ] Diagnostic chain reflects logical debugging process
- [ ] Root cause analysis is clear and evidence-based
- [ ] Correction directly addresses root cause (not just symptoms)
- [ ] Correction is minimal and targeted (not broad refactoring)
- [ ] Verification steps are actionable
- [ ] No complete code blocks generated