piv-investigate-issue

调查 Issue #$ARGUMENTS（根因分析）

目标

调查此代码库中的 GitHub Issue #$ARGUMENTS，找出根因，并记录调查结果，供后续实现参考。

前提条件：

• 在具有 GitHub origin 的本地 Git 代码库中工作
• 已安装并完成身份验证的 GitHub CLI（gh auth status）
• 此代码库中的有效 GitHub Issue ID

调查流程

1. 获取 GitHub Issue 详情

使用 GitHub CLI 检索 Issue 信息：

gh issue view $ARGUMENTS

此命令会获取：

• Issue 标题和描述
• 报告者和创建日期
• 标签和状态
• 评论和讨论

2. 探索代码库 — 并行展开调查

并行分派专门的 Agent（在一条消息中调用多个 Task），以加快探索速度，并避免大量搜索结果占用主上下文：

• codebase-analyst — 端到端追踪受影响代码的工作方式：集成点、数据流、状态/副作用、错误处理。返回精确的 file:line 引用，不提供建议。
• research-agent（第二位探索者）— 查找相关代码的位置和可借鉴的模式：Issue 中的错误字符串、相关函数/模块、类似实现、现有测试模式。

在分析根因前，将调查结果汇总成一份简短的索引（file:line + 重要性说明）。（这是应用于诊断的并行子 Agent 展开调查方式。）

3. 回顾近期历史 — 问题何时引入？

检查受影响区域的近期变更，并确定 Bug 是何时引入的： !git log --oneline -20 -- [relevant-paths]

git blame -L <start>,<end> <affected-file>   # who/when introduced the suspect lines

判断这是近期的回归问题、长期存在的 Bug，还是原有行为 — 这会影响修复方式和风险。

4. 调查根因 — 用证据进行 5 Whys 分析

不要停留在表面症状。持续追问为什么 → 因为，直到找到具体且可修复的代码，并用 file:line 证据支持每一步：

WHY does <symptom> happen? → because <cause A>   (evidence: file.ts:123 — <snippet>)
WHY <cause A>?             → because <cause B>   (evidence: file.ts:456 — <snippet>)
… ROOT CAUSE: <the exact code/logic to change>  (evidence: file.ts:789 — <snippet>)

留意：输入验证缺失、未处理的边界情况、竞争/时序问题、错误假设、缺少错误处理、集成不匹配。

5. 评估影响

确定：

• 此问题的影响范围有多广？
• 哪些功能会受到影响？
• 是否有变通方法？
• 严重程度如何？
• 是否可能导致数据损坏或安全问题？

6. 提出修复方案

设计解决方案：

• 需要做哪些改动？
• 将修改哪些文件？
• 修复策略是什么？
• 是否有其他方案？
• 需要进行哪些测试？
• 是否存在风险或副作用？

输出：创建 RCA 文档

将分析保存为：docs/issues/issue-$ARGUMENTS.md

RCA 文档的必需结构

# Root Cause Analysis: GitHub Issue #$ARGUMENTS

## Issue Summary

- **GitHub Issue ID**: #$ARGUMENTS
- **Issue URL**: [Link to GitHub issue]
- **Title**: [Issue title from GitHub]
- **Reporter**: [GitHub username]
- **Status**: [Current GitHub issue status]

## Assessment

Each value needs a one-line reason grounded in the investigation (not a guess):

| Metric | Value | Reasoning |
|--------|-------|-----------|
| Severity | Critical/High/Medium/Low | user impact · workaround · scope of failure |
| Complexity | Low/Medium/High | files touched · integration points · risk |
| Confidence | High/Medium/Low | evidence quality · unknowns · assumptions |

> **Confidence is the human-attention signal:** LOW confidence = a human should look before the fix runs. Say it honestly.

## Problem Description

[Clear description of the issue]

**Expected Behavior:**
[What should happen]

**Actual Behavior:**
[What actually happens]

**Symptoms:**
- [List observable symptoms]

## Reproduction

**Steps to Reproduce:**
1. [Step 1]
2. [Step 2]
3. [Observe issue]

**Reproduction Verified:** [Yes/No]

## Root Cause

### Affected Components

- **Files**: [List of affected files with paths]
- **Functions/Classes**: [Specific code locations]
- **Dependencies**: [Any external deps involved]

### Analysis

[Detailed explanation of the root cause]

**Evidence Chain (5 Whys):**

WHY <症状> → 因为 <原因> （证据：file:line — 代码片段） … ROOT CAUSE: <确切且可修复的问题> （证据：file:line — 代码片段）

**Why This Occurs:**
[Explanation of the underlying issue]

**Code Location:**

[文件路径:行号] [展示问题的相关代码片段]

### Related Issues

- [Any related issues or patterns]

## Impact Assessment

**Scope:**
- [How widespread is this?]

**Affected Features:**
- [List affected features]

**Severity Justification:**
[Why this severity level]

**Data/Security Concerns:**
[Any data corruption or security implications]

## Proposed Fix

### Fix Strategy

[High-level approach to fixing]

### Files to Modify

1. **[file-path]**
   - Changes: [What needs to change]
   - Reason: [Why this change fixes it]

2. **[file-path]**
   - Changes: [What needs to change]
   - Reason: [Why this change fixes it]

### Alternative Approaches

[Other possible solutions and why the proposed approach is better]

### Risks and Considerations

- [Any risks with this fix]
- [Side effects to watch for]
- [Breaking changes if any]

### Testing Requirements

**Test Cases Needed:**
1. [Test case 1 - verify fix works]
2. [Test case 2 - verify no regression]
3. [Test case 3 - edge cases]

**Validation Commands:**
```bash
[Exact commands to verify fix]

实施计划

[实施步骤简述]

此 RCA 文档应供 piv-implement-issue 技能使用。

后续步骤

1. 审阅此 RCA 文档
2. 使用 Issue #$ARGUMENTS 运行 piv-implement-issue 技能以实施修复
3. 实施完成后运行 piv-commit 技能

## Post the summary to the issue

After writing the doc, post a short version as a GitHub comment — an audit trail, and so the fix can be
triggered/tracked from the issue itself:
```bash
gh issue comment $ARGUMENTS --body "<title · the Assessment table (severity/complexity/confidence + one-line reasons) · root cause in 1–2 lines · files to change · next: /piv-implement-issue $ARGUMENTS>"

边界情况

• 已关闭 → 报告此情况；如果需要分析，仍需编写 RCA。
• 已有已关联的 PR → 发出警告；继续前先确认。
• 无法确定根因 → 设置 Confidence: LOW，记录最有可能的假设及不确定之处，并在进行任何修复前标记为需要人工介入。
• 范围过大 → 建议拆分成更小的 Issue；本 RCA 聚焦核心问题，并将其余内容列为范围外。