survey-visuals

サーベイのビジュアル（タイムライン＋図の仕様、本文なし）

トリガーと振り分け

• トリガー：survey visuals、timeline、figures、visuals、图表、时间线、figure spec。
• 使用する場面：サーベイの C4（本文なし）で、outline と claim/evidence、引用がすでに揃っており、タイムライン／図の仕様をまずファイルに記録する必要がある場合。

このスキルでは、執筆段階のテンプレート感を抑える、本文以外の成果物を作成します。

• タイムライン／変遷の箇条書き
• 図の仕様（描く内容、重要な理由、裏付けとなる論文）

読み込み順序

必ず読み込むもの：

• references/overview.md
• references/figure_archetypes.md

タスクに応じて読み込むもの：

• タイムラインのマイルストーンを作成する場合は references/timeline_patterns.md

機械可読アセット：

• assets/figure_templates.yaml — 図の類型の仕様（コードを変更せずに拡張可能）

スクリプトの適用範囲

scripts/run.py は、次の用途に限って使用します。

• paper_notes と bibkeys からタイムラインの箇条書きを決定的に組み立てる
• outline とマッピングから表を生成する
• assets/figure_templates.yaml を使用して図の仕様の骨組みを生成する

次の用途で run.py を使用しないでください。

• 図の説明やナラティブのハードコード
• references から確認できるべきマイルストーン選定のヒューリスティクス

表は専用の表スキルで扱います。

• table-schema -> outline/table_schema.md
• table-filler -> outline/tables_index.md（内部インデックス）
• appendix-table-writer -> outline/tables_appendix.md（読者向け付録表）

入力

• outline/outline.yml
• outline/claim_evidence_matrix.md
• papers/paper_notes.jsonl
• citations/ref.bib

出力

• outline/timeline.md
• outline/figures.md

ワークフロー入力（明示）

• outline/outline.yml と outline/claim_evidence_matrix.md を使って、何を可視化するか決めます。
• 年やマイルストーンの候補には papers/paper_notes.jsonl を使います。
• citations/ref.bib に含まれる引用キーのみを使用します。

ワークフロー（ヒューリスティック）

1. outline と claim-evidence matrix を読み、繰り返し登場する比較軸を選びます。
2. タイムライン（outline/timeline.md）：
   • 年 -> 主要なマイルストーンを箇条書きで記述します（幅広く取り上げ、引用を付けることを目指します）。
3. 図（outline/figures.md）：
   • 人が描ける図の仕様を2～4件記述します。
     • 目的（図が伝える知見）
     • 必須要素（ボックス／矢印／軸）
     • 各要素を裏付ける論文（引用キー）
4. citations/ref.bib にある引用キーのみを使用します。

品質チェックリスト

• 出力に TODO や `` が残っていないこと。
• outline/timeline.md に年の箇条書きが8件以上あり、各箇条書きに引用マーカー [@...] が1つ以上あること。
• outline/figures.md に図の仕様が2件以上あり、各仕様に裏付けとなる引用が1つ以上記載されていること。

ヘルパースクリプト（任意）

クイックスタート

• uv run python .codex/skills/survey-visuals/scripts/run.py --help
• uv run python .codex/skills/survey-visuals/scripts/run.py --workspace <workspace>

すべてのオプション

• --workspace <workspace>（必須）
• --unit-id <id>（任意。runner の記録管理にのみ使用）
• --inputs <a;b;c>（任意。デフォルトは上記の4つの入力）
• --outputs <timeline_rel;figures_rel>（任意。デフォルトは outline/timeline.md;outline/figures.md）
• --checkpoint <C#>（任意。ヘルパーでは無視されます）

例

• デフォルト設定でタイムラインと図を生成する：

  uv run python .codex/skills/survey-visuals/scripts/run.py --workspace <workspace>

• 出力先を指定して生成する：

  uv run python .codex/skills/survey-visuals/scripts/run.py --workspace <workspace> --outputs outline/timeline.md;outline/figures.md

注記

• このヘルパーは意図的に最小限の機能に絞られており、プレースホルダー以外の成果物を上書きすることはありません。
• strict モードでは、プレースホルダーマーカーが残っている場合に限り処理をブロックします（タイムライン／図の最小要件を満たしていない場合も同様です）。

トラブルシューティング

問題：タイムラインの内容が乏しい、または引用がない

対処法：

• 厳選したマイルストーンを少数選び、各箇条書きに [@...] が1つ以上あることを確認します。
• notes の内容が乏しい場合は、情報を水増しするのではなく、上流工程に戻って paper-notes／evidence-draft を強化します。

課題：図の仕様が散文のように読める

修正：

• 仕様は描画指示として維持します：目的＋要素＋各要素を裏付けるもの（引用キーを記載）。
• 説明文は本文に移します。このファイルは散文以外の形式にしてください。