ppw%3arepo-to-paper（ppw%3arepo 到纸上）

Purpose

This Skill scans a Python ML experiment repository and generates a hierarchical paper outline (H1/H2/H3) with user approval checkpoints at each heading level. It serves researchers who have completed experiments and need to structure findings into an academic paper. The scan categorizes repo files using patterns from references/repo-patterns.md, then progressively generates headings from coarse (sections) to fine (sub-subsections), with the user confirming or modifying each level before proceeding. After H2 confirmation, the Skill automatically collects academic references via Semantic Scholar MCP and saves them as per-section ref files for downstream body generation.

Trigger

Activates when the user asks to:

• Generate a paper structure, outline, or skeleton from a repository or codebase
• Scan a project and create paper sections from experiment code or results
• 从实验仓库/代码仓库生成论文大纲或论文结构

Example invocations:

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

Modes

Default mode: guided. The layered confirmation design is central to this Skill.

References

Required (always loaded)

Leaf Hints

None. All reference files are in required because Step 5 body generation always needs CEUS formatting.

Loading Rules

• Load repo-patterns.md and bilingual-output.md at Step 1 start.
• Load body-generation-rules.md and journals/ceus.md at Step 5 start.
• If journal template file is missing, refuse: "Journal template for [X] not found. Available: CEUS."

Ask Strategy

Before starting, ask about:

1. Repo path (required): "Which repository should I scan?" -- use Structured Interaction if available
2. Target journal (optional): "Which journal is this paper targeting?" -- options: CEUS, Other, None/General. If CEUS, load template at Step 2. If Other, ask for journal name. If None, use IMRaD default

Bilingual mode: Inferred from trigger text. Check for opt-out keywords per references/bilingual-output.md (exact phrases: english only, no bilingual, only english, 不要中文). Do not ask explicitly.

Rules:

• Never ask more than 2 explicit questions (repo path + journal)
• In direct mode, skip -- but direct mode is not supported for this Skill

Workflow

Step 0: Workflow Memory Check

• Read .planning/workflow-memory.json. If file missing or empty, skip to Step 1.
• Check if the last 1-2 log entries form a recognized pattern with ppw:repo-to-paper that has appeared >= threshold times in the log. See skill-conventions.md > Workflow Memory > Pattern Detection for the full algorithm.
• If a pattern is found, present recommendation via AskUserQuestion:

- Question: "检测到常用流程：[pattern]（已出现 N 次）。是否直接以 direct 模式运行 ppw:repo-to-paper？" - Options: "Yes, proceed" / "No, continue normally"

• If user accepts: set mode to direct, skip Ask Strategy questions.
• If user declines or AskUserQuestion unavailable: continue in normal mode.
• Note: This Skill does not support full direct mode. If user accepts the recommendation, skip the Ask Strategy questions (repo path, journal) using inferred context, but retain all guided Step checkpoints (Steps 2-5 confirmations). The output contract is not altered.

Step 1: Scan Repository

Prepare:

• Load references/repo-patterns.md and references/bilingual-output.md
• Read the repository directory structure (top 2 levels: root + first-level subdirectories)
• Categorize each file using the File Identification Patterns table from repo-patterns.md
• Apply ambiguity rules for files matching multiple categories (lowest priority number wins)
• Skip hidden files, test files, and binary data files per the Skip Rules in repo-patterns.md

Present:

• Display a categorized summary table: Category Files Found Key Items documentation 3 README.md, docs/overview.md results 5 results/metrics.csv, scores.json
• Mark missing categories: "No [category] files found"
• Summary line: "Scanned N files in M categories. Proceeding to H1 outline generation..."
• If user wants to review or correct, they can interrupt; otherwise auto-proceed to Step 2
• Record workflow: Append {"skill": "ppw:repo-to-paper", "ts": "<ISO timestamp>"} to .planning/workflow-memory.json. Create file as [] if missing. Drop oldest entry if log length >= 50.

Step 2: Generate H1 Outline

Prepare:

• If journal specified (e.g., CEUS), load references/journals/[journal].md and use its Section Guidance headings as H1 structure. CEUS sections: Abstract, Introduction, Study Area / Data / Methods, Results, Discussion, Conclusion
• If no journal specified, use IMRaD default: Introduction, Methods, Results and Discussion, Conclusion
• Adjust base sections based on scan summary (e.g., add "Study Area" if spatial data detected)

Present:

• Display H1 headings with one-sentence descriptions: # 1. Introduction Establish research context, literature gap, and contribution statement. # 2. Methods Describe the analytical approach, data sources, and model architecture.
• Bilingual: if bilingual mode is ON, add Chinese translation of each description using Markdown blockquote format: > **[Chinese]**... per references/bilingual-output.md
• Summary line: "Generated N H1 sections. Please confirm, modify, or add before proceeding to H2."
• Wait for user confirmation ("ok") or modification instructions

On modification: Revise H1 headings per user feedback and re-display. Loop until confirmed.

Section adjustment examples:

• If scan found spatial data files (shapefiles, GeoJSON) -> consider adding "Study Area" H1 section
• If scan found no result files -> mark Results section with warning placeholder
• If scan found multiple distinct model implementations -> consider splitting Methods into sub-approaches

Step 3: Generate H2 Outline

Prepare:

• For each confirmed H1 section, read relevant repo files to generate H2 sub-headings
• Use the Category to Paper Section Mapping from repo-patterns.md to identify which files inform each H1 section
• Read actual file contents (README for Introduction, config files for Methods, result files for Results) -- H2 generation requires content reading, not just directory structure
• Generate 2-4 H2 sub-headings per H1 section, each with a one-sentence description

Present:

• Display full H1 + H2 hierarchy with source annotations on each 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.
• Source annotations: list the 1-3 most directly relevant files (highest-priority per repo-patterns.md)
• Bilingual: if ON, add Chinese descriptions in > **[Chinese]**... blockquote format
• Same confirmation loop as Step 2: "Generated N H2 subsections across M H1 sections. Please confirm, modify, or add before proceeding to H3."

Step 2.5: Literature Collection

Pre-flight:

• Call mcp__semantic-scholar__papers-search-basic with {"query": "test", "limit": 1}
• If call succeeds: proceed to literature collection below
• If call fails or tool unavailable: skip Step 2.5 entirely

- Insert [CITATION NEEDED] after each H2 subsection description in the outline - Display: "Semantic Scholar MCP not available. Skipping literature collection. [CITATION NEEDED] markers added." - Proceed directly to Step 4 (H3 generation)

Collect references:

FOR each H1 section: FOR each H2 subsection under this H1: 1. Derive search query: extract 2-5 key technical terms from the H2 title and description, contextualized by the H1 section title. Use English terms only (ignore Chinese translations in bilingual mode). Strip filler words (and, of, the, for). Example: H1="Methods", H2="Gradient Boosting Prediction Framework", description="Feature engineering using street-level semantic segmentation data" -> query: "gradient boosting prediction street-level semantic segmentation" 2. Call mcp__semantic-scholar__papers-search-basic with {"query": derived_query, "limit": 10} 3. For each result where the abstract field is empty: call mcp__semantic-scholar__get-paper-abstract with the paper's paperId. If abstract is still empty after fetch, mark as "Abstract not available" 4. Filter results by relevance: assess how many distinct claims/arguments the H2 subsection needs to make, then keep 5-10 papers that best support those claims. Discard papers that are only tangentially related based on title and abstract content 5. Display progress line: ✓ 1.1 Research Background: 8 refs found (or ⚠ 1.1 Research Background: 0 refs found for zero results) 6. If a search call fails mid-batch: mark that H2 as [CITATION NEEDED], display warning, continue to next H2 END FOR END FOR

Write ref files:

Create {repo_path}/.paper-refs/ directory. Write one Markdown file per H1 section, named by the section topic in lowercase (e.g., introduction.md, methods.md, results.md).

Each file uses this structure:

# [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"]

@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:

| Section | Subsection | Refs | Top Reference |
| --- | --- | --- | --- |
| 1. Introduction | 1.1 Research Background | 8 | Smith et al. (2023) - 142 citations |
| ... | ... | ... | ... |

Total: [N] references collected. Confirm to proceed to H3 outline generation.

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 Research Background and Motivation

### 1.1.1 Urban Heat Island Measurement Challenges <- from: README.md:L15-30

Current approaches to UHI measurement rely on satellite imagery with limited resolution.

• 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: "Which sections should I generate body text for?", 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)

1. Write to {repo_path}/.paper-output/{section}.tex
2. Display the generated section content to the user
3. AskUserQuestion for confirmation:

AskUserQuestion({question: "Section [N]: [Title] generated. Please review above.", options: [{label: "Confirm", description: "Accept this section and proceed to next"}, {label: "Modify", description: "Describe changes needed (will regenerate entire section)"}, {label: "Skip", description: "Skip this section, move to next"}]})

• 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

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

Fallbacks

Examples

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

Step 1 output (scan summary):

| Category | Files Found | Key Items |
| --- | --- | --- |
| documentation | 2 | README.md, docs/data-sources.md |
| config | 3 | config.yaml, params.json,.env.example |
| results | 4 | results/metrics.csv, results/ablation/ |
| code | 8 | src/model.py, src/train.py, src/eval.py |
| figures | 3 | figures/heatmap.png, figures/scatter.svg |
| dependencies | 1 | requirements.txt |

Scanned 21 files in 6 categories. Proceeding to H1 outline generation...

Step 2 output (H1 with CEUS template):

# 1. Introduction

Establish the urban heat island prediction problem and contribution.

[Chinese] 阐述城市热岛预测问题及本研究贡献。

# 2. Study Area and Data

Describe the geographic scope and data sources for UHI analysis.

[Chinese] 描述研究区域范围及城市热岛分析的数据来源。

# 3. Methods

Present the gradient boosting prediction framework and feature engineering.

[Chinese] 介绍梯度提升预测框架与特征工程方法。

# 4. Results

Report prediction accuracy and spatial pattern analysis.

[Chinese] 报告预测精度与空间格局分析结果。

# 5. Discussion

Interpret findings in the context of urban planning and prior UHI studies.

[Chinese] 在城市规划和既有热岛研究背景下解读发现。

# 6. Conclusion

Summarize contributions and identify limitations.

[Chinese] 总结贡献并指出局限性。

Generated 6 H1 sections. Please confirm, modify, or add before proceeding to 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*