📖 Prompt Cookbook — explainer pipeline

inbox-explainer skill を初めて使う。以下の順で必読:

1. ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle/skills/inbox-explainer/SKILL.md (特に §0)
2. ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle/examples/INDEX.md
3. ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle/skills/inbox-explainer/templates/image_prompt_grammar.md (§3 few-shot)
4. ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle/skills/inbox-explainer/templates/outline.schema.json
5. ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle/skills/inbox-explainer/templates/ground_truth_rules.md

実行はしない。読み込み後、以下を 1 段落で報告:
- 5 ファイルの size (ls -la)
- §0 の 4 sub-section (0.1/0.2/0.3/0.4) を 1 行ずつ要約
- 過去の outline でこの新 schema に通らないものがあるか (find + validate)

inbox-explainer skill で smoke test として 1 本作る。

事前必読 (§0 mandatory): SKILL.md / examples/INDEX.md / image_prompt_grammar.md / outline.schema.json / ground_truth_rules.md

テーマ: <ここに技術名 1 つ。例: "MR Fingerprinting" / "DIXON 4-point" / "ASL Perfusion">

要件:
- domain: paper-deep
- canonical 写経参照: examples/perfusion-deep/outline.json または 4dflow-deep/outline.json
- sections 6-8、各 section に 5-element (Lead p / table / 用語解説 callout / 運用方法 callout / アンチパターン callout-warn)
- 各 figure の `ground_truth` に sources / quote_refs / why_chain (l1/l2/l3) / apps_guide_status を埋める
- 完了前に templates/outline.schema.json で validate、errors=0 まで修正

deploy は **明示するまでしない** (smoke なので --skip-deploy)。Discord は deploy 時 default ON だが smoke 段階なので暗黙抑止される。

完了後:
- 出力先絶対 path
- schema validation 結果 (errors=0)
- 何が drift しそうだったか (英語化 / レイアウト崩れ / 浅深度) を 3 行で報告

# Mac/母艦 共通 (jsonschema 必要: pip install jsonschema)
bundle="$HOME/GoogleDrive/GD_Mirror/inbox-explainer-bundle"
schema="$bundle/skills/inbox-explainer/templates/outline.schema.json"

find "$HOME/GoogleDrive" "$HOME/OneDrive*" -name "outline.json" 2>/dev/null | while read f; do
  python3 -c "
import json, sys
from jsonschema import Draft202012Validator
schema = json.load(open('$schema', encoding='utf-8'))
try:
  data = json.load(open('$f', encoding='utf-8'))
except Exception as e:
  print(f'$f: PARSE_ERROR {e}'); sys.exit()
errs = list(Draft202012Validator(schema).iter_errors(data))
status = 'PASS' if not errs else f'FAIL({len(errs)})'
print(f'$f: {status}')
for e in errs[:2]:
  print('  -', list(e.absolute_path), str(e.message)[:100])
"
done

inbox-explainer skill / paper-deep domain で outline.json 起案。

論文 / WIP: <DOI or WIP code or topic name>
canonical 参照: examples/perfusion-deep/outline.json (5-stage cascade pattern) または
                examples/4dflow-deep/outline.json (multi-dimension pattern)

sections 構成 (推奨 8 section):
01. 全体技術 cascade (5-7 段で工程列挙)
02-05. Component 詳細 (各 component を 1 section、Before/After table 必須)
06. KOL 文献 (世界 leader 双璧、Top 5 文献カード)
07. 自施設適用 + Decision Tree (30 秒判断)
08. 限界 + 次アクション + Common Limit リンク

Phase A ground_truth (各 figure):
- sources: ["Apps Guide §X.Y", "Author Year Journal"] (≥1 必須)
- quote_refs: ["page Z: 'quote...'"] (optional だが強推奨)
- why_chain: l1 (定義) / l2 (機構) / l3 (戦略決定)
- apps_guide_status: covered/silent/conflicting/na

完了 gate: schema validate errors=0、各 section に callout-warn 1 つ以上。

inbox-explainer skill / zk domain で ZK ノート群を 1 枚 explainer 化。

トピック: <技術名 例: BOOST / Wideband LGE>
ZK source: 10_Knowledge/01_ZettelKasten/{02_Literature, 03_Permanent}/<topic>*.md (全 grep)
canonical 参照: examples/boost/outline.json (Cross-WIP discipline + 3 ソース triangulation pattern)

sections 構成 (7 section):
01. 概念 + Before/After (従来 vs 本技術)
02. 機構 (Cross-WIP discipline 区別必須、lineage swap 防止)
03. 臨床応用 (3 部位 / 3 適応など)
04. 重要関連文献 Top 5 (3 ソース triangulation)
05. 自施設適用マトリクス + WIP code
06. 30 秒 Decision Tree
07. 限界 + 次アクション + Common Limit

ZK 引用: [[<note>]] wikilink で本文中に inline 化 (`.claude/rules/wikilink-density.md` 準拠)。

inbox-explainer skill / mail domain で施設別メール往復を可視化。

施設: <三重大学 / NCVC / 京都大学 / 東北大学 / 名古屋大学 / 日本医科大学 / 旭川医科大学>
データ source:
- 01_Input/03_Email/_Index/sent_index.json (送信履歴)
- 02_ToDo/02_Drafts/ (未送信ドラフト)
- 02_ToDo/01_Cockpit/ (タスク状態)

canonical 参照: examples/mail-drafts/outline.json

sections 構成 (4-5 section):
01. 送信タイムライン (timeline figure + sent count table)
02. 担当者マップ (medical staff + 我々側、connection 図)
03. 未送信ドラフト一覧 (aging 別、SEND READY 候補)
04. 次アクション (3 ソース cross-check 結果)
05. (optional) 過去訪問記録 link

注意: callout に [!mail]- は埋めない (HTML output 用、Outlook copy パターン)。

inbox-explainer skill / visit domain で訪問報告 / 訪問準備を 1 枚化。

施設 + 日付: <例: 三重大学 2026-05-15>
データ source:
- 03_Workspace/01_Projects/<facility>/0000_報告書/ (過去訪問報告)
- _Platform/Project_Bridge/project_cards/<facility>_*.md (Project Dossier)
- visit-battlecard skill 出力 (あれば)

canonical 参照: 既存の rc-platform/outline.json (5 Spoke pattern を参考に)

sections 構成 (5-7 section):
01. 訪問前状態 (現在 active project マトリクス)
02. Project 別進捗 (各 project の current state)
03. 提案 / 議題 (今回訪問で持ち込む WIP / 文献)
04. 訪問後アクション (想定される次 step)
05. 関連 Knowledge link (ZK Permanent / Literature)
06. (optional) 装置情報 (model / 磁場 / SW version)
07. (optional) Decision Tree (商談判断フロー)

時系列: 過去訪問 → 今回 → 次回計画 を縦軸で示す。

inbox-explainer skill / wave domain で N wave 分の振り返り explainer 化。

範囲: <例: Wave 5-10 / Wave 11>
canonical 参照: examples/second-brain/outline.json (ZK + Knowledge OS pattern) /
                examples/todo/outline.json (parallel SOP pattern)

sections 構成 (6-8 section):
01. 全体俯瞰 (hub-and-spoke で N wave を一望)
02-N. 各 wave の Before/After (1 wave = 1 section、確立した skill / pattern を可視化)
N+1. 双璧体制 (Manager/Worker / multi-agent / 二重レビュー)
N+2. メタパターン (繰り返し効いた要素 = 次回再現条件)

履歴: git log / commit refs を末尾 footer に記録。

codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox - <<'EOF'
<<ROLE>> 客観レビュー専門エージェント。manager の成果物を独立評価。

<<CONTEXT>>
レビュー対象: <絶対 path のリスト>
判定基準: <SKILL.md §0 / outline.schema.json / image_prompt_grammar.md / ground_truth_rules.md のうち該当>

<<TASK>>
1. 全対象を read
2. 以下に答える:
   - cold-start 再現性 verdict (APPROVE / NEEDS_FIX / REJECT)
   - CRITICAL findings (file:line + issue)
   - HIGH findings
   - MINOR findings
3. 推奨改善 (manager に渡す指示書フォーマット)

<<OUTPUT>> stdout、構造化 Markdown、末尾 "<<DONE>>"
EOF

codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox - <<'EOF'
<<ROLE>> JSON Schema validator + smoke test 専門。

<<TASK>>
schema: ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle/skills/inbox-explainer/templates/outline.schema.json
target outlines:
- <outline 1 absolute path>
- <outline 2 absolute path>
- <outline 3 absolute path>

PYTHONIOENCODING=utf-8 で jsonschema (Draft202012Validator) を実行し、各 outline の errors=N + 違反 path を報告。
errors > 0 なら schema 側問題か outline 側問題か判定 + 修正提案。

<<OUTPUT>> stdout、各 outline の verdict、末尾 "<<DONE>>"
EOF

# Manager が image prompt を outline.json から準備した後
cd ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle

python3 tools/generate_explainer_images.py \
  --outline <outline.json absolute path> \
  --out-dir <images output absolute path> \
  --workers 4
# 内部で codex exec stdin pipe + ThreadPoolExecutor(max_workers=4)
# 失敗 figure は status=FAIL で報告、retry は §5.3 を使う

codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox - <<'EOF'
<<ROLE>> HTML assembly + deploy executor。

<<TASK>>
1. ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle/tools/build_explainer_html.py を実行
   - --skeleton skills/run-explainer-page/templates/skeleton.html
   - --outline <absolute path>
   - --images-dir <absolute path>
   - --out <index.html absolute path>
2. 生成 HTML が 0 byte でないこと verify (ls -la)
3. (オプション) Cloudflare deploy:
   cd <index.html dir>
   npx wrangler pages deploy . --project-name <slug> --commit-dirty=true \
     --branch main --commit-message "ASCII text only"
4. (オプション) Discord notify:
   curl -s -H "Content-Type: application/json" -d @_discord_payload.json "<webhook>"

<<DONE WHEN>> index.html 存在 + size > 10 KB + (deploy 時) Cloudflare URL を stdout に印字
EOF

bash ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle/tools/run_pipeline.sh \
  --slug <slug> \
  --outline <outline.json absolute path> \
  --project <cloudflare-project-name> \
  --skip-images --skip-deploy --skip-discord

bash ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle/tools/run_pipeline.sh \
  --slug <slug> \
  --outline <outline.json absolute path> \
  --project <slug> \
  --skip-deploy --skip-discord

bash ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle/tools/run_pipeline.sh \
  --slug <slug> \
  --outline <outline.json absolute path> \
  --project <slug> \
  --skip-discord

bash ~/GoogleDrive/GD_Mirror/inbox-explainer-bundle/tools/run_pipeline.sh \
  --slug <slug> \
  --outline <outline.json absolute path> \
  --project <slug>

新規 explainer に Common Limit cross-link を統合:

1. 各 section の callout-warn (アンチパターン) は section 固有の限界のみ書く
2. 全 explainer 共通の制約 (WIP/IPA/single-vendor 等) は本文に書かず、以下を最終 section + footer に追加:

   <strong>⚠️ Common Limitation 必読</strong>: WIP/C2P = 研究用 (NOT 医療機器) / VA60A 推奨 / IPA 締結必須 / Single-vendor → 詳細 <a href="https://explainer-common-limit.pages.dev/">Common Limit page</a>。

3. footer 最後に "| Common Limit: → explainer-common-limit.pages.dev" を追記

利点: 12 個の explainer で同じ警告文を 12 回書かなくて済む、一元更新可能。

新規 explainer に inter-page nav を追加:

1. hero.lede の最後に関連 explainer リンク 1-2 件を inline:
   "...詳細は <a href="https://explainer-<slug>.pages.dev/">A</a> + <a href="https://explainer-<slug2>.pages.dev/">B</a> 参照。"

2. 該当 section に cross-link callout (1 つ):
   <strong>📚 関連</strong>: <a href="...">explainer-A</a> (背景技術) / <a href="...">explainer-B</a> (発展応用)

3. footer に登場する全 cross-link page を列挙

注意: 循環参照 (A→B→A) は 1 度まで許容、無限ループ禁止。

# 04_Output/03_Tools/generate_explainer_images_<slug>_retry.py パターン
"""<slug> retry — 失敗した figure 番号のみ再生成。"""
import sys
sys.path.insert(0, r"<absolute tools dir>")
from pathlib import Path
import generate_explainer_images as gei
import generate_explainer_images_<slug> as src  # 元の script

gei.OUT_DIR = Path(r"<images output absolute path>")
# 失敗した figure 番号だけ抜き出す
gei.FIGURES = [f for f in src.FIGURES if f[0] in ("06", "07", "08")]  # ←適宜変更

if __name__ == "__main__":
    gei.main()

python3 04_Output/03_Tools/generate_explainer_images_<slug>_retry.py