Procedure Extractor

Procedure Extractor

推奨実行モデル & 並列化

モデル: sonnet 必須（opusはコスト3-5倍。精度差は小さい） haiku禁止: 手順の意味的な紐付けにはsonnet以上が必要

並列化: 章をN分割してN Agent並列起動

Agent起動テンプレート:

Agent(
  model: "sonnet",
  mode: "bypassPermissions",
  run_in_background: true,
  prompt: "Process chapters NN-NN of [bundle_path]..."
)

注意: visual-indexerは画像を全Read するため最もコスト重い。必ずsonnet+並列。opusで全章順次は禁じ手。

前提: visual-indexerが完了していること。procedure-extractorはvisual-index.jsonのフレーム情報を参照して手順とスクショを紐付ける。

WHAT

講座トランスクリプトからUIウォークスルー・操作手順を抽出し、visual-indexerが分類したスクリーンショットと紐付けて procedures.json を生成する。

WHY

• 講座動画には「概念の説明」と「操作の実演」が混在している
• concept-extractorは概念・定義・名言を抽出するが、操作手順は対象外
• 手順はスクリーンショットと紐付けることで初めて再現可能になる
• 本スキルはマルチモーダル（スクショを実際に読む）である点がconcept-extractorと異なる

concept-extractorとの境界

入力の優先順位

マニュアルとトランスクリプトの両方を読むのがベスト。 マニュアルで手順の構造を把握し、トランスクリプトで具体的な操作の言い回しを拾う。

BLOCKER gates

以下を満たさない場合は処理を中断し、ユーザーに報告する。

処理フロー

1. manifest.json を読む
2. 対象チャプターの visual-index.json を読む  ← BLOCKER B2
3. 対象チャプターの transcript.txt を読む     ← BLOCKER B3
4. 対象チャプターの manual.md があれば読む（構造化済みマニュアル）
5. transcript_ts.json があれば読む（タイムスタンプ付きセグメント）
6. resources-manifest.json があれば読む（リソース参照用）
7. トランスクリプト（+マニュアル）から手順的言語パターンをスキャン
8. 関連するアクションをprocedureにグルーピング
9. 各ステップをスクリーンショットと紐付け（→ Screenshot Correlation）
10. 各ステップのリソース参照を紐付け（→ リソース参照の紐付け）
11. procedures.json を生成
12. 自己検証を実行

Step 5: 手順的言語パターンの検出

トランスクリプトから以下のパターンを検出する。詳細は references/visual-correlation.md を参照。

アクション動詞パターン

グルーピングルール

分割の目安:

• 画面が変わるタイミング
• 目的が変わるタイミング（「検索する」→「購入する」）
• 8ステップを超えたら分割を検討

Step 7: Screenshot Correlation

スクリーンショットとの紐付けロジック。

紐付けフロー

1. transcript_ts.json からアクション動詞の出現タイムスタンプを特定
2. visual-index.json で該当タイムスタンプ付近のフレームを検索
   - 対象: type が browser_screenshot または terminal_screenshot のフレーム
   - 範囲: アクション前後 ±5秒
3. 候補フレームを Read ツールで実際に読み、内容を確認
4. トランスクリプトの操作内容と画面内容が一致するフレームを screenshot_ref に設定

紐付けルール

transcript_ts.json がない場合

タイムスタンプ情報がない場合は以下で代替する:

1. トランスクリプト内の位置（先頭からの割合）でチャプター全体の時間軸を推定
2. visual-index.json のフレーム順序と照合
3. 画像内容を実際に読んで、トランスクリプトの文脈と照合

記事章（content_type: article/hybrid）の場合

記事章ではタイムスタンプ紐付けは不要。article.md内の画像参照は著者が正しい位置に 埋め込み済みなので、手順テキストの直近にある画像参照（![...](screenshots/img_NNN.png)） をそのまま screenshot_ref に使う。これはタイムスタンプ推定より確実。

• 手順の抽出元はarticle.md（原文）。hybrid章では動画transcriptからも抽出し、 各手順に source: "article" | "video" を付ける
• 画像なしの手順は screenshot_ref: null でよい（記事は文章だけで完結する手順が多い）

Step 10: リソース参照の紐付け

手順内で外部リソースを使用するステップには resource_ref を設定する。

検知パターン

• 「Notionからコピー」「テンプレートを使って」「PDFを参照」
• 「ここにあるプロンプトを」「ダウンロードして」

紐付け方法

1. resources-manifest.json を読む
2. 手順内のリソース言及を検知
3. manifest内の該当リソースとマッチング
4. resource_ref にパスを設定（マッチしない場合は null）

出力フォーマット: procedures.json

チャプターごとに procedures.json を生成する。

{
  "chapter_id": "06",
  "procedures": [
    {
      "id": "p06-01",
      "title": "noteでプロンプトを検索する方法",
      "steps": [
        { "step": 1, "action": "NotionからPredictionXプロンプトをコピー", "screenshot_ref": "frame_011.jpg", "resource_ref": "prompts/prediction-x.md" },
        { "step": 2, "action": "note.comにアクセス", "screenshot_ref": "frame_012.jpg", "resource_ref": null },
        { "step": 3, "action": "検索欄に「プロンプト」と入力", "screenshot_ref": "frame_013.jpg", "resource_ref": null },
        { "step": 4, "action": "有料のみフィルタを選択", "screenshot_ref": "frame_014.jpg", "resource_ref": null }
      ],
      "outcome": "有料のプロンプト一覧が表示される",
      "tags": ["note", "プロンプト検索", "壁打ち"],
      "prerequisites": ["c03-02"],
      "difficulty": "beginner"
    }
  ]
}

フィールド仕様

difficulty 判定基準

Step 9: 自己検証

生成後に以下をすべてチェックする。1つでも失敗したら修正する。

• 各procedureに明確なtitleとoutcomeがあるか
• screenshot_refが全てvisual-index.jsonに存在するフレームを指しているか
• stepsの順序が論理的か（前提なしに後段のステップが来ていないか）
• tagsが具体的か（「その他」のような曖昧タグがないか）
• 概念的な内容が混入していないか（それはconcept-extractorの仕事）
• 1つのprocedureが8ステップ以下か
• procedures.jsonが schemas/procedures.schema.json に準拠しているか
• 全screenshot_refのファイルが実際に存在するか（Bashで確認）
• resource_refが設定されたステップのパスがresources-manifest.jsonに存在するか
• マニュアルがある章でマニュアルを参照したか

screenshot_ref 検証コマンド

# procedures.jsonから全screenshot_refを抽出し、存在チェック
jq -r '.procedures[].steps[].screenshot_ref // empty' procedures.json | while read f; do
  [ -f "$FRAMES_DIR/$f" ] || echo "MISSING: $f"
done

ユーザーへの提示

処理完了後、以下の形式で報告する:

## 手順抽出完了: Chapter {id}

- 抽出数: {n} procedures, {m} total steps
- スクショ紐付け: {linked}/{total} steps にスクショあり
- 難易度分布: beginner={b}, intermediate={i}, advanced={a}

### 抽出した手順一覧
| ID | タイトル | ステップ数 | スクショ数 |
|----|---------|----------|----------|
| p{id}-01 | ... | 5 | 3 |
| p{id}-02 | ... | 4 | 4 |

出力先: {path}/procedures.json

このスキルがやらないこと