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. コードベースを調査する — 並行して展開する

調査を迅速に進め、ノイズの多い検索結果がメインのコンテキストに入らないように、専用エージェントを並行して起動します（1つのメッセージで複数の Task 呼び出しを行います）。

• codebase-analyst — 影響を受けるコードの仕組みをエンドツーエンドで追跡します。統合ポイント、データフロー、状態／副作用、エラー処理を調べます。正確な file:line 参照を提示し、提案はしません。
• research-agent（2つ目の調査担当） — 関連コードの場所と、踏襲できるパターンを探します。issue に記載されたエラー文字列、関連する関数／モジュール、類似の実装、既存のテストパターンを調べます。

根本原因を導き出す前に、調査結果をまとめて簡潔なマップ（file:line と各項目の重要性）を作成します。これは、診断に並行サブエージェントの展開を適用したものです。

3. 最近の履歴を確認する — いつ導入されたか？

影響を受ける領域の最近の変更を確認し、不具合がいつ入り込んだかを特定します。 !git log --oneline -20 -- [relevant-paths]

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

最近のリグレッションか、以前から存在する不具合か、当初からの動作かを判断します。これは修正方法とリスクの両方に影響します。

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. 影響を評価する

以下を確認します。

• この issue の影響範囲はどの程度ですか？
• どの機能が影響を受けますか？
• 回避策はありますか？
• 深刻度はどの程度ですか？
• データ破損やセキュリティ上の問題につながる可能性はありますか？

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 <症状> → because <原因> （根拠：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 では中核となる問題に焦点を当て、残りは対象外として列挙します。