knowledge-synthesis

Imported from xtone/ai_development_tools (knowledge_sharing/skills/knowledge-synthesis/SKILL.md). Install upstream with npx skills add xtone/ai_development_tools --skill knowledge-synthesis. Copyright stays with the author.

Knowledge Synthesis

週ごとに集まったナレッジカードを束ね、対立から提案を出し、次の問いを決める。手順の根拠と判断基準は references/synthesis-method.md にある。このスキルはその手順を実行する。v0 は週次の合成だけを扱う（月次の P2・Q6・Q8 とプロジェクトマップは対象外）。

成果物は 3 つ。

• Notion「合成テーマ」DB の行（1 テーマ 1 行、採否 = 検討中）
• 週の行の配下の「まとめ（<週>）」ページ
• 週の行のステータス = 合成済み

守ること

• 個人別の件数ランキングや、「誰が何を失敗した」は書かない。代表カードの引用は claim とプロジェクトまでにする。投稿者は匿名のラベル（p1、p2 …）で渡すが、ラベルも本文に書かない
• カードに無い事実を足さない。推定は推定と書く
• 人事評価・処遇と経営に関する話題（knowledge-cards の confidential_topics.json）は書かない。強い語に当たるカードは、読み込みの段階で合成から外れる
• Notion への書き込みは、まとめの下書きをユーザーが確認してから行う

引数

$ARGUMENTS を次のように解釈する。

以下、このスキルのディレクトリを <skill-dir>、knowledge-cards のスクリプトを <cards-scripts>（<skill-dir>/../knowledge-cards/scripts）、プラグインのディレクトリを <plugin-dir>（<skill-dir>/../..）と書く。スクリプトはすべて python3 -I で実行する。このスキルは knowledge-cards の機密スキャナと話題判定をそのまま使うので、同じプラグインの knowledge-cards が必要。

作業ファイルは実行したディレクトリ（案件のリポジトリかもしれない）には作らない。<run> は ~/.claude/knowledge-cards/synthesis/<week>/（まとめの下書き summary-<week>.md）、<work> は <run>/.work/（カードの全文、テーマ、Notion に送る内容）。--out を指定したときは <run> がそのディレクトリ、<work> が <out>/.work/ になる。

Phase 0: 準備

1. 対象週を決める: python3 -I <cards-scripts>/cards.py week [--week <week>]。week と title を以降で使う
2. 作業ディレクトリを作る: python3 -I <cards-scripts>/cards.py workdir --kind synthesis --week <week> [--out <out>]。出力の run と work を <run> と <work> に使う
3. <plugin-dir>/notion.json から、週次 Tips・ナレッジカード・合成テーマの data source を読む
4. Notion MCP の query-data-sources で週の行を探す（"週" LIKE '<week>%'）。url、ステータス を控える
   • 週の行が無ければ、合成するカードも無いので、その旨を伝えて終える
   • ステータス が 合成済み か 共有済み なら、既に合成されている。そのまま進めると合成テーマが重複するので、AskUserQuestion で「中止する（推奨）/ dry-run で内容だけ見る」を聞く。既存の行を消したり書き換えたりはしない
5. 段取りを 1 行で伝える（対象週、dry-run かどうか）

Phase 1: カードの読み出し

references/synthesis-method.md の手順 1 の SQL で、週の行のページ ID（URL の末尾 32 桁）を LIKE で含むカードを全件読む。結果は、MCP が返した JSON をそのまま <work>/query-1.json に保存する（100 件を超えたら query-2.json 以降に分ける）。

python3 -I <skill-dir>/scripts/load_cards.py <work>/query-*.json --week <week> --out <work>/cards-<week>.json

出力には、指標（参加者数、問い・極性ごとの枚数、observed の数）、事実カード、意見カードが入る。投稿者は匿名のラベルに置き換わっている。重複は代表カードの duplicates に束ねられる。強い語に当たるカードは外れ、excluded.confidential に件数だけが入る。指標と除外の件数をユーザーに伝える。意見カードが 0 枚なら、事実カードの表だけのまとめになると伝えてから進む。

Phase 2: 合成（Claude が判断する）

references/synthesis-method.md の手順 4〜7 に従い、<work>/cards-<week>.json の意見カードを読んで、<work>/themes-<week>.json を書く。

{"week": "<week>",
 "themes": [{"title": "結論の一文（10〜60 字）", "cards": ["<カードの url>"],
             "proposal": "何をするかの一文（80 字まで、動詞で終える）", "kinds": ["条件分け", "仕組み化"],
             "split": "正と反の分かれ目の一文（80 字まで）。対立が無ければ空",
             "limits": "反証・限界（100 字まで）",
             "decision": "共有会で決める問い（60 字まで、「〜しますか？」で終える）"}],
 "next_questions": [{"id": "Q4", "reason": "なぜ次に聞くか"}, {"text": "新しい問いの案", "reason": "..."}]}

• 意見カードは問いをまたいで束ねる。すべての意見カードを、どれか 1 つのテーマに入れる（1 枚だけのテーマも残す）
• kinds は「両立案」「条件分け」「仕組み化」から選ぶ。仕組み化なら還元先（スキル、hook、CLAUDE.md、プラグイン設定など）を名指しする
• テーマの問い・根拠の強さ（人数・プロジェクト数・枚数）はスクリプトが数えるので書かない
• 対立の分かれ目や合は、カードの文脈と根拠から言えることに限る
• 正と反のカードの claim は書き写さない。まとめと合成テーマの本文に、スクリプトがカードから並べる
• 読み手は Web 制作会社のエンジニアで、開発の進め方を議論するために読む。結論から書き、1 項目 1 文にする。書き方の規則は references/synthesis-method.md の「まとめの読ませ方」

検査して、エラーが 0 になるまで直す。

python3 -I <skill-dir>/scripts/synth.py validate <work>/themes-<week>.json --cards <work>/cards-<week>.json

worked と failed が同じテーマにあるのに分かれ目が空、テーマに入っていない意見カード、事実カードの混入、合や限界の空欄、字数の超過や 2 文以上の項目、「〜か？」で終わらない問い、投稿者ラベルの記載はエラーになる。

Phase 3: まとめの下書きと機密の再確認

python3 -I <skill-dir>/scripts/synth.py render <work>/themes-<week>.json --cards <work>/cards-<week>.json --out <run>/summary-<week>.md
python3 -I <skill-dir>/scripts/synth.py check <run>/summary-<week>.md --cards <work>/cards-<week>.json

check は、今週のカードへのメンションだけを除いた本文に、機密スキャナとカードにしない話題の判定をかける。行ごとと、改行をつないだ全文の両方を見る（改行や見えない文字で分けた語も止まる）。

• 強い語・秘密情報: themes-<week>.json の該当箇所を消して、render からやり直す
• 要確認の語（昇格、退職など）: カードに含まれていても自動では通さない。当たった語と行をユーザーに示し、AskUserQuestion で「人事評価・処遇や経営の話ではない」と確認できた語だけ、--allow-term <語> を付けて check をやり直す。確認できなければ、その文を消す。通した語は以降の to-notion と再確認にも同じ --allow-term を付ける

問題が 0 件になるまで Phase 4 に進まない。

Phase 4: 確認

1. テーマの一覧（テーマ名、対立の有無、合の一文、根拠の強さ）と次の問いを表示する。<run>/summary-<week>.md を開けば全文を読めると伝える
2. AskUserQuestion で聞く: 「Notion に書き込む」「themes を直したので読み直す」「書き込まずに終える」
3. 「読み直す」なら Phase 2 の validate からやり直す

--dry-run のときは、次の synth.py to-notion の出力と、まとめの本文を表示して完了報告に進む。

Phase 5: 書き込み

1. 合成テーマ DB に、同じ週の行が既に無いかを query-data-sources で確かめる（"週" LIKE '%<週の行のページ ID>%'）。あれば書き込まずに止め、ユーザーに伝える
2. 合成テーマを作る

python3 -I <skill-dir>/scripts/synth.py to-notion <work>/themes-<week>.json --cards <work>/cards-<week>.json --week-url <週の行の URL> [--allow-term <確認済みの語> ...] > <work>/theme-pages.json

to-notion は、テーマの文章が check と同じ判定を通らないと、出力せずにエラーで止まる。各要素の properties と content を create-pages の pages[] に入れる（parent は合成テーマの data source、allow_async: false）。返ってきた URL を title と組にして <work>/theme-urls.json（[{"title": "...", "url": "..."}]）に書く。

3. テーマへのメンション付きで、まとめを作り直して再確認する

python3 -I <skill-dir>/scripts/synth.py render <work>/themes-<week>.json --cards <work>/cards-<week>.json --theme-urls <work>/theme-urls.json --out <run>/summary-<week>.md
python3 -I <skill-dir>/scripts/synth.py check <run>/summary-<week>.md --cards <work>/cards-<week>.json --theme-urls <work>/theme-urls.json [--allow-term <確認済みの語> ...]

--theme-urls を渡すと、作ったテーマのページへのメンションも検査から除く。それ以外のメンションは URL ごと検査される。

4. 週の行の配下に「まとめ」ページを create-pages で作る（parent は {"type": "page_id", "page_id": "<週の行のページ ID>"}、properties は {"title": "まとめ（<week>）"}、icon は 🧭、content は <run>/summary-<week>.md の中身）
5. fetch でまとめページを読み返し、崩れ（ファイル名の自動リンクなど）が無いか確かめる。あれば update-page の update_content で直す
6. 週の行の ステータス を update-page（update_properties）で 合成済み にする

Phase 6: 後片付け

Phase 5 の 6（週の行を 合成済み）まで終わったら、その回の作業ディレクトリを消す。カードの全文が手元に残らないようにするため。

python3 -I <cards-scripts>/cards.py cleanup <run>

--dry-run、確認で「書き込まずに終える」を選んだとき、途中で止まったとき、--out を指定したとき（cleanup が拒否する）は消さずに残し、完了報告で <run> のパスを伝える。

完了報告

• 対象週、参加者数、カード枚数（問い別）、除外した件数（重複・カードにしない話題）
• テーマ数・対立数・提案数と、テーマ名の一覧
• 次の問い
• まとめページと合成テーマの URL（--dry-run のときはその旨）
• 共有会で採否を決めること（合成テーマの 採否 を共有会で更新する）

作業ディレクトリを消したかを伝える。残したときはそのパスと、カードの全文を含むので共有リポジトリにコミットしないことを伝える。