research-writeup

name	research-writeup
description	技術調査の結果を、原文引用つきの自己完結型HTMLレポートにまとめるスキル。同梱の生成器 assets/render.py にJSONを渡すと、事実/解釈を視覚分離した比較表・根拠(原文引用)・ADRを含むHTMLを出力する。解説文で出典を引用したら、そのすぐ後に「原文+日本語訳(非日本語のみ)+リンク」を置き、末尾に出典を一括しない。要約は自分の言葉で簡潔に書き、引用する原文は最小限の範囲にとどめる。技術選定・障害調査・実装調査の結果を「HTMLでまとめて」「図解して」「比較表にして」「ADRを書いて」と言われたとき、また調査内容を判断可能な形で残す必要があるときは必ずこのスキルを使うこと。成果物は調査ごとに新しいHTMLファイルとして出力する。Claude Code 環境での利用を前提とする。

調査結果のまとめ・図解(research-writeup)

調査資料の価値は「後から検証でき、判断に使える形にしたこと」にある。このスキルは調査結果を 原文引用つきの自己完結型HTMLレポート にまとめる。成果物は調査ごとに新しいHTMLファイル(1調査=1ファイル、上書きしない)。

生成方法

レポートは手書きせず、同梱の生成器を使う(スタイルとSVG座標が常に一定になる)。

python <skills>/research-writeup/assets/render.py <data.json> <out.html>

assets/sample_data.json が入力の実例、assets/template.html が出力見本(スタイルのたたき台)。

情報の信頼性と原文引用(必須)

簡潔さは必須だが、信頼性が最優先。事実として書く主張には、信頼できる情報源(公式ドキュメント等)の原文を必ず添える。

• 主張は自分の言葉で簡潔に書き、その直後に 原文引用ブロック(citation)を置く。
• 引用ブロックは「原文」「日本語訳(原文が日本語以外のときのみ)」「出典リンク(URL+アクセス日+バージョン)」で構成する。生成器が自動でこの体裁にする。
• リンクはその引用のすぐ後に置く。末尾に出典を一括しない。
• 引用する原文は最小限の範囲にとどめる(定義文1つ、設定値、シグネチャなど)。段落まるごとの転載はしない。1つの出典から何度も長く引かない。これは著作権配慮であり、簡潔さの要件とも一致する。
• 非日本語の原文には忠実な日本語訳を付ける。訳は意訳しすぎず、原文の意味を保つ。

事実と解釈の分離

• 事実(出典から得たこと)と 解釈・判断(こちらの評価・推奨)を、見た目でも分ける。生成器は解釈を .interpretation ブロック(色付き枠+ラベル)に隔離する。事実の要約に推奨を混ぜない。
• 裏取り状況を badge(ok=確認済 / warn=要確認 / na=不明)で明示する。source-verification のラベルをそのまま持ち込む。

JSONスキーマの要点(sample_data.json 参照)

• title / date / candidates_label / verification_note / sample(trueでSAMPLEタグ)
• requirements: purpose / must[] / want[]
• candidates[]: name / color(省略可) / scores{軸:値}(任意。ポジショニング図に使う場合のみ)
• positioning(任意): x / y(軸名)。scores がある候補だけ描画。無ければ図は出ない。
• comparison(任意): rows[]{axis, cells[]{text, badge, url(セル内インライン出典)}}
• findings[]: 根拠セクション。candidate ごとに items[]:
  • claim(自分の言葉の主張) / badge / citation{quote(原文), lang, translation(訳、非日本語時), source, url, accessed, version}
• recommendation: options_note / flow(任意){question,yes,no} / interpretation / citations

レーダーチャートは使わない(廃止済み)。図解は任意のポジショニングマップと、条件付き推奨の意思決定フローのみ。

スタイル調整

見た目を変えるときは assets/render.py 上部の CSS と各SVG関数だけを編集する。1ファイルの修正が全レポートに反映される。

障害・実装調査に使う場合

比較表の代わりに findings を「調べた目的 / わかったこと(事実+原文引用+バッジ)/ 残った疑問」に読み替える。当てはめ・評価は interpretation 側に置く。原文引用と事実/解釈分離の原則は同じ。

出力時の注意

• 調査ごとに新規ファイル(.html)。上書きしない。命名例:tech-selection_<topic>_<YYYYMMDD>.html。
• 自己完結型(CSS・SVGインライン、外部依存なし)。render.py はこれを満たす。
• 裏取りできていない主張を確定情報として載せない。原文が示せない主張は badge を warn/na にする。