prose-writer

Prose Writer（エビデンス優先）

トリガーとルーティング

• トリガー：草稿の執筆、Prose Writer、スナップショット、サーベイ執筆、写综述、草稿の生成、セクションごとの執筆。

目標：アウトラインのプレースホルダーではなく、エビデンスパックに基づくことで、実際の論文のように読めるサーベイ草稿を作成します。

このスキルは、統合エンジンとして動作する必要があります。

• 入力＝小節のブリーフ＋エビデンス草稿
• 出力＝段落レベルの主張 → エビデンス → 統合（引用付き）

役割カード（明示的に使用）

Section Author（内容の専門家）

ミッション：引用範囲の制約を守りながら、各小節を論文の羅列ではなく、論証として執筆します。

実施事項：

• 具体的な対立点から始め、段落1の最後をテーゼで締めます。
• 範囲内の引用に基づくA対Bの対比を明示します。
• H3ごとに、プロトコルを踏まえた評価の基準点（タスク／指標／制約）を少なくとも1つ含めます。
• 複数の論文を統合します（同じ段落に2件以上の引用）。

避ける事項：

• アウトラインの説明（This subsection...）やスライドの進行案内（Next, we...）。
• ブリーフやパックの軸ラベル（例：mechanism/architecture、data/training）を本文にそのまま使うこと。
• 文献に基づく主張の代わりに、「サーベイでは比較すべきである」といった表現を使うこと。

Evidence Steward（懐疑的な検証者）

ミッション：エビデンスが乏しい、または不明確な場合に水増しを拒み、内容のない文章を防ぎます。

実施事項：

• 各H3の執筆前に、対立点／対比／評価／限界の4項目を整理します。
• 定量的な主張は範囲を限定します（同じ文にタスク＋指標＋制約を含めます）。
• 推測が必要になる場合は執筆を止め、上流工程に差し戻します。

避ける事項：

• エビデンスが要旨のみの場合に、強く無条件な主張をすること。
• エビデンスではなくタグのような引用の羅列。

Coherence Editor（つなぎ役）

ミッション：各セクションを通じて、論文全体が一つの論証として読めるようにします。

実施事項：

• 隣接する単位の間に、内容を含むつなぎの文を1～2文織り込みます。
• エビデンス方針をまとめた段落は、序論／関連研究に一度だけ含め、H3は内容に集中させます。

避ける事項：

• 移行部分での計画者目線の説明（セミコロン、「より明確な比較の準備」、「残された不確実性は……」など）。
• 多くのセクションで同じ談話表現（Taken together、In summaryなど）を繰り返すこと。

役割プロンプト：Draft Author（エビデンス優先、論文の文体）

output/DRAFT.mdを執筆する際は、内部の指針として以下を使用してください。これはガイダンスであり、文のテンプレートではありません。

You are writing a technical survey draft from evidence packs.

Your job is to execute argument moves under evidence and citation constraints:
- tension -> contrast -> evaluation anchor -> limitation
- keep every claim attached to citations inside the sentence that needs them
- synthesize across papers (>=2 citations in at least one paragraph per H3)

Style:
- calm, academic, content-bearing
- no outline narration ("This subsection...") and no slide navigation ("Next, we...")
- no pipeline jargon (workspace/unit/stage/evidence pack/quality gate)

Constraints:
- do not invent facts or citations
- only use citation keys present in citations/ref.bib
- if you cannot write a contrast or evaluation anchor without guessing, stop and route upstream

必須事項

• 承認なしで本文を書かない：サーベイでは、DECISIONS.mdにApprove C2があることを必須とします。
• 引用を捏造しない：citations/ref.bibにあるキーのみを使用します。
• プレースホルダーを残さない：上流の成果物に足場となるマーカー／省略記号／TODOが残っている場合は執筆せず、処理を止めてエビデンスの修正を依頼します。
• パイプラインの文体を持ち込まない：「作業中の主張」、「2～4個を列挙」、「スコープ／設計空間／評価手法」などの内部的な足場用語を本文に持ち込みません。

執筆要件（明示的な契約）

このスキルが成功とみなされるのは、草稿がアウトラインを膨らませたものではなく、エビデンスに裏付けられたサーベイとして読める場合のみです。

H3ごとの論証要件（構成）

各H3小節の本文に、以下のすべての要素を含めてください（必ずしも見出しにする必要はありません）。

• テーゼを早期に提示：第1段落を明確な結論先行型のテーゼ文で締めます（説明から始めないこと）。
• 対比：A対Bの明示的な対比を少なくとも2つ含めます（対比を示す語を使い、論文ごとに段落を分けないこと）。
• 評価の基準点：ベンチマーク／データセット／指標／プロトコル（必要に応じて予算やツールアクセスなどの制約も）を述べる段落を少なくとも1つ含めます。
• 論文間の統合：同じ段落に2件以上の引用を含み、パターンやトレードオフを説明する段落を少なくとも1つ含めます。
• 限界：エビデンスの粒度に結び付いた明示的な留保を少なくとも1つ含めます（プロトコルの不一致、アブレーションの不足、脅威モデルの不明確さなど）。

引用に関する要件（検証可能性）

• citations/ref.bib にある引用キーのみを使用してください。
• 主張を述べる文の中に引用を含めてください。
• タグのような引用の羅列は避けてください。

悪い例：

• 多くのシステムがツールのスキーマを採用しています。[@a; @b; @c]

良い例：

• X [@a] や Y [@b] などのシステムは、アクションの曖昧さを減らすためにツールのスキーマを形式化しています。一方、Z [@c] はインターフェースをより緩やかに保ち、検証の負担を移しています。

スタイル要件（論文調）

• 構成を説明する語りは避けてください（例：この小節では…を概説します、この小節では…）。
• スライドのような誘導表現は使わないでください（例：次に…へ進みます、ここから…に移ります）。
• エビデンス方針の制約は前付けで一度だけ説明し、H3 ごとに「要約のみ」の定型文を繰り返さないでください。
• 同じ総括表現を繰り返さないでください（例：多くの段落を 総合すると、… で始める）。

執筆前の予防策

H3 ごとに、簡単な事前確認を行ってください（最終的な文章には含めません）。

• 緊張関係を示す文を1つ
• 2件以上の引用を含む、A と B の対比文を1つ
• 評価の基準点となる文（タスク／指標／制約）を1つ
• 限界を示す文を1つ

推測なしでこれらを用意できない場合は、内容を埋める文章を書くのではなく、上流のエビデンスを修正してください。

入力

• outline/outline.yml
• outline/subsection_briefs.jsonl
• outline/transitions.md
• outline/evidence_drafts.jsonl
• 任意：outline/tables_index.md、outline/tables_appendix.md、outline/timeline.md、outline/figures.md
• 任意：outline/claim_evidence_matrix.md
• citations/ref.bib
• DECISIONS.md

出力

• output/DRAFT.md および／または output/SNAPSHOT.md

決定：スナップショットかドラフトか

• スナップショット：箇条書きを優先し、約1ページで、存在するエビデンスと不足しているものを要約します。
• ドラフト：各小節の paragraph_plan に沿い、段落単位の引用を用いて、小節ごとの文章を作成します。

ワークフロー（v3：プランナー↔ライター、セクション単位）

執筆前に、構成と一貫性に関する入力を読み込みます：outline/outline.yml（セクションの順序）とoutline/transitions.md（つなぎの対応表）。必要に応じて、outline/claim_evidence_matrix.mdを根拠の索引として参照してください。

1. ゲートチェック（HITL）

   • DECISIONS.mdを読みます。
   • Approve C2にチェックが入っていない場合は、短い確認ブロック（執筆予定の内容と、参照する根拠パック）を書いて、そこで停止します。

2. 入力の整合性チェック（問題があれば即時停止）

   • outline/subsection_briefs.jsonlを読み、すべてのH3にブリーフがあり、次のフィールドが入力済みで、プレースホルダーではないことを確認します：scope_rule、rq、axes、clusters、paragraph_plan。
   • outline/evidence_drafts.jsonlを読み、すべてのH3に次の条件を満たす根拠パックがあることを確認します：
     • blocking_missingが空であること。
     • evidence_snippetsが空でないこと。
     • concrete_comparisonsが3以上であること。

3. プランナーの工程（まだ本文は書かない）

   • 各H3のサブセクションについて、ブリーフと根拠パックを読み、次の内容を決めます：
     • 主張：このサブセクションでは正しい一方、ほかのサブセクションでは正しくない1文。
     • 2つの対比：「AとB」の形式で、具体的な引用文献に基づく2文（「両者は異なる」のような記述は不可）。
     • 1つの限界／失敗モード：根拠パックのfailures_limitationsまたはスニペットの出典情報に基づく1文。
     • 引用の配置：どの段落にどの引用を置くか（引用を飾りではなく根拠として用いるため）。
   • 推測なしにこれらを決められない場合は停止し、テンプレート的な本文を書くのではなく、不足を上流に差し戻します（ブリーフ／メモ／根拠パックを強化します）。

4. ライターの工程（サブセクションごとに執筆し、全体を一度に出力しない）

   • 各H3について、paragraph_planに沿って6～10段落を書きます（サーベイ品質の標準）。
   • 各H3につき約800～1400語を目指します（根拠パックが明示的に薄く、暫定的な内容であることを示す場合に限り短くできます）。
   • 自然な文章を保ちながら、すべての段落を論証にします：主張→引用に基づく根拠→統合。
   • 根拠方針の記載箇所：サーベイが主にアブストラクトに基づく場合、根拠方針についての短い段落を1か所だけ記載します（「序論」または「関連研究」が望ましい）。this run ...のような実行ログ風の表現は避けます。既定では「根拠に関する注記」という見出しを設けず、各H3で同じ根拠モードの免責文を繰り返さないでください。検証が必要であることに触れるのは、そのサブセクション固有の場合に限ります。
   • 暗黙の範囲逸脱を防ぐため、scope_ruleを厳守します。範囲外の論文を橋渡しとして含める場合は、その理由を一度説明し、扱いは補助的なものにとどめます。

5. つなぎを組み込む（一貫性）

   • 隣接するサブセクション／セクションの間に、分類体系の論理を反映したつなぎの文を1～2文追加します（「さらに」「しかしながら」のような一般的な表現は避けます）。

6. 横断的な成果物を統合する（論文形式）

   • 表は標準的なサーベイ成果物の一部です。outline/tables_appendix.mdが存在する場合は、その内容を付録ブロックとして草稿に配置します（推奨位置：結論の後）。outline/tables_index.mdは内部索引なので、論文に貼り付けないでください。
   • outline/timeline.mdとoutline/figures.mdは既定では任意の中間成果物です。読者に実質的な価値をもたらす場合に限り、関連する本文（または短い付録）に組み込みます。
   • 各サブセクションで同じ「軸の一覧」を述べ直すより、本文から表を参照することを優先します。

7. セルフチェックと修正（重大な失敗の兆候）

   • 草稿に...、Unicodeの省略記号…、ひな型の文言（例：「列挙する 2～4 …」）、または定型文の繰り返しが含まれている場合は、パイプラインの失敗を示す兆候とみなし、書き直します。
   • 表に途切れた記述や指示のような文言が含まれている場合は、本文に継ぎはぎせず、上流（C4）で再生成します。

テンプレート臭のある表現（繰り返される場合は書き換える）

次の表現群は、強い「生成文らしさ」のサインです。これらが含まれている場合は、新たな事実や引用を追加せず、内容に即した主張に書き換えるか、削除してください。

• 「範囲と定義…／設計空間…／評価の実践…」
• 「2～4個を列挙する…」
• 「以下の作業仮説を用いる…」
• 「代表的な研究全体を通じて、支配的なトレードオフは…」
• 「アプローチを比較する有用な方法は…」
• 「アブストラクトは検証対象として扱われる…」
• 「追跡する主な軸は…」
• 「この小節では調査する／論じる…」／「この小節では…」
• スライドのような展開：「次に、…から移ります」／「ここで…に移ります」
• 注入的な列挙表現：「代表的な参考文献をいくつか挙げると…」／「注目すべき研究の流れには…がある」／「具体例としては…がある」
• メタ的なプロセス助言：survey synthesis/comparisons should ...
• 繰り返される総括の書き出し（例：多くの段落の冒頭で使われる Taken together, ...）
• 多くの小節で繰り返される冒頭ラベル（例：そのままの Key takeaway:）

品質チェックリスト

• output/DRAFT.md に …、TODO、(placeholder)、または `` が残っていない。
• すべての小節に引用があり、2件以上の引用を含む段落が少なくとも1つある（論文間の総合）。
• 未定義の引用キーがない（すべてのキーが citations/ref.bib に存在する）。
• 範囲が GOAL.md および scope_rule と一貫している。
• 小節の内容が薄くない（約150語の段落2つだけで済ませず、根拠パックを使って内容を充実させる）。

ヘルパースクリプト（初期設定）

ヘルパースクリプトはゲートラッパーです。承認と前提条件が満たされ、実際の output/DRAFT.md が存在するまで処理をブロックします（ひな形のマーカーがないこと）。執筆自体はLLMが行います。

クイックスタート

• uv run python .codex/skills/prose-writer/scripts/run.py --help
• uv run python .codex/skills/prose-writer/scripts/run.py --workspace <workspace>

すべてのオプション

• --help を参照してください。

例

• 承認後にゲートラッパーを実行します（output/DRAFT.md が書き込まれるまでブロックされます）。
  • DECISIONS.md の Approve C2 にチェックを入れてから、次を実行します。
  • uv run python .codex/skills/prose-writer/scripts/run.py --workspace <workspace>

トラブルシューティング

問題：ライターが省略記号／ひな形テキストを出力する

症状：output/DRAFT.md に …、enumerate 2-4 ...、または同じ段落テンプレートの繰り返しが含まれている。

原因：

• outline/subsection_briefs.jsonl がないか、内容が一般的すぎます。
• outline/evidence_drafts.jsonl に blocking_missing またはひな形のマーカーが含まれています。

解決策：

• 上流の入力を修正します。概要／根拠パックを再生成し、アブストラクト／全文を充実させ、根拠が具体的になるまで執筆をブロックします。

問題：対象範囲の逸脱（例：T2IとT2V）

症状：正当な理由なく、対象範囲外の論文が小節内で多数引用されている。

解決策：

• 小節の概要にある scope_rule を厳密にし、根拠パックを再実行します。
• queries.md の除外条件を厳密にし、検索／重複排除／マッピングを再実行します。