Deeppapernote

DeepPaperNote

Use this skill when the user wants one outcome:

• read one paper carefully
• generate a high-quality Markdown note
• save the note to the workspace or Obsidian target selected by resolved configuration

Chinese trigger examples:

• 给这篇论文生成深度笔记
• 写一篇高质量论文精读笔记
• 把这篇文章整理成 obsidian 笔记
• 读这篇论文并生成 md 笔记

English trigger examples:

• Generate a deep-reading note for this paper
• Turn this paper into an Obsidian research note

User Configuration

Before a normal paper run, read references/user-configuration.md for configuration admission, migration, repair, Run Overrides, and Preference Changes.

Resolve Run Overrides from the explicit request, CLI, and current process environment first. When they form a complete valid configuration for the selected Save Mode, Configuration Readiness is complete without reading User Configuration. Only inspect User Configuration when those Run Overrides need fallback values.

Language Integrity Contract

After Configuration Readiness, resolve one output_language (zh-CN or en) for the run. source_manifest.language_hint describes source text only and never selects the note profile.

Bind that exact value through Save Target Admission → Figure Plan → Figure/Table Decisions → Synthesis Bundle → Note Plan → Grounding Lint → Final Note Lint → Final Quality Review → Final Readability Review → Formal Save:

• Every JSON artifact in the chain carries a top-level output_language; the Synthesis Bundle also carries the same value at writing_contract.language.
• Before producing its output, every adjacent consumer requires each input language and compares it with the resolved value. Missing, unsupported, or mismatched values stop the run; no stage infers or defaults an artifact language.
• Final Quality Review and Final Readability Review each receive the resolved value and check the note against only that profile.
• Final Note Lint records note_sha256. Any review edit invalidates the prior lint, so rerun Final Note Lint under the same language. Formal Save requires the lint language and note_sha256 to match the final note, and validates Figure/Table Decisions language before any save side effect.

This contract is complete only when every named stage is bound to the resolved value and Formal Save validates the final bytes. Read references/output-language.md for profile content while drafting or debugging either language.

This skill is intentionally narrow:

• it is one canonical Skill and one pipeline with two output profiles
• it handles one paper at a time
• it does not update daily reading lists
• it does not treat a shallow abstract rewrite as a successful output
• it does not split the public entrypoint into separate setup, troubleshooting, or start commands

Core Standard

The finished note must be more than a summary. It should reconstruct the paper's argument:

• what problem it solves
• how the task is defined
• what data or materials it uses
• how the method or analysis actually works
• what results matter most
• what the paper does not prove
• why the paper is worth keeping

Default writer persona:

• a top-tier researcher or algorithm engineer
• writing a replication-oriented lab note
• not writing a popular-science explanation
• assuming the reader can follow Python, PyTorch, training loops, and evaluation logic

The note must adapt to the paper type. Use the same base structure, but shift emphasis for AI methods, benchmarks, clinical studies, and humanities or social-science papers.

Workflow

Follow this order:

1. complete Configuration Readiness: resolve Run Overrides first, and inspect User Configuration only when they are incomplete; advance only after the resolved run configuration is complete and valid
2. resolve the paper identity
3. collect metadata
4. acquire the best available PDF
5. extract canonical raw source text: *_raw_sections.jsonl, *_source_manifest.json, and optional derived *_full_text.md
6. perform Save Target Admission before drafting or domain routing:
   • for Obsidian mode, run scripts/write_obsidian_note.py --preflight with the resolved title, exact output_language, Vault, and *_source_manifest.json; this program result is authoritative, so do not replace it with prompt-only duplicate checking
   • when admission returns reuse_source_directory or reuse_empty_same_name_directory, use that directory and skip domain selection
   • when it returns same_language_note_exists, stop before drafting and ask whether to overwrite the reported note. If the user approves, rerun preflight with --overwrite-existing-note --expected-existing-note-sha256 <reported_sha256> and carry that exact confirmation into Formal Save; if the user declines, stop without writing
   • for any other blocked conflict, report the returned ambiguity and stop without creating a second directory
   • workspace mode does not scan an Obsidian Vault and continues through its normal domain routing
7. extract structural indexes and PDF assets
8. plan figure placement
9. build the full figure/table decision table
10. build the manifest synthesis bundle
11. have the model read the bundle plus raw sections and create a short JSON note_plan that satisfies the generated bundle contract, including its exact output_language
12. draft from the plan only after the grounding gate passes
13. have the model write the note
14. lint the final note against the same note_plan — this stage completes only when the lint artifact exists and every reported passes_* gate is true; otherwise revise and rerun lint. If the lint output contains passes_style_gate: false, apply the Style Gate Enforcement rule before advancing to step 15, 16, or 17
15. perform final_quality_review after lint passes
16. perform final_readability_review after the quality review passes
17. perform Formal Save to the admitted target with scripts/write_obsidian_note.py, the same Source Manifest, and any user-approved overwrite hash; the script repeats admission before the first save side effect

This is the required workflow for a normal single-paper note request, not a loose suggestion. Unless this skill explicitly marks a stage as optional, required stages must not be silently skipped, reordered into a shortcut, or treated as complete just because a partial artifact already exists.

Global no-short-circuit rule:

• do not stop after only the early stages and present the workflow as finished
• do not treat slowness, inconvenience, or temporary uncertainty as permission to bypass a required stage
• do not replace the declared workflow with an improvised shortcut
• if a required stage fails, only do one of three things:
  • retry that stage
  • enter a fallback that is explicitly allowed by this skill
  • stop and report which stage is blocked and which downstream required stages remain incomplete
• do not describe the whole task as complete while required downstream stages are still pending

Completion-language rule:

• say 笔记已完成 only when the required workflow is actually complete
• say 已生成草稿 when drafting is done but lint, final readability review, or save is still pending
• say 已通过校验 only when lint has actually been run and passed
• say 已保存到 Obsidian only when the write step has actually succeeded
• do not treat lint 已通过 as equivalent to 整篇笔记已经润色完成
• if final readability review is still pending, explicitly say the draft passed script lint but has not finished final language review
• if the workflow stopped early, name the current stage and the still-missing required stages instead of using completion language
• lint is a floor, not the writing objective

Final user report:

• Keep the completion wording defined above. After a successful Formal Save, report in the user's conversation language.
• Lead with the final note link or path, save mode, and actual saved domain. Read the domain from the final note path under the configured papers root in Obsidian mode or output root in workspace mode; when Save Target Admission reused an existing directory, report that directory's existing domain.
• Then report, in order:
  1. paper title and strongest verified identifier
  2. Grounding Lint, Final Note Lint, Final Quality Review, and Final Readability Review results, plus the warning count
  3. materialized and retained-placeholder figure/table counts
  4. whether the saved note SHA-256 matches the Final Note Lint note_sha256
• Add overwrite actions, preference changes, or user-relevant warnings only when they occurred.
• Keep the report to these fields and derive every claim from current-run artifacts.

Core Execution Contract

SKILL.md plus the generated synthesis_bundle.json must be enough to complete a normal note-generation run. Files under references/ are optional stage-specific deep dives, not a default reading checklist.

Non-negotiable rules:

• evidence-first: draft from the synthesis bundle, source_manifest, raw sections, coverage metadata, explicit note_plan, and inspected paper evidence; never finish from title/abstract/headings alone
• raw-source authority: for ordinary PDFs, *_raw_sections.jsonl and *_source_manifest.json are the canonical reading material; old top-N evidence buckets, truncated section_texts, and candidate_chunks are not model-facing writing inputs
• fail-closed: if a usable PDF or sufficient evidence cannot be obtained after supported acquisition paths, stop and ask for better source material rather than producing a finished degraded note
• model-first: scripts structure evidence, but the model must decide emphasis, contribution, mechanism, limitations, and final prose in the configured language
• required structure: include the localized canonical sections in the order declared by writing_contract.must_include_sections
• abstract fidelity: preserve the original abstract's meaning without adding later evidence or model judgments; translate it in zh-CN mode and render it faithfully in English in en mode
• mechanism depth: method, framework, and system papers should include the localized mechanism-flow subsection under the localized method section, normally as a 3 to 4 step numbered flow with input, operation, and output destination
• placeholder-first figures: plan major figure/table placeholders first; replace one only when identity match and visual usability are both strong; otherwise keep the placeholder

Reference usage policy:

• do not load every reference file by default
• consult references/evidence-first.md, references/deep-analysis.md, or references/final-writing.md only when the paper is complex or the draft is too shallow
• consult references/figure-placement.md only for ambiguous figure/table placement or image replacement decisions
• consult references/obsidian-format.md only for Markdown, vault, frontmatter, or reference-link formatting details
• consult references/note-quality.md or references/paper-types.md only for final review or domain adaptation
• consult references/metadata-sources.md only when metadata is incomplete, and references/architecture.md only for repository maintenance decisions

Tool and Source Priority

Prefer the strongest available source in this order:

1. local PDF path given by the user
2. local Zotero item and local Zotero attachment if available
3. DOI and publisher metadata
4. arXiv or open-access PDF sources
5. Semantic Scholar or OpenAlex for metadata backfill

Before web resolution, use the bundled scripts/resolve_paper.py Zotero Local API path to check the desktop library. Its default --zotero-mode auto prefers a unique local match and falls back to the existing providers when Zotero is unavailable or has no match. An explicit Zotero key has no safe web fallback and must be verified locally. Use off to make no Local API request, or required when the reference must resolve through Zotero. A trusted JSON artifact or explicit local PDF remains authoritative and bypasses this lookup. A compatible session-scoped Zotero/MCP integration may still provide a trusted input artifact when available, but it is not required for the built-in path.

Local-library-first rule:

• search the local Zotero library first using the paper title, DOI, arXiv id, or exact Zotero item key
• If Zotero finds the paper, treat that result as the canonical identity resolution step.
• Prefer the safe local attachment path returned by the built-in Local API. If another compatible integration exposes only an attachment key and filename, use scripts/locate_zotero_attachment.py to find the PDF under the user's Zotero storage.
• If a local attachment path is available, pass it forward as the preferred PDF source.
• If no local attachment is found, still use the library-resolved metadata to avoid title ambiguity, then fall back to network PDF acquisition only for the file itself.
• If multiple local items are equally plausible, fail closed and request a DOI, arXiv id, or exact Zotero key rather than selecting one arbitrarily.
• Do not let a weaker title-only internet match override a confident local-library hit.

Output Rules

Formal Save states:

• A normal note-generation request should complete in one pass: note text, figure placeholder decisions, image materialization when confident, and final save.
• Do not stop after a text-only draft just to ask whether the user wants figures inserted. Finish the figure replacement decision inside the same task unless the user explicitly asked for text only.
• The note must use real heading levels: #, ##, and ###.
• Every final note must start with an Obsidian YAML properties block above the # title heading. Include at least a tags field with a papers/<domain> value and useful aliases; include date, doi, or arxiv_id when known, and omit unavailable fields rather than inventing placeholders.
• The localized Core Information section must be a fixed metadata block only. Use only the fields and order declared by writing_contract.core_info_fields; omit unavailable fields and move commentary to a later analysis section.
• Include the localized Abstract section near the beginning when abstract metadata is available, before the one-sentence summary.
• The Abstract section should faithfully render the paper's original abstract in the configured language rather than replacing it with a model-written summary.
• Do not mix later judgments, contribution summaries, or hindsight explanations into the Abstract section.
• Include a dedicated localized Contributions section immediately after Abstract and before the one-sentence summary.
• Contributions should enumerate the paper's actual innovations and explain why each matters rather than offering empty praise.
• High-quality notes should usually contain multiple meaningful ### subheadings in the technical sections when the paper is non-trivial.
• Generate the complete figure/table decision table and satisfy the generated writing_contract.figure_table_contract before drafting or saving.
• After the synthesis bundle is built, complete the model-led Visual Review Gate and Figure/Table Decision Freeze before creating note_plan; no review_pending item may cross that boundary.
• Pass the grounding and final-note figure gates before advancing; revise any failed decision coverage, insertion, structure, or status check.
• An insert decision is complete only after Formal Save materializes the selected image into the paper-local images/ directory and the write succeeds.
• The note must pass the style gate for its configured language: zh-CN rejects mixed Chinese-English prose artifacts, while en rejects Chinese prose outside citation metadata.
• The style gate also rejects mechanical term-replacement artifacts such as KV缓存 of, 批量ing, In相关 Researcher, or Single 序列 generation; rewrite the sentence naturally instead of preserving a partially translated phrase.
• Style gate enforcement: when lint_note.py output contains passes_style_gate: false, fix the reported issues and re-run lint. Keep fixing and re-running until lint passes — multiple rounds are normal and expected. Do not decide that any failure is an acceptable exception — proper nouns, math formulas, and citation metadata are not automatic exemptions. Only escalate to the user if the same failures appear unchanged across multiple rounds with no reduction, indicating the model is unable to make further progress independently.
• If PDF or evidence quality is insufficient for a real deep note, fail closed: stop, report the blocked stage, and ask for the better PDF, OCR/source material, or other input needed to continue.

Model-first rule:

• scripts may gather and structure evidence
• scripts must not be the primary mechanism for understanding the paper
• final paper understanding and note writing belong to the model
• use the generated bundle contract to choose the paper type, section semantics, evidence-backed claims, boundaries, comparisons, and reusable follow-up questions; script suggestions remain hints rather than writing authority
• do not require or expose a long free-form <thinking> block
• for technical papers, prefer replication-grade explanation over high-level summary
• if formulas, objectives, or complexity expressions are central, include the key ones in the final note
• render math as $...$ or $$...$$, not as inline code or fenced code blocks
• before final save, explicitly self-review whether the note contains enough technical detail, key numbers, and any necessary formulas
• during final_quality_review, check the full note against seven questions: whether the central evidence chain is complete, whether key settings and numbers are present, whether mechanisms or protocols are mapped to the result pattern they explain, whether the paper is positioned against strong baselines or alternative routes, whether Discussion/Limitations conclusions are explained mechanistically, whether proven claims are separated from unproven claims, and whether the research, engineering, replication, or validity takeaways are specific enough to reuse
• central quantitative comparisons with three or more systems, settings, tasks, datasets, metrics, or ablation rows should normally be written as compact Markdown tables, followed by interpretation; do not leave the main result table as a loose bullet list when a table would be clearer
• short papers still need a complete deep note: use the saved space to explain protocol details, ablations, limitations, and deployment or replication implications rather than compressing the note into a terse summary
• after final_quality_review passes, reread the full note once more for readability; do not stop at formal compliance only
• in final_readability_review, rewrite language leftovers into natural prose in the configured language while preserving stable proper nouns
• do not use final_readability_review to invent new facts, empty filler text, or shallower but safer wording just to satisfy lint

The topic references above can improve difficult runs, but the normal execution path should not depend on reading all of them.

Scripts

Use these bundled scripts rather than rebuilding the workflow from scratch:

• scripts/check_environment.py
• scripts/user_configuration.py
• scripts/create_input_record.py
• scripts/locate_zotero_attachment.py
• scripts/resolve_paper.py
• scripts/run_pipeline.py
• scripts/collect_metadata.py
• scripts/fetch_pdf.py
• scripts/extract_source_text.py
• scripts/extract_evidence.py
• scripts/extract_pdf_assets.py
• scripts/plan_figures.py
• scripts/plan_figure_table_decisions.py
• scripts/build_synthesis_bundle.py
• scripts/lint_grounding.py
• scripts/lint_note.py
• scripts/materialize_figure_asset.py
• scripts/write_obsidian_note.py

Python interpreter rule:

• DeepPaperNote requires Python >=3.10.
• Before running repository scripts, check the interpreter version instead of assuming the current shell default is compatible.
• If the default python3 is below 3.10, automatically look for another available interpreter that satisfies the requirement, such as python3.12, python3.11, python3.10, /opt/anaconda3/bin/python3, /opt/homebrew/bin/python3, or /usr/local/bin/python3.
• Use the first compatible interpreter you find and continue with that interpreter for the repository scripts in the current task.
• If no compatible interpreter is available, stop and clearly tell the user which interpreter was found, which version it reported, and that DeepPaperNote requires Python >=3.10.

Troubleshooting rule:

• use scripts/check_environment.py only when a concrete dependency or integration question is blocking execution
• explain required dependencies, optional enhancements, and downgrade behavior directly rather than redirecting the skill into a separate troubleshooting workflow
• do not feature environment inspection as a public pseudo-command surface

Current status:

• the single-paper deterministic core pipeline is implemented as an MVP
• scripts/run_pipeline.py now defaults to building a model-facing synthesis bundle
• scripts/write_obsidian_note.py can write the final note into a target vault
• patch the scripts rather than replacing the workflow ad hoc

Limits

• If the paper identity is ambiguous, confirm before writing.
• If the PDF is unavailable after all supported acquisition paths have been tried, stop and report what input is needed; do not produce a degraded, provisional, or abstract-only note as the finished output. Supported acquisition paths include local PDF, Zotero attachment, metadata pdf_url, direct PDF URL, arXiv/open-access sources, publisher PDF if accessible, DOI enrichment, and any other current fetch path implemented by the workflow.
• Placeholder-first figure planning is required; image extraction is optional and must never reduce textual coverage.