Survey Skill

ソースを網羅的に読み込み、見出し・セクション構成・要約を索引ドキュメントとして生成します。

使用方法

/survey <ソースパス> [--output <出力パス>] [--depth <1-3>]

引数

• ソースパス（必須）: PDF, ディレクトリ, URL のいずれか
• --output: 出力先ファイルパス（省略時: ./docs/survey_<basename>.md）
• --depth: 要約の深さ（デフォルト: 2）
  • 1: 見出しとページ番号/パスのみ
  • 2: 見出し + 2-3行の要約
  • 3: 見出し + 詳細要約 + キーポイント

処理手順

Step 1: ソースタイプ判定

$ARGUMENTS を解析し、ソースタイプを判定する:

引数が空の場合はエラーメッセージを表示して終了:

使い方: /survey <ソースパス> [--output <出力パス>] [--depth <1-3>]
例: /survey ./docs/manual.pdf --output ./docs/survey_manual.md

Step 2: ソース読み込み

PDF の場合

重要: PDFは必ず分割して読み込むこと。一度に全ページを読まない。

1. まず pages パラメータで "1-2" を指定してReadツールで読み込み、総ページ数を把握する
2. 12ページずつ分割して読み込む（例: "1-12", "13-24", "25-36", ...）
3. 各チャンクから以下を抽出:
   • セクション見出し（章・節の番号とタイトル）
   • 各セクションの開始ページ番号
   • セクション内容の要約（depth に応じた詳細度）
   • 実装で参照しそうな重要箇所（表、定義、コード例など）
4. 最大20ページ/リクエストの制限に注意。大きなPDFは12ページ単位を推奨

# 読み込み例（Readツール使用）
pages: "1-12"   → 最初のチャンク
pages: "13-24"  → 2番目のチャンク
pages: "25-36"  → 3番目のチャンク
...

ディレクトリ（リポジトリ）の場合

1. Glob で全ファイル一覧を取得（**/*）
2. ファイル数を確認:
   • 100ファイル以下: 主要ファイルをすべて走査
   • 100ファイル超: ディレクトリ構造のみ + 主要ファイルに限定
3. 以下の順序で読み込み:
   • README.md / README（あれば）
   • 設定ファイル（package.json, pyproject.toml, Cargo.toml, CMakeLists.txt 等）
   • エントリポイント（main., index., app.* 等）
   • src/ 配下の主要モジュール
4. 各ファイルの役割を2-3行で要約
5. ディレクトリ構造をツリー形式で表示

URL（Web）の場合

1. WebFetch でメインページのコンテンツを取得
2. ページ内の主要セクション見出しを抽出
3. depth=3 の場合、リンク先の主要サブページも取得（最大5ページ）
4. 認証が必要なURLの場合は警告を表示:

   警告: このURLは認証が必要な可能性があります。WebFetchは認証付きURLに対応していません。
   ローカルにダウンロードしてから /survey を実行してください。

Step 3: 索引ドキュメント生成

以下のテンプレートに従ってMarkdownドキュメントを生成する。

Step 4: ファイル出力

• --output が指定されている場合はそのパスに出力
• 未指定の場合は ./docs/survey_<ソース名>.md に出力
• 出力先ディレクトリが存在しない場合は Bash の mkdir -p で作成
• Write ツールでファイルを書き出す

重要度マーキング基準

各セクションに以下の基準で重要度マークを付ける:

出力テンプレート

# Survey: [ソース名]

| 項目 | 値 |
|------|-----|
| ソース | [フルパス or URL] |
| 種別 | PDF / Repository / Web |
| 規模 | XX ページ / XX ファイル |
| 作成日 | YYYY-MM-DD |
| 深さ | depth N |

## 目次

| # | セクション | ページ/パス | 重要度 | 要約 |
|---|-----------|------------|--------|------|
| 1 | [セクション名] | p.1-5 | ★★ | [1行の概要] |
| 2 | [セクション名] | p.6-12 | ★★★ | [1行の概要] |
| ... | ... | ... | ... | ... |

## セクション詳細

### 1. [セクション名] (p.1-5) ★★

[2-3行の要約]

**キーポイント:**
- ポイント1
- ポイント2

### 2. [セクション名] (p.6-12) ★★★

[2-3行の要約]

**キーポイント:**
- ポイント1
- ポイント2
- ポイント3

(depth=3の場合、各セクションにさらに詳細な要約を追加)

---

## クイックリファレンス

実装時に最初に参照すべきセクション:

- ★★★ [セクション名] (p.XX) - [理由]
- ★★★ [セクション名] (p.XX) - [理由]
- ★★ [セクション名] (p.XX) - [理由]

リポジトリの場合の追加セクション

目次テーブルの代わりにディレクトリ構造を含める:

## ディレクトリ構造

project/ ├── README.md ├── package.json ├── src/ │ ├── index.ts ★★ エントリポイント │ ├── config.ts ★★ 設定定義 │ └── modules/ │ ├── auth.ts ★★★ 認証モジュール │ └── api.ts ★★★ API定義 ├── tests/ └── docs/

## ファイル詳細

### src/index.ts ★★
[2-3行の要約]

### src/config.ts ★★
[2-3行の要約]

注意事項

• PDFは絶対に一括読み込みしない。必ず12ページ以下に分割すること
• 大規模リポジトリ（100ファイル超）は構造概要 + 主要ファイルのみにとどめる
• Web取得は認証不可。認証付きURLには事前に警告する
• 出力は日本語で記述する
• 索引は「後から実装時に必要な情報をすぐ見つけられる」ことを最優先とする

実行対象

$ARGUMENTS