research-writeup

調査結果のまとめ・図解(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 にする。