pdf2paper

name	pdf2paper
description	Converts an existing PDF draft into paper.md section by section by extracting text, mapping claims into the existing paper framework, and polishing wording without inventing new content.

PDF to Paper Skill

This skill converts an existing PDF draft into paper.md incrementally, one section at a time. It is designed for cases where the PDF already contains most of the technical narrative, and the task is structured migration plus light polishing.

When to Use This Skill

• User asks to import an existing PDF draft into paper.md
• User wants section-by-section conversion instead of one-shot rewrite
• User wants to preserve claims from PDF while adapting to CoPaper structure

Typical triggers:

• convert pdf to paper.md
• 从PDF初稿生成paper.md
• 将位于 <path> 的pdf转变为paper.md
• 把 <path>.pdf 逐section转换到 paper.md
• use $pdf2paper to convert <path>.pdf to paper.md
• 调用 pdf2paper，将 <path>.pdf 转为 <target>/paper.md

Paper Structure Reference

The paper follows CoPaper structure. Key rules for this skill:

• Level 1-5 (# to #####): Structural headings only — do NOT modify these in paper.md.
• Level 6 (######): Content paragraphs. Title = topic sentence (≤50 chars). Body = supporting text (≤500 chars).
• Metadata: HTML comments <!-- description: ... --> guide what each section should contain.

Input Files

File	Required	When to Read	Purpose
paper.md	Conditional	Step 1 and Step 8	Target framework; inspect through copaper_paper_structure_status if present
*.pdf	Required	Step 2	Source draft content; extract and validate through copaper_pdf_extract
.agents/state.json	Optional	Step 9	Updated only through copaper_workflow_set_phase
fig/	Optional	Step 5	Keep references to figure files mentioned in PDF

Preferred source example:

• target/example_project/draft.pdf

Core Principle

Preserve source meaning. Do not invent research claims.

This skill is a converter + editor, not a paper generator. It should:

• extract what the PDF already says
• map content to existing paper.md sections
• polish wording for clarity and fit

It should not:

• create new results, datasets, or citations not present in the PDF
• silently rewrite the whole document at once

Path safety rule:

• If the user does not provide a PDF path in the request, the agent MUST ask for a path and wait.
• The agent MUST NOT scan directories, glob files, or guess candidate PDF files automatically.
• Accepted path forms are absolute or relative paths explicitly provided by the user.

Supported Formats

• Text-based pdf: supported through copaper_pdf_extract
• Scanned/image-only pdf: not OCRed by this skill; if copaper_pdf_extract reports low confidence or little/no text, stop and ask the user for a text-based PDF or extracted text

Extraction Strategy

Call copaper_pdf_extract for source extraction when the OpenCode plugin tool is available.

This tool is read-only and requires an explicit .pdf path. It validates path safety, file existence, supported extension, file size, and readable text operators. It does not scan directories, guess source files, write paper.md, update .agents/state.json, append .agents/events.jsonl, or advance workflow phases.

Use the tool output to capture:

• page range
• extracted text
• page count
• extraction confidence
• source hash for traceability

If the tool reports low confidence or no text operators, disclose that limitation to the user and ask for a better source. Do not replace copaper_pdf_extract with prompt-only extraction instructions, shell existence checks, shell pdftotext, OCR, or directory scans when the plugin tool is available.

Mapping Rules (PDF -> paper.md)

Map by semantics, not by exact heading names.

Typical cues:

• Motivation/problem framing -> introduction/problem sections
• Prior approaches and gaps -> related-work sections
• Design and mechanisms -> method/design sections
• Setup, metrics, baselines, results -> experiment sections
• Threats/limitations/discussion -> discussion sections
• Final takeaways -> conclusion sections

If one PDF paragraph supports multiple destinations, split conservatively and keep each inserted paragraph scoped to one ##### target.

Strict Workflow

Step 1: Validate inputs

1. Check whether the user explicitly provided a source .pdf path.
2. If source path is not specified, ask exactly one concise question:
   • 请提供要转换的 PDF 文件路径（例如：target/example_project/draft.pdf）。
3. Do not scan the filesystem for PDF candidates when the path is missing.
4. Wait for user-provided absolute or relative path.
5. Do not run a separate shell/file existence check for the .pdf; copaper_pdf_extract performs this validation in Step 2.
6. Check whether paper.md exists through copaper_paper_structure_status in Step 3:
   • if yes, continue normal mapping and in-place update flow
   • if no, continue conversion in draft mode and initialize project at Step 8 before final write

Step 2: Extract PDF content

1. Call copaper_pdf_extract with the explicit user-provided .pdf path.
2. If the tool returns an error, stop and report the error; do not retry by scanning directories, running pdftotext, or doing OCR.
3. Use the returned text, page count, confidence, warnings, and source hash.
4. Build an intermediate traceable note with available page information.
5. Mark extraction confidence:
   • high: direct text extraction
   • medium: mixed quality
   • low: too little reliable text; ask the user for a text-based PDF or extracted text before continuing

Step 3: Scan target framework

1. Call copaper_paper_structure_status to inspect paper.md structure and Level 5 writing targets.
2. If the tool reports missing paper.md, keep accepted conversion content in draft mode and initialize project at Step 8 before final write.
3. If the tool reports an unsafe path or unreadable file, stop and report the tool error.
4. Use the embedded Paper Structure Reference above for structure constraints.
5. Build a target section map for insertion planning from the tool's headings, level5Targets, and violations.

Step 4: Build section evidence map

For each target ##### section:

1. attach relevant PDF snippets with page references
2. classify as:
   • grounded: enough evidence to draft
   • partial: weak or incomplete evidence
   • missing: no evidence

Step 5: Draft one section at a time (polish only)

For each selected section:

1. Rewrite extracted points into compliant Level 6 paragraphs.
2. Keep claims and numeric values unchanged.
3. Preserve citation intent from PDF text; do not fabricate references.
4. Keep unresolved content as TODO placeholders when evidence is missing.

Step 6: User review gate (required)

Before writing each section, present the candidate content and ask:

• Accept
• Modify
• Skip this section

Do not apply unreviewed section edits.

Step 7: Apply accepted edits safely

1. Edit only under existing ##### headings.
2. Do not alter Level 1-5 structure.
3. Insert or replace only the accepted Level 6 content for that section.
4. If paper.md is missing, hold accepted converted content in temporary draft and apply it after Step 8 initialization.

Step 8: Project bootstrap check (start-stage friendly)

After conversion content is accepted, ask for the current project directory:

• 请确认当前项目路径（project dir）。

Then validate:

1. <project-dir>/.agents/skills/ exists and is non-empty
2. <project-dir>/paper.md exists

If paper.md is missing:

1. Ask for:
   • project name
   • project domain
2. Restate the project directory, project name, and project domain.
3. Wait for explicit user confirmation.
4. Call copaper_init_apply with name and domain; the tool initializes OpenCode-managed CoPaper core files and refuses conflicts.
5. Then apply the accepted converted content into initialized paper.md.

Do not manually create storyline.md, paper.md, writingrules.md, AGENTS.md, .agents/state.json, or .agents/events.jsonl when copaper_init_apply is available.

If only .agents/skills/ is missing or incomplete, report that the current OpenCode plugin initialization writes core project files only and does not install the skill library. Do not claim copaper_init_apply can repair missing skills. Continue only if paper.md exists and the current skill instructions are available in the active agent context.

Step 9: Update workflow status

After accepted edits:

• If at least one writing section is filled, set writing phase to in_progress.
• If all intended conversion sections are materially filled, set writing phase to complete.

Use copaper_workflow_set_phase for this update. Before calling it, restate the target phase and status and wait for explicit user confirmation. The tool call writes .agents/state.json and appends the workflow event to .agents/events.jsonl.

Do not run copaper set-phase and do not manually edit .agents/state.json when the OpenCode plugin tool is available.

Output Requirements

• Primary output: updated paper.md
• Secondary output: concise conversion summary including:
  • source PDF path
  • extraction confidence level
  • sections updated
  • sections skipped/missing evidence
  • TODO placeholders intentionally kept

Quality Bar

Each inserted paragraph should be:

• faithful to PDF content
• structurally compliant with CoPaper rules
• concise and readable
• traceable to source pages

Must NOT Do

• NEVER invent claims not present in PDF
• NEVER invent experiment numbers, datasets, or baselines
• NEVER modify Level 1-5 structure in paper.md
• NEVER rewrite the full paper in one blind pass
• NEVER pretend OCR was performed by this skill; disclose low-confidence or missing text from copaper_pdf_extract
• NEVER treat this as autonomous writing without user confirmation

Recommended Default Invocation

For this repository, default to:

• source: target/example_project/draft.pdf
• target: target/example_project/paper.md if present, otherwise project-root paper.md

End Condition

Stop when one of the following is true:

• user accepts converted sections for this run
• no additional sections can be grounded from PDF evidence
• user pauses or requests manual continuation

At stop time, report:

• completed sections
• unresolved sections (missing PDF evidence)
• whether writing phase status was updated

Next-step prompt rule:

• At the end of each run, explicitly offer both options:
  1. Run find related work.
  2. Go directly to the next step: socratic discussion.