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. 画像内容を実際に読んで、トランスクリプトの文脈と照合

---

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

---

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

Visual Correlation ガイド

トランスクリプトのアクション記述とスクリーンショットを紐付けるための詳細ガイド。

---

1. アクション動詞パターン（日本語）

トランスクリプトから手順を検出する際に使うパターン。

クリック・タップ系

入力・記述系

選択・チェック系

移動・遷移系

設定・変更系

指示語+動詞（高確率で画面操作）

---

2. タイムスタンプの推定

transcript_ts.json がある場合

transcript_ts.json にはセグメントごとのタイムスタンプがある:

[
  { "start": 120.5, "end": 125.3, "text": "ここをクリックしてください" },
  { "start": 125.3, "end": 130.1, "text": "次に検索欄に入力します" }
]

アクション動詞が含まれるセグメントの start を基準に、visual-index.json のフレームを検索する。

transcript_ts.json がない場合

位置ベースの推定を使う:

推定タイムスタンプ = (アクション出現位置 / トランスクリプト全文字数) × チャプター総時間

チャプター総時間は manifest.json の duration、または visual-index.json の最後のフレームのタイムスタンプから推定する。

精度は低いため、候補を広めに（±15秒）取り、画像内容で最終判断する。

---

3. フレームとのマッチング

visual-index.json のフレーム構造

{
  "frame": "frame_012.jpg",
  "timestamp": 123.4,
  "type": "browser_screenshot",
  "description": "noteの検索画面"
}

マッチング手順

1. タイムスタンプで候補を絞る: アクションのタイムスタンプ ±5秒（ts.jsonなしなら±15秒）のフレームを候補にする 2. typeでフィルタ: browser_screenshot または terminal_screenshot を優先。talking_head や slide は手順には使わない 3. 画像を実際に読む: Read ツールで候補フレームを表示し、内容を確認する 4. 照合判断: トランスクリプトの操作内容と画像内容が一致するか判断する

照合の判断基準

原則: screenshot_ref は「操作を行う直前の画面」または「操作中の画面」のフレームを指す。「操作後の結果画面」はそのステップではなく、次のステップや outcome の参考にする。

---

4. エッジケース

4.1 複数ステップが同一スクリーンショットを共有

同じ画面内で複数の操作を行う場合（例: フォームの複数フィールドに入力）、同じ screenshot_ref を複数ステップで参照してよい。

{ "step": 1, "action": "名前欄に入力", "screenshot_ref": "frame_020.jpg" },
{ "step": 2, "action": "メール欄に入力", "screenshot_ref": "frame_020.jpg" },
{ "step": 3, "action": "送信ボタンをクリック", "screenshot_ref": "frame_020.jpg" }

4.2 スクリーンショットがないステップ

口頭での説明のみで画面操作がない、またはカメラが講師を映しているときは null にする。

{ "step": 2, "action": "別タブでGmailを開く", "screenshot_ref": null }

無理にスクショを付けない。存在しないファイルを参照するよりは null のほうが安全。

4.3 手順が複数チャプターにまたがる

1つの操作手順が2つのチャプターにまたがる場合:

• 各チャプターで独立した procedure として記録する
• 前チャプターの procedure を prerequisites に含める
• title に「(続き)」等を付けて関連を示す

{
  "id": "p07-01",
  "title": "LINE公式アカウントの設定（続き: メッセージ配信設定）",
  "prerequisites": ["p06-03"],
  ...
}

注意: prerequisites の形式は concept ID (c{xx}-{yy}) だが、procedure 間の依存は title と tags で表現する。スキーマ上 prerequisites は concept への参照に限定されている。

4.4 スクリーンショットの画質が悪い / 判読不能

画像を読んでも内容が判別できない場合は screenshot_ref: null にし、action の記述をより詳細にする。

4.5 同一タイムスタンプに複数フレーム

visual-index.json で同タイムスタンプに複数フレームがある場合は、type が browser_screenshot / terminal_screenshot のものを優先し、さらに description がトランスクリプトの文脈に近いものを選ぶ。