aipoch/literature-close-read

Literature Close Reading

When to Use

• When you have a full paper converted from PDF to Markdown and need a structured, in-depth interpretation rather than a brief abstract-style summary.
• When you must extract reproducible experimental details (datasets, settings, controls, metrics, statistics) for replication or reimplementation.
• When you need to map the paper's logical chain (motivation → problem → method → experiments → conclusions) and identify missing links or ambiguities.
• When you want a systematic list of limitations, threats to validity, and follow-up research questions grounded strictly in the text.
• When figures/tables are referenced via Markdown images and you need them incorporated into the interpretation without guessing beyond what is shown.

Key Features

• Reads the entire Markdown paper text, prioritizing Methods and Results for technical fidelity.
• Produces a structured close-reading report in Markdown (UTF-8), following a predefined template.
• Extracts and organizes:
  • research background and problem statement
  • methodological details and experimental design
  • key results and statistical evidence (as explicitly stated)
  • limitations and threats to validity
  • reproducible points and follow-up questions
• Supports Markdown inputs that include pagination headers like ## Page XX and image references such as ![page-01](...).
• Enforces a strict constraint: summarize only what is explicitly present in the text/images; do not infer or speculate.
• Uses external guidance and templates:
  • Requirements/checklist: references/guide.md
  • Output template: assets/deep_reading_template.md

Dependencies

• pdf-extract (version: not specified) — used only when the source is PDF and must be converted to Markdown first.

Example Usage

# 1) (Optional) Convert PDF to Markdown if you only have a PDF
# Note: exact command/options depend on your local pdf-extract installation.
pdf-extract paper.pdf > paper.md

# 2) Run the close-reading process (manual or via your orchestration tool):
# Input: paper.md (full text converted from PDF, may include `## Page XX` and images)
# Guidance: references/guide.md
# Template: assets/deep_reading_template.md

# 3) Save the final report as UTF-8 Markdown under outputs/
mkdir -p outputs
# Example output file name:
# outputs/paper_close_reading.md

Minimal expected I/O contract:

• Input: a single .md file containing the full paper text (PDF-to-Markdown), optionally with:
  • page headers like ## Page 01
  • image references like ![page-01](...)
• Output: one UTF-8 encoded .md report saved to outputs/, formatted according to assets/deep_reading_template.md.
• Language: default output is Chinese; if the user specifies a language, output in that language.

Implementation Details

• Input reading rules

  • Treat the Markdown as the authoritative source of truth.
  • Pagination markers (e.g., ## Page XX) may be used for navigation and citation, but should not alter meaning.
  • Image references may be used to interpret figures/tables only to the extent that the content is explicitly visible/legible.

• Extraction and summarization rules

  • Focus on Methods and Results first; then connect to background, problem statement, and conclusions.
  • Capture experimental details precisely: datasets, splits, baselines, ablations, hyperparameters, training/inference settings, evaluation metrics, and statistical tests—only if stated.
  • If a required field in the template cannot be filled from the text, write "Not specified".

• Quality constraints

  • No speculation: do not add assumptions, unstated motivations, or inferred mechanisms.
  • Maintain traceability: ensure each claim in the report can be traced back to explicit paper content (text or figure/table).
  • Output must be valid Markdown and saved in UTF-8 to avoid encoding issues.

• Files used

  • Requirements and checklist: references/guide.md
  • Output template: assets/deep_reading_template.md
  • Output directory: outputs/ (create if missing)

When Not to Use

• Do not use this skill when the required source data, identifiers, files, or credentials are missing.
• Do not use this skill when the user asks for fabricated results, unsupported claims, or out-of-scope conclusions.
• Do not use this skill when a simpler direct answer is more appropriate than the documented workflow.

Required Inputs

• A clearly specified task goal aligned with the documented scope.
• All required files, identifiers, parameters, or environment variables before execution.
• Any domain constraints, formatting requirements, and expected output destination if applicable.

Recommended Workflow

1. Validate the request against the skill boundary and confirm all required inputs are present.
2. Select the documented execution path and prefer the simplest supported command or procedure.
3. Produce the expected output using the documented file format, schema, or narrative structure.
4. Run a final validation pass for completeness, consistency, and safety before returning the result.

Output Contract

• Return a structured deliverable that is directly usable without reformatting.
• If a file is produced, prefer a deterministic output name such as literature_close_read_result.md unless the skill documentation defines a better convention.
• Include a short validation summary describing what was checked, what assumptions were made, and any remaining limitations.

Validation and Safety Rules

• Validate required inputs before execution and stop early when mandatory fields or files are missing.
• Do not fabricate measurements, references, findings, or conclusions that are not supported by the provided source material.
• Emit a clear warning when credentials, privacy constraints, safety boundaries, or unsupported requests affect the result.
• Keep the output safe, reproducible, and within the documented scope at all times.

Failure Handling

• If validation fails, explain the exact missing field, file, or parameter and show the minimum fix required.
• If an external dependency or script fails, surface the command path, likely cause, and the next recovery step.
• If partial output is returned, label it clearly and identify which checks could not be completed.

Quick Validation

Run this minimal verification path before full execution when possible:

No local script validation step is required for this skill.

Expected output format:

Result file: literature_close_read_result.md
Validation summary: PASS/FAIL with brief notes
Assumptions: explicit list if any