piv-investigate-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Investigate Issue #$ARGUMENTS (Root-Cause Analysis)

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

Objective

目标

Investigate GitHub issue #$ARGUMENTS from this repository, identify the root cause, and document findings for future implementation.

Prerequisites:

Working in a local Git repository with GitHub origin
GitHub CLI installed and authenticated (
```
gh auth status
```
)
Valid GitHub issue ID from this repository

调查当前仓库中的GitHub Issue #$ARGUMENTS，确定根本原因，并记录调查结果以便后续修复。

前提条件：

在带有GitHub远程源的本地Git仓库中工作
已安装并认证GitHub CLI（执行
```
gh auth status
```
验证）
当前仓库的有效GitHub Issue ID

Investigation Process

调查流程

1. Fetch GitHub Issue Details

1. 获取GitHub Issue详情

Use GitHub CLI to retrieve issue information:

bash

gh issue view $ARGUMENTS

This fetches:

Issue title and description
Reporter and creation date
Labels and status
Comments and discussion

使用GitHub CLI检索Issue信息：

bash

gh issue view $ARGUMENTS

此命令会获取：

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

2. Explore the Codebase — fan out in parallel

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

Dispatch specialized agents in parallel (one message, multiple Task calls) so exploration is fast and the noisy search stays out of your main context:

codebase-analyst
— trace HOW the affected code works end-to-end: integration points, data flow, state/side effects, error handling. Return precise
```
file:line
```
references, no suggestions.
research-agent
(a second explorer) — find WHERE the relevant code lives + patterns to mirror: the error strings from the issue, related functions/modules, similar implementations, existing test patterns.

Merge their findings into a short map (

file:line

+ why each matters) before forming the root cause. (This is the parallel-subagent fan-out, applied to diagnosis.)

并行调度专业Agent（一次消息调用多个任务），以加快探索速度并避免无关搜索占用主上下文：

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

在确定根本原因前，将它们的发现合并为一个简短的映射表（

file:line

+ 各条目的重要性原因）。（这是并行子Agent展开的方法，应用于诊断环节。）

3. Review Recent History — when was it introduced?

3. 查看近期历史——问题何时引入？

Check recent changes to the affected areas, and pin down when the bug entered: !

git log --oneline -20 -- [relevant-paths]

bash

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

Decide: a recent regression vs a long-standing bug vs original behavior — it changes both the fix and the risk.

检查受影响区域的近期变更，确定bug的引入时间：

bash

git log --oneline -20 -- [relevant-paths]

bash

git blame -L <start>,<end> <affected-file>   # 谁在何时引入了可疑代码行

判断：这是近期回归问题、长期存在的bug还是原有行为——这会影响修复方案和风险评估。

4. Investigate Root Cause — the 5 Whys, with evidence

4. 调查根本原因——基于证据的5个为什么

Don't stop at the symptom. Chain why → because until you reach the specific, fixable code, and back every link with
file:line
evidence:

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>)

Watch for: input-validation gaps, unhandled edge cases, race/timing issues, wrong assumptions, missing error handling, integration mismatches.

不要停留在表面症状。通过为什么→因为的链式提问，直到找到具体可修复的代码，并且每个环节都要有

file:line

证据支持：

为什么会出现<症状>？→ 因为<原因A>   (证据：file.ts:123 — <代码片段>)
为什么会有<原因A>？→ 因为<原因B>   (证据：file.ts:456 — <代码片段>)
… 根本原因：<需要修改的具体代码/逻辑>  (证据：file.ts:789 — <代码片段>)

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

5. Assess Impact

5. 评估影响

Determine:

How widespread is this issue?
What features are affected?
Are there workarounds?
What is the severity?
Could this cause data corruption or security issues?

确定：

该问题的影响范围有多广？
哪些功能受到影响？
是否有可行的解决办法？
问题的严重程度如何？
是否可能导致数据损坏或安全问题？

6. Propose Fix Approach

6. 提出修复方案

Design the solution:

What needs to be changed?
Which files will be modified?
What is the fix strategy?
Are there alternative approaches?
What testing is needed?
Are there any risks or side effects?

设计解决方案：

需要修改哪些内容？
将修改哪些文件？
修复策略是什么？
是否有替代方案？
需要进行哪些测试？
是否存在任何风险或副作用？

Output: Create RCA Document

输出：创建RCA文档

Save analysis as:

docs/issues/issue-$ARGUMENTS.md

将分析结果保存为：

docs/issues/issue-$ARGUMENTS.md

Required RCA Document Structure

必备RCA文档结构

markdown

undefined

markdown

undefined

Root Cause Analysis: GitHub Issue #$ARGUMENTS

根本原因分析：GitHub Issue #$ARGUMENTS

Issue Summary

Issue摘要

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

GitHub Issue ID：#$ARGUMENTS
Issue链接：[GitHub Issue链接]
标题：[GitHub上的Issue标题]
报告者：[GitHub用户名]
状态：[当前GitHub Issue状态]

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:

[Step 1]
[Step 2]
[Observe issue]

Reproduction Verified: [Yes/No]

复现步骤：

[步骤1]
[步骤2]
[观察问题]

已验证可复现： [是/否]

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 <symptom> → because <cause>          (evidence: file:line — snippet)
… ROOT CAUSE: <the exact fixable thing>  (evidence: file:line — snippet)

Why This Occurs: [Explanation of the underlying issue]

Code Location:

[File path:line number]
[Relevant code snippet showing the issue]

[详细解释根本原因]

证据链（5个为什么）：

为什么<症状>会出现 → 因为<原因>          (证据：file:line — 代码片段)
… 根本原因：<具体可修复的问题>  (证据：file:line — 代码片段)

问题产生的原因： [对底层问题的解释]

代码位置：

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

Related Issues

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

待修改文件

[file-path]
- Changes: [What needs to change]
- Reason: [Why this change fixes it]
[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:

[Test case 1 - verify fix works]
[Test case 2 - verify no regression]
[Test case 3 - edge cases]

Validation Commands:

bash

[Exact commands to verify fix]

需要的测试用例：

[测试用例1 - 验证修复有效]
[测试用例2 - 验证无回归问题]
[测试用例3 - 边缘情况测试]

验证命令：

bash

[验证修复的具体命令]

Implementation Plan

实施计划

[Brief overview of implementation steps]

This RCA document should be used by the

piv-implement-issue

skill.

[简要概述实施步骤]

此RCA文档将供

piv-implement-issue

技能使用。

Next Steps

后续步骤

Review this RCA document
Run the
```
piv-implement-issue
```
skill with issue #$ARGUMENTS to implement the fix
Run the
```
piv-commit
```
skill after implementation complete

undefined

审核此RCA文档
使用
```
piv-implement-issue
```
技能处理Issue #$ARGUMENTS以实施修复
修复完成后运行
```
piv-commit
```
技能

undefined

Post the summary to the issue

在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>"

撰写完文档后，将简短版本作为GitHub评论发布——作为审计跟踪记录，以便从Issue本身触发和跟踪修复：

bash

gh issue comment $ARGUMENTS --body "<标题 · 评估表格（严重程度/复杂度/置信度 + 一行理由） · 1-2行根本原因 · 待修改文件 · 下一步：/piv-implement-issue $ARGUMENTS>"

Edge cases

边缘情况

Already closed → report it; still write the RCA if analysis is wanted.
Already has a linked PR → warn; confirm before continuing.
Can't pin the root cause → set Confidence: LOW, document the best hypothesis + what's uncertain, and flag it for a human before any fix.
Scope too large → suggest splitting into smaller issues; focus this RCA on the core problem and list the rest as out-of-scope.

已关闭的Issue → 报告此情况；如果需要分析，仍需撰写RCA文档。
已关联PR的Issue → 发出警告；继续前需确认。
无法确定根本原因 → 设置置信度：低，记录最佳假设+不确定项，并在修复前标记需人工审核。
范围过大 → 建议拆分为更小的Issue；将此RCA聚焦于核心问题，其余列为超出范围内容。

piv-investigate-issue

Original

Translation

Investigate Issue #$ARGUMENTS (Root-Cause Analysis)

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

Objective

目标

Investigation Process

调查流程

1. Fetch GitHub Issue Details

1. 获取GitHub Issue详情

2. Explore the Codebase — fan out in parallel

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

3. Review Recent History — when was it introduced?

3. 查看近期历史——问题何时引入？

4. Investigate Root Cause — the 5 Whys, with evidence

4. 调查根本原因——基于证据的5个为什么

5. Assess Impact

5. 评估影响

6. Propose Fix Approach

6. 提出修复方案

Output: Create RCA Document

输出：创建RCA文档

Required RCA Document Structure

必备RCA文档结构

Root Cause Analysis: GitHub Issue #$ARGUMENTS

根本原因分析：GitHub Issue #$ARGUMENTS

Issue Summary

Issue摘要

Assessment

评估

Problem Description

问题描述

Reproduction

复现步骤

Root Cause

根本原因

Affected Components

受影响组件

Analysis

分析

Related Issues

相关问题

Impact Assessment

影响评估

Proposed Fix

修复方案

Fix Strategy

修复策略

Files to Modify

待修改文件

Alternative Approaches

替代方案

Risks and Considerations

风险与注意事项

Testing Requirements

测试要求

Implementation Plan

实施计划

Next Steps

后续步骤

Post the summary to the issue

在Issue中发布摘要

Edge cases

边缘情况