research

name	research
description	Deep codebase investigation producing structured research documents. Use when user says 'investigate', 'how does X work', '仕組みを教えて', 'コードを調査して', '既存実装を把握したい', or wants to understand existing code before planning. Do NOT use for simple file searches, quick questions about specific functions, or making code changes.
allowed-tools	Agent, AskUserQuestion, Bash, Read, Write, Glob, Grep
argument-hint	[topic, feature name, or file path] [--scope 'broad'|'focused'] [--output 'filename']
disable-model-invocation	true
metadata	{"author":"ysk1031","version":"1.0.0"}

Codebase Research Skill

Deeply investigate a codebase topic, feature, or module and produce a structured research document (research-<topic>.md) for human review — before any planning or implementation begins.

Instructions

Phase 1: Scope Determination (use Agent with subagent)

Call the Agent tool with:

• subagent_type: "research-planner"
• description: "determine research scope"
• prompt: Replace $ARGUMENTS in the agent's loaded prompt with the actual user arguments and execute.

---

Phase 2: Deep Investigation (use Agent with subagent)

If Phase 1 returned an error status ("status": "NO_TOPIC"), display the message field to the user and stop.

If Phase 1 returned "entry_point_count": 0, use AskUserQuestion to ask the user for clarification:

• question: "<topic from Phase 1 output> に関連するファイルが見つかりませんでした。キーワードやパスを変えて再試行しますか？"
• header: "Research"
• options:
  1. label: "キーワードを変更", description: "別のキーワードで検索します（Otherで入力）"
  2. label: "キャンセル", description: "調査を終了します"

If "キーワードを変更": Re-run Phase 1 with the new keyword. If "キャンセル": Print "調査を終了しました。" and stop.

Otherwise, call the Agent tool with:

• subagent_type: "codebase-investigator"
• description: "deep codebase investigation"
• prompt: Use the entire Phase 1 output as scope data and the TOPIC as the investigation topic.

The subagent returns a JSON object following the research-investigation-output schema defined in research/references/schemas.md. Key fields used in Phase 3: status, topic, files_investigated, overview, architecture, components, data_flow, patterns, risks, file_list.

---

Phase 3: User Review (main agent)

"status": "OK" from Phase 2:

Display the research summary to the user, using JSON fields:

## 調査結果サマリー

**トピック**: <topic>
**調査範囲**: <scope from Phase 1>
**調査ファイル数**: <files_investigated>

### 主要な発見
<key findings summary — 3-5 bullet points>

### アーキテクチャ概要
<brief architecture description>

Use AskUserQuestion:

• question: "調査結果をファイルに出力しますか？"
• header: "Research"
• options:
  1. label: "ファイルに出力", description: "research-.md として保存します"
  2. label: "追加調査", description: "特定の領域をさらに深く調査します（Otherで入力）"
  3. label: "キャンセル", description: "調査を終了します"

If "ファイルに出力": Proceed to Phase 4 If "追加調査": User provides a follow-up question or area via "Other". Re-run Phase 2 with the original scope data PLUS the follow-up request AND the previous Phase 2 results as prior context. Do NOT re-run Phase 1. If "キャンセル": Print "調査を終了しました。" and stop.

---

Phase 4: Output Generation (main agent)

Write the research document:

1. Determine filename:

   • If Phase 1's output field is non-empty: use that filename
   • Otherwise: research-<sanitized-topic>.md (sanitize: lowercase, replace spaces/special chars with hyphens)

2. Read the output template from assets/output-template.md (relative to this skill's directory) with the Read tool. Write the research document using the Write tool, populating each section with the corresponding data from Phase 2's JSON output.

3. Display completion message:

## 調査完了

`<filename>` に調査結果を出力しました。

### 次のステップ
- 調査結果を確認し、認識の誤りがあれば修正してください
- 計画策定に進む場合、このファイルをコンテキストとして活用できます

---

Rules

• ALWAYS display messages in Japanese — the user is a Japanese speaker and needs to review research findings in Japanese
• NEVER modify any source code — this skill is read-only investigation — modifying code during research risks introducing unverified changes
• NEVER skip user review (Phase 3) — without human verification of findings, planning may proceed on incorrect assumptions
• When re-running Phase 2 with follow-up, include previous findings to avoid redundant investigation — re-reading the same files wastes tokens; leveraging prior results enables efficient deep-dives
• Read files in full — do NOT use partial reads (head/tail) unless the file exceeds 1000 lines — partial reads lose context and lead to incorrect analysis
• Trace call chains at least 2 levels deep (caller → callee → callee's callee) — one level only gives surface-level understanding and misses actual data flow and side effects
• When assumptions are made, explicitly mark them as assumptions in the output — without distinguishing assumptions from facts, downstream planning may treat guesses as confirmed truths
• If CLAUDE.md exists, read it and incorporate project conventions into the analysis — analysis that ignores project-specific conventions is not useful during implementation
• The research output file should be detailed enough for someone unfamiliar with the codebase to understand the topic — even when the researcher and implementer differ, the findings alone should be sufficient for implementation decisions

---

Examples

Example 1: 機能調査

User says: "認証フローの仕組みを調べて" Actions:

1. research-planner がスコープを決定（topic: 認証フロー, scope: focused）
2. codebase-investigator が関連ファイルを深掘り調査
3. ユーザーに調査結果サマリーを提示
4. 承認後 research-auth-flow.md として出力 Result: 認証フローのアーキテクチャ、コンポーネント、データフローを網羅した調査ドキュメントが生成される

---

Troubleshooting

"entry_point_count: 0"

Cause: 指定したキーワードに関連するファイルが見つからない Solution: より具体的なキーワードやファイルパスを指定して再試行

調査結果が浅い

Cause: デフォルトのfocusedスコープでは調査範囲が限定される Solution: --scope broad を指定して広範囲の調査を実行