ppw:repo-to-paper

目的

このスキルは、Python の ML 実験リポジトリをスキャンし、各見出しレベルでユーザーの承認を得ながら、階層構造の論文アウトライン（H1/H2/H3）を生成します。実験を終え、研究成果を学術論文として構成する必要がある研究者を対象としています。references/repo-patterns.md のパターンに基づいてリポジトリ内のファイルを分類し、粗い構成（セクション）から細かい構成（小節）へと見出しを段階的に生成します。次のレベルへ進む前に、ユーザーが各レベルを確認または修正します。H2 の確認後、このスキルは Semantic Scholar MCP を使って学術文献を自動収集し、後続の本文生成で使用するセクションごとの参照ファイルとして保存します。

トリガー

次のような依頼があった場合に起動します：

• リポジトリまたはコードベースから論文の構成、アウトライン、または骨子を生成する
• プロジェクトをスキャンし、実験コードや結果から論文のセクションを作成する
• 实验仓库/代码仓库生成论文大纲或论文结构

呼び出し例：

• "Generate a paper outline from my repo"
• "帮我从实验仓库生成论文大纲"
• "Scan my project and create paper structure"
• "把我的代码仓库转成论文框架"

モード

モード	デフォルト	動作
guided	はい	各見出しレベルで確認し、セクションごとに本文を生成する、5ステップのワークフロー全体を実行します
direct		サポート対象外です。アウトライン生成では、各レベルでユーザーによる検証が不可欠です
batch		サポート対象外です。リポジトリごとに個別の分析が必要です

デフォルトモード： guided。段階的な確認設計は、このスキルの中核です。

参照資料

必須（常に読み込み）

ファイル	用途
references/repo-patterns.md	ファイル分類パターンとセクション対応ルール
references/bilingual-output.md	バイリンガル出力形式（このスキルはバイリンガル出力に対応しています）
references/body-generation-rules.md	幻覚防止ルール、引用の統合、バイリンガル形式、references.bib のアルゴリズム
references/journals/ceus.md	CEUS ジャーナルの書式仕様（文体、セクションの指針）

下位参照のヒント

ありません。ステップ 5 の本文生成では常に CEUS の書式が必要なため、すべての参照ファイルを required に含めています。

読み込みルール

• ステップ 1 の開始時に repo-patterns.md と bilingual-output.md を読み込みます。
• ステップ 5 の開始時に body-generation-rules.md と journals/ceus.md を読み込みます。
• ジャーナルのテンプレートファイルが見つからない場合は、次のように回答して依頼を断ります："Journal template for [X] not found. Available: CEUS."

質問方針

開始前に確認する項目：

1. リポジトリのパス（必須）："Which repository should I scan?" — 利用可能であれば構造化された対話を使用します
2. 投稿先のジャーナル（任意）："Which journal is this paper targeting?" — 選択肢：CEUS、その他、なし／一般。 CEUS の場合はステップ 2 でテンプレートを読み込みます。その他の場合はジャーナル名を尋ねます。なしの場合は IMRaD をデフォルトとして使用します

バイリンガルモード： トリガー文から推定します。references/bilingual-output.md に記載されたオプトアウト用キーワード（正確なフレーズ：english only、no bilingual、only english、不要中文）を確認します。明示的に尋ねないでください。

ルール：

• 明示的な質問は 2 つまでにします（リポジトリのパスとジャーナル）
• direct モードでは質問を省略します。ただし、このスキルでは direct モードはサポートされていません

ワークフロー

ステップ 0：ワークフローメモリの確認

• .planning/workflow-memory.json を読み込みます。ファイルが存在しないか、空の場合は、ステップ 1 に進みます。
• 最後の 1～2 件のログエントリが、ログ内にしきい値以上の回数登場している ppw:repo-to-paper の既知のパターンを形成しているか確認します。アルゴリズムの全容については、skill-conventions.md > Workflow Memory > Pattern Detection を参照してください。
• パターンが見つかった場合は、AskUserQuestion を使って次の推奨事項を提示します。
  • 質問：「常用流程：[pattern]（已出现 N 次）。是否直接以 direct 模式运行 ppw:repo-to-paper？」
  • 選択肢：「はい、続行します」／「いいえ、通常どおり続行します」
• ユーザーが承諾した場合：モードを direct に設定し、Ask Strategy の質問をスキップします。
• ユーザーが承諾しなかった場合、または AskUserQuestion を利用できない場合：通常モードで続行します。
• 注： このスキルは完全な direct モードには対応していません。ユーザーが推奨事項を承諾した場合は、推定されるコンテキストを使って Ask Strategy の質問（リポジトリのパス、ジャーナル）をスキップしますが、ガイド付きのステップチェックポイント（ステップ 2～5 の確認）は維持します。出力要件に変更はありません。

ステップ 1：リポジトリをスキャンする

準備：

• references/repo-patterns.md と references/bilingual-output.md を読み込みます。
• リポジトリのディレクトリ構造を読み込みます（上位 2 階層：ルートと第 1 階層のサブディレクトリ）。
• repo-patterns.md の File Identification Patterns テーブルを使って、各ファイルを分類します。
• 複数のカテゴリに該当するファイルには、曖昧さに関するルールを適用します（優先順位の番号が最も小さいものを採用します）。
• repo-patterns.md の Skip Rules に従い、隠しファイル、テストファイル、バイナリデータファイルを除外します。

提示：

• カテゴリ別の概要テーブルを表示します。

  カテゴリ	見つかったファイル	主な項目
  documentation	3	README.md, docs/overview.md
  results	5	results/metrics.csv, scores.json

• 該当ファイルがないカテゴリには、「[カテゴリ] ファイルが見つかりません」と記載します。

• 概要行：「N 個のカテゴリで M 個のファイルをスキャンしました。H1 アウトラインの生成に進みます……」

• ユーザーは確認や修正を希望する場合、中断できます。それ以外の場合は、自動的にステップ 2 に進みます。

• ワークフローを記録： {"skill": "ppw:repo-to-paper", "ts": "<ISO timestamp>"} を .planning/workflow-memory.json に追加します。ファイルが存在しない場合は [] として作成します。ログが 50 件以上の場合は、最も古いエントリを削除します。

---

ステップ 2：H1 アウトラインを生成する

準備：

• ジャーナルが指定されている場合（例：CEUS）は、references/journals/[journal].md を読み込み、その Section Guidance の見出しを H1 構成として使用します。CEUS のセクション：Abstract、Introduction、Study Area / Data / Methods、Results、Discussion、Conclusion
• ジャーナルが指定されていない場合は、IMRaD のデフォルトを使用します：Introduction、Methods、Results and Discussion、Conclusion
• スキャン結果に基づいて基本セクションを調整します（例：空間データが検出された場合は「Study Area」を追加）。

提示：

• 1 文の説明を添えて H1 見出しを表示します。

  # 1. Introduction
      Establish research context, literature gap, and contribution statement.
  # 2. Methods
      Describe the analytical approach, data sources, and model architecture.
  

• バイリンガルモードが ON の場合は、references/bilingual-output.md に従い、各説明の中国語訳を Markdown の引用形式で追加します：> **[Chinese]** ...
• 概要行：「N 個の H1 セクションを生成しました。H2 に進む前に、確認、変更、または追加を行ってください。」
• ユーザーの確認（「ok」）または変更指示を待ちます。

変更時： ユーザーのフィードバックに従って H1 見出しを修正し、再表示します。確認されるまで繰り返します。

セクション調整の例：

• スキャンで空間データファイル（shapefile、GeoJSON）が見つかった場合 → 「Study Area」H1 セクションの追加を検討します。
• スキャンで結果ファイルが見つからなかった場合 → Results セクションに警告プレースホルダーを付けます。
• スキャンで複数の異なるモデル実装が見つかった場合 → Methods を複数のアプローチに分割することを検討します。

---

ステップ 3：H2 アウトラインの生成

準備：

• 確認済みの各 H1 セクションについて、関連するリポジトリのファイルを読み、H2 の小見出しを生成します
• repo-patterns.md のカテゴリと論文セクションの対応表を使用して、各 H1 セクションに関連するファイルを特定します
• 実際のファイルの内容を読みます（Introduction では README、Methods では設定ファイル、Results では結果ファイル）。H2 の生成には、ディレクトリ構成だけでなく、内容を読む必要があります
• 各 H1 セクションに対して、1 文の説明を添えた H2 の小見出しを 2～4 個生成します

提示：

• 各 H2 にソース注釈を付けて、H1 と H2 の階層全体を表示します：

  # 1. Introduction
  ## 1.1 Research Background and Motivation  <- from: README.md
      Urban heat island measurement requires fine-grained spatial analysis approaches.
  ## 1.2 Literature Gap and Contribution  <- from: README.md
      Existing methods lack integration of street-level semantics with thermal data.
  

• ソース注釈：最も関連性の高いファイルを 1～3 個記載します（repo-patterns.md に基づき、優先度の高いファイルを選びます）
• バイリンガル：ON の場合は、> **[Chinese]** ... の引用形式で中国語の説明を追加します
• ステップ 2 と同じ確認手順を行います：「M 個の H1 セクションにわたって N 個の H2 小見出しを生成しました。H3 に進む前に、確認、修正、または追加してください。」

---

ステップ 2.5：文献の収集

事前確認：

• {"query": "test", "limit": 1} を指定して mcp__semantic-scholar__papers-search-basic を呼び出します
• 呼び出しに成功した場合：以下の文献収集に進みます
• 呼び出しに失敗した場合、またはツールを利用できない場合：ステップ 2.5 全体をスキップします
  • アウトライン内の各 H2 小見出しの説明の後に [CITATION NEEDED] を挿入します
  • 「Semantic Scholar MCP を利用できません。文献の収集をスキップします。[CITATION NEEDED] マーカーを追加しました。」と表示します
  • ステップ 4（H3 の生成）に直接進みます

参考文献の収集：

各 H1 セクションについて： この H1 の各 H2 小見出しについて： 1. 検索クエリを作成します。H2 のタイトルと説明から、H1 セクションのタイトルに関連する重要な技術用語を 2～5 個抽出します。英語の用語のみを使用します（バイリンガルモードでは中国語訳を無視します）。不要語（and、of、the、for）を除外します。 例：H1="Methods"、H2="Gradient Boosting Prediction Framework"、 説明="Feature engineering using street-level semantic segmentation data" -> クエリ："gradient boosting prediction street-level semantic segmentation" 2. {"query": derived_query, "limit": 10} を指定して mcp__semantic-scholar__papers-search-basic を呼び出します 3. abstract フィールドが空の各検索結果について、その論文の paperId を指定して mcp__semantic-scholar__get-paper-abstract を呼び出します。取得後も abstract が空の場合は、「Abstract not available」と記載します 4. 関連性に基づいて結果を絞り込みます。H2 の小見出しで述べる必要のある主張や論点がいくつあるかを評価し、それらを最もよく裏付ける論文を 5～10 本選びます。タイトルと abstract の内容から、関連性が薄いだけの論文は除外します 5. 進捗行を表示します：✓ 1.1 Research Background: 8 refs found（結果が 0 件の場合は ⚠ 1.1 Research Background: 0 refs found） 6. 一括検索の途中で検索呼び出しに失敗した場合、その H2 を [CITATION NEEDED] とし、警告を表示して、次の H2 に進みます 終了 終了

参考文献ファイルの作成：

{repo_path}/.paper-refs/ ディレクトリを作成します。各 H1 セクションにつき Markdown ファイルを 1 つ作成し、セクションのトピックを小文字にした名前を付けます（例：introduction.md、methods.md、results.md）。

各ファイルは次の構成にします。

# [H1 Section Title] - References

## [H2 Number] [H2 Subsection Title]

### [FirstAuthor] et al. ([Year])
**Title:** [Full title from MCP]
**Authors:** [Author1; Author2; ...]
**Year:** [YYYY] | **Citations:** [N]
**Relevance:** [[H2 number] [H2 subsection title]]
[One-sentence explanation of why this paper is relevant to this subsection]

> [Abstract summary: 1-2 sentences from MCP abstract data. If abstract not available, write "Abstract not available"]

```bibtex
@article{[citationkey], ...}

BibTeX rules (reuse literature-skill patterns):
- Citation key format: `firstAuthorLastnameLowercaseYYYYfirstKeyword` (e.g., `smith2023urban`)
- Entry type: `@article` for journal, `@inproceedings` for conference, `@misc` for preprints (follow MCP paper type)
- All BibTeX fields MUST come from MCP-returned data. If a field is not in the MCP response, OMIT it
- If DOI missing, add comment: `% DOI not available -- verify manually`
- Never fill missing fields from prior knowledge

Duplicate handling: allow same paper to appear in multiple section files. Each file is self-contained.

**Display summary table:**

After all H2 subsections processed, display:

セクション	小見出し	参考文献数	主要な参考文献
1. Introduction	1.1 Research Background	8	Smith et al. (2023) - 142 citations
...	...	...	...
合計：[N] 件の参考資料を収集しました。H3 アウトラインの生成に進むことを確認してください。

Wait for user confirmation before proceeding to Step 4.

---

### Step 4: Generate H3 Outline

**Prepare:**
- For each confirmed H2 subsection, read deeper file contents to generate H3 sub-sub-headings
- H3 captures specific technical details: individual model components, specific metrics,
  particular datasets, analysis steps
- Not every H2 needs H3 -- generate only where repo content supports further breakdown
  (typically Methods and Results). Generate 0-3 H3 entries per H2 subsection

**Present:**
- Display full H1 + H2 + H3 hierarchy with source annotations on H3 entries:

1.1 研究の背景と動機

1.1.1 都市ヒートアイランドの測定における課題 <- from: README.md:L15-30

  現在の都市ヒートアイランド（UHI）の測定方法は、解像度に限りのある衛星画像に依存しています。

- Bilingual: if ON, add Chinese descriptions in `> **[Chinese]** ...` blockquote format
- Same confirmation loop as Step 2: "Generated N H3 sub-subsections. Please confirm, modify,
or add. This completes the outline structure."

---

### Step 5: Body Generation

Step 5 auto-continues in the same session after H3 confirmation. It uses the H3 outline already in memory -- does not re-read `paper_outline.md`.

**Prepare:**
- Load `references/body-generation-rules.md` and `references/journals/ceus.md`
- Check if `{repo_path}/.paper-refs/` exists. If missing: note that all citation positions will use `[CITATION NEEDED]`
- Create `{repo_path}/.paper-output/` directory if it does not exist

**Section selection:**
- Display all H1 sections via AskUserQuestion (multiSelect):

AskUserQuestion({ question: "本文を生成するセクションを選択してください。", options: [ { label: "1. [H1 title]", description: "[H2 subsection summary]" }, ...one option per H1 section from confirmed outline ] })

- User selects which sections to generate in this session

**Generation loop (for each selected H1 section, sequentially):**

1. Read relevant repo files using the Category to Paper Section Mapping from `references/repo-patterns.md`
2. Read `{repo_path}/.paper-refs/{section}.md` if it exists -- extract `\cite{key}` citation keys
3. Generate full section `.tex` content following ALL rules in `references/body-generation-rules.md`:
 - `\section{}`, `\subsection{}`, `\subsubsection{}` LaTeX heading commands from confirmed H2/H3 structure
 - Academic prose following CEUS writing style from `references/journals/ceus.md`
 - `\cite{key}` inline citations (keys from `.paper-refs/` only; `[CITATION NEEDED]` for unsupported claims)
 - `[SOURCE: file:line]` annotations on all repo-derived claims (specific numbers, configs, model names)
 - `[RESULTS NEEDED]` / `[EXACT VALUE: metric]` for unknown quantitative data
 - Bilingual: `% --- Paragraph N ---` markers + `%` Chinese comment lines before each English paragraph (skip if opt-out detected)
4. Write to `{repo_path}/.paper-output/{section}.tex`
5. Display the generated section content to the user
6. AskUserQuestion for confirmation:

AskUserQuestion({ question: "セクション[N]：[Title]を生成しました。上記をご確認ください。", options: [ { label: "確認", description: "このセクションを承認し、次に進む" }, { label: "修正", description: "必要な変更を記述してください（セクション全体を再生成します）" }, { label: "スキップ", description: "このセクションをスキップして、次に進む" } ] })

- **Confirm:** proceed to next selected section
- **Modify:** user describes changes -> regenerate entire section -> re-display -> loop until confirmed
- **Skip:** move to next section without writing file

**After all selected sections confirmed:**
- Generate `references.bib` following the algorithm in `references/body-generation-rules.md`
- Display completion summary: number of sections generated, files written, references.bib entry count

## Output Contract

| Output | Format | Condition |
|--------|--------|-----------|
| `scan_summary` | Categorized summary table | Always -- Step 1 |
| `paper_outline` | Hierarchical H1/H2/H3 with descriptions and source annotations | After all steps confirmed |
| `literature_refs` | Per-section Markdown files in `{repo_path}/.paper-refs/` with reference cards | After Step 2.5 (skipped if MCP unavailable) |
| `body_text` | Per-H1 `.tex` files in `{repo_path}/.paper-output/` + `references.bib` | After Step 5 sections confirmed |

**Bilingual eligibility:** This Skill produces academic text (one-sentence heading descriptions).
Bilingual mode is ON by default; opt-out via keywords in `references/bilingual-output.md`.

After final H3 confirmation, offer to save the complete outline to a file using Write tool:
- Default filename: `paper_outline.md` in the repo root
- Include all heading levels with descriptions and source annotations
- Bilingual descriptions included if bilingual mode is ON

## Edge Cases

| Situation | Handling |
|-----------|----------|
| Empty repository (no recognized files) | Refuse: "No scannable files found in [path]. Please verify the repository path." |
| No README.md found | Warn in scan summary; proceed with available files; Introduction H2 will have limited source annotations |
| No result files found | Warn in scan summary; Results H2/H3 use placeholder: "[RESULTS NEEDED: add result files to populate this section]" |
| Journal specified but template missing | Refuse: "Journal template for [X] not found. Available: CEUS." |
| Non-Python repo | Warn: "Scan patterns are calibrated for Python ML projects. Non-Python files may be miscategorized." Proceed with best-effort |
| Very large repo (>500 files in top 2 levels) | List only top 10 files per category in scan summary; note total count |
| All files in one category | Proceed -- outline may be unbalanced; user corrects at confirmation step |
| Semantic Scholar MCP unavailable | Skip Step 2.5; insert [CITATION NEEDED] markers in outline; proceed to Step 4 |
| Zero search results for an H2 | Display warning with ⚠ prefix; mark H2 as [CITATION NEEDED]; continue to next H2 |
| MCP call fails mid-batch | Mark that specific H2 as [CITATION NEEDED]; continue with remaining H2 subsections |
| Springer papers with empty abstracts | Call get-paper-abstract; if still empty, display "Abstract not available" in ref card; still include paper |
| .paper-refs/ directory missing | Continue generating; all citation positions use `[CITATION NEEDED]` placeholders; do not block |
| User selects zero sections in Step 5 | Skip body generation entirely; display "No sections selected. Body generation skipped." |
| Modification loop exceeds 3 iterations | Proceed with current version; warn "Multiple revision cycles detected. Consider manual editing for fine adjustments." |

## Fallbacks

| Scenario | Fallback |
|----------|----------|
| Structured Interaction unavailable | Ask repo path and journal as plain-text questions |
| `references/repo-patterns.md` missing | Refuse: "Required reference file references/repo-patterns.md not found. Cannot categorize repo files." |
| `references/bilingual-output.md` missing | Proceed with English-only output; warn user |
| Journal template missing | Refuse with message from Edge Cases |
| Write tool unavailable | Present final outline in conversation; user saves manually |
| Semantic Scholar MCP unavailable | Skip Step 2.5 entirely; add [CITATION NEEDED] after each H2 description; warn user; proceed to H3 generation |
| `references/body-generation-rules.md` missing | Refuse: "Required reference file references/body-generation-rules.md not found. Cannot generate body text." |

## Examples

**Minimal invocation:** User provides repo path `~/projects/uhi-prediction/` and selects CEUS as target journal.

**Step 1 output (scan summary):**

カテゴリ	見つかったファイル数	主な項目
ドキュメント	2	README.md, docs/data-sources.md
設定	3	config.yaml, params.json, .env.example
結果	4	results/metrics.csv, results/ablation/
コード	8	src/model.py, src/train.py, src/eval.py
図	3	figures/heatmap.png, figures/scatter.svg
依存関係	1	requirements.txt

6 カテゴリから21個のファイルをスキャンしました。H1 アウトラインの生成に進みます…

**Step 2 output (H1 with CEUS template):**

1. はじめに

都市ヒートアイランド予測の課題と本研究の貢献を示します。
> **[Chinese]** 阐述城市热岛预测问题及本研究贡献。

2. 研究対象地域とデータ

UHI 分析の地理的範囲とデータソースを説明します。
> **[Chinese]** 描述研究区域范围及城市热岛分析的数据来源。

3. 方法

勾配ブースティング予測フレームワークと特徴量エンジニアリングを説明します。
> **[Chinese]** 介绍梯度提升预测框架与特征工程方法。

4. 結果

予測精度と空間パターン分析の結果を報告します。
> **[Chinese]** 报告预测精度与空间格局分析结果。

5. 考察

都市計画と既存のUHI研究を踏まえて知見を解釈します。
> **[Chinese]** 在城市规划和既有热岛研究背景下解读发现。

6. 結論

貢献をまとめ、限界を明らかにします。
> **[Chinese]** 总结贡献并指出局限性。

H1 セクションを6つ生成しました。H2 に進む前に、確認、修正、または追加してください。

User confirms. Steps 3-4 follow the same pattern with increasing detail and source annotations.

---

*Skill: repo-to-paper-skill*
*Conventions: references/skill-conventions.md*