Walkthrough

---
name: walkthrough
description: 差分または既存コードを実コードに基づいて説明し、入口・経路・状態・設計上の注意を整理する。必要な場合だけ詳細化・保存・HTML化を行う。ユーザーが /walkthrough と入力したときに使う。
argument-hint: "[PR番号 / ブランチ名 / ファイル / ディレクトリ / topic] [--html] [--no-save] [--fresh]"
---

# Walkthrough — 実コードを読む

**対象**: `$ARGUMENTS`（省略時は親が確認したローカル差分）

親は対象、対象版、読み取り範囲、必要な追加調査、保存、詳細化、終了を所有します。本文未読の要約だけから実装内容を断定しません。説明は読み手がコードの実際の入口、経路、状態、境界を追えるようにします。

## 1. 対象を確定する

target は次の優先順で判定します: 明示されたPR/ブランチ/ファイル/ディレクトリ、自然文のtopic、省略時のローカル差分。曖昧な場合だけユーザーへ確認します。PR・ブランチ・差分では base/head または現在の変更状態を記録し、評価中に親が対象を変更しません。

単一の既知ファイルは親が直接読めます。ディレクトリ、topic、複数レイヤー、間接参照が対象なら、必要な範囲だけ現在のruntimeの標準 read-only child または汎用 Task へ渡します。担当には対象版、所有範囲、確認済み事実、具体的な問い、実コードの返却箇所、編集禁止と、必要な実行者用 Skill / reference の実体 path を渡し、担当自身に必要な資料を Read させます。親が直接確認する場合だけ、必要な資料を親が Read します。担当同士の相互起動、report保存、記憶追記を要求しません。

## 2. キャッシュを扱う

既存の walkthrough があり、ユーザーが `--fresh` を指定していない場合は、現在の対象版・ファイル状態とキャッシュのメタデータを比較します。完全一致なら再利用、部分変化なら変化範囲だけ更新、構造変化や対象消失なら再調査を提案します。古い・削除済み・比較不能なキャッシュを最新結果として扱いません。

保存先、ファイル名、RUN_DIRは既存方針または親の指定から解決します。指定がない場合に docs や一時台帳を推測して作りません。`--no-save` ではチャット内だけで完結します。

## 3. 調査と複雑度

親は対象の実コードと、必要なら探索結果を照合し、読む順序を決めます。複数担当は、独立した所有範囲または別の呼び出し経路を分けることで利益がある場合だけ使います。小規模な単一ファイルにチームや追加ラウンドを強制しません。子へ親用 `/walkthrough` の説明・詳細化・保存ループを渡して同じ工程を再起動させません。

次の状況では分割を検討します: 複数の独立レイヤー、状態遷移、複数の起点、動的ディスパッチ、広い差分、ユーザーが全経路を明示要求した場合。担当数・行数・メニュー数・ラウンド数を完了条件にせず、親が結果を統合します。情報不足で説明を確定できない場合は、具体的な追加調査か未確認事項を返します。

## 4. 冒頭の説明

対象の規模に合わせ、次の構造から必要な項目を選びます。小さな対象に不要な長文、固定数のコード引用、固定数のメニューを足しません。

```markdown
---
target_type: pr | branch | file | directory | topic | local-diff
target_id: [対象の識別子]
base_sha: [分かる場合]
head_sha: [分かる場合]
created_at: [保存する場合]
updated_at: [保存する場合]
---
# [対象] ウォークスルー
## 変更・構造の全体像
## 読む順序
### 1. [入口・責務] — [path:line]
## データ・制御フロー（必要な場合）
## 影響範囲
## 設計上の注意点・落とし穴
## 詳細化メニュー（必要な場合）
```

各説明は実在する `path:line`、関数・型・設定・テストに結びつけます。核心コードは必要な範囲だけ正確に引用し、引用箇所の役割、呼び出し元/先、成功・失敗経路を説明します。設計理由が確認できない場合は推測と明示します。

データフロー図や表は、文章より速く理解できるときだけ使います。外部依存の仕様を説明する場合は一次資料を参照し、URLを添えます。レビューのPASS/FAIL、実装修正、commit、pushはこのスキルの責務ではありません。

## 5. 保存とHTML

保存する場合は、親が指定した親directoryの実在を確認し、その配下の今回未使用のファイルpathへ新規作成します。既存の対象キャッシュを更新する場合も、対象版と変更範囲を確認し、別の対象結果を上書きしません。保存後にファイルpathの実在を確認して提示します。

`--html` が明示された場合は、この共有Skillの実体ディレクトリから `references/html-mode.md` を先にReadし、そこから同じskill packageの `references/html-template.html` をReadします。親からHTML reference/templateのpathを渡されることを前提にせず、共有packageの実体を起点に解決します。HTMLの内容はmdと同じ事実に基づき、単一ファイル・外部リクエストなしを基本にします。テンプレートが指定する自己チェックを通し、ブラウザを開けない環境ではパスを返して終了します。HTMLを保存する先、生成、再表示は既存のruntime手順に従い、外部アップロードを行いません。

## 6. 詳細化

冒頭の説明後、ユーザーがメニューまたは自然文で対象を指定した場合だけ深掘りします。既存の回答で足りる場合は追加調査せず、必要な場合だけ具体的な問いを追加調査担当へ渡します。短いQ&Aは保存せず、ユーザーが記録を求めた構造化説明だけ保存します。

詳細化ログを保存する場合は、要求、対象版、実コード引用、解説、未確認事項、更新日時を記録します。`--no-save` ではチャットだけに返します。広い「全部」要求は、対象の量と利用可能な容量から妥当な範囲を親が選び、続きを要求された場合だけ続けます。

ユーザーが終了を示したら、必要な保存を完了し、対象、確認範囲、詳細化、未確認事項、保存先を報告します。明示の終了を無期限に待つことを完了条件にせず、単発の説明依頼なら説明を返して終了できます。