lylll9436/paper-polish-workflow-skill/ppw-repo-to-paper

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:

• 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"

1. Call mcp__semantic-scholar__papers-search-basic with {"query": derived_query, "limit": 10}
2. 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"

1. 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

1. Display progress line: ✓ 1.1 Research Background: 8 refs found (or ⚠ 1.1 Research Background: 0 refs found for zero results)
2. 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