Paper Notes

Triggers & routing

Trigger: paper notes, structured notes, reading notes, 论文笔记, paper_notes.jsonl.
Use when: survey 的 evidence 阶段（C3），已有 papers/core_set.csv（以及可选 fulltext），需要为后续 claims/citations/writing 准备可引用证据。

Produce consistent, searchable paper notes that later steps (claims, visuals, writing) can reliably synthesize.

This is still NO PROSE: keep notes as bullets / short fields, not narrative paragraphs.

Load Order

Always read:

references/overview.md
references/note_schema.md

Read by task:

references/limitation_taxonomy.md when writing or reviewing limitations (avoid boilerplate)
references/resultextractionexamples.md when extracting key_results (good vs bad examples)
references/sourcetexthygiene.md when result/limitation fields still preserve paper self-narration or author-result wrappers

Machine-readable assets:

assets/note_schema.json — JSONL record schema for validation
assets/evidence_tags.json — evidence bank tagging categories (extensible without code changes)
assets/sourcetexthygiene.json — note-field source sentence cleanup policy
repo-wide assets/limitation-signals.json — shared polarity rules for

distinguishing unresolved constraints from resolved failures or improvements

Script Boundary

Use scripts/run.py only for:

deterministic scaffold generation from core_set + metadata
priority selection based on mapping coverage
evidence bank construction from structured note fields

Do not treat run.py as the place for:

paper-specific limitation prose (use references/limitation_taxonomy.md for guidance)
domain-specific evaluation heuristics hidden in code
reader-facing narrative text

Role cards (prompt-level guidance)

Close Reader

- Mission: extract what is specific and checkable (setup, method, metrics, limits). - Do: name concrete tasks/benchmarks and what the paper actually measures. - Avoid: generic summary boilerplate that could fit any paper.

Results Recorder

- Mission: capture evaluation anchors that later writing needs. - Do: record task + metric + constraints (budget/tool access) whenever available. - Avoid: copying numbers without the evaluation setting that makes them meaningful. - Avoid: promoting artifact introductions (X enables ..., our framework features ...) into keyresults. - Avoid: promoting benchmark-positioning, field-motivation, or author-navigation lines (we apply ... and show ..., we then discuss how ...) into keyresults.

Limitation Logger

- Mission: capture the caveats that change interpretation. - Do: write paper-specific limitations (protocol mismatch, missing ablations, threat model gaps). - Avoid: repeated generic limitations like “may not generalize” without specifics.

When to use

After you have a core set (and ideally a mapping) and need evidence-ready notes.
Before writing a survey draft.

Inputs

papers/core_set.csv
Optional: outline/mapping.tsv (to prioritize)
Optional: papers/fulltext_index.jsonl + papers/fulltext/*.txt (if running in fulltext mode)

Outputs

papers/paper_notes.jsonl (JSONL; one record per paper)
papers/evidence_bank.jsonl (JSONL; addressable evidence snippets derived from notes; profile target: course paper >=4, A150++ >=7 items/paper on average)

Decision: evidence depth

If you have extracted text (papers/fulltext/*.txt) → enrich key papers using fulltext snippets and set evidence_level: "fulltext".
If you only have abstracts (default) → keep long-tail notes abstract-level, but still fully enrich high-priority papers (see below).

Workflow (heuristic)

Uses: outline/mapping.tsv, papers/fulltext_index.jsonl.

Ensure coverage: every paperid in papers/coreset.csv must have one JSONL record.
Use mapping to choose high-priority papers:

- heavily reused across subsections - pinned classics (ReAct/Toolformer/Reflexion… if in scope)

For high-priority papers, capture:

- 3–6 summary bullets (what’s new, what problem setting, what’s the loop) - method (mechanism and architecture; what differs from baselines) - key_results (benchmarks/metrics; include numbers if available) - limitations (specific assumptions/failure modes; avoid generic boilerplate)

For long-tail papers:

- keep summary bullets short (abstract-derived is OK) - still include at least one limitation, but make it specific when possible

Assign a stable bibkey for each paper for citation generation.

Quality checklist

Coverage: every paperid in papers/coreset.csv appears in papers/paper_notes.jsonl.
High-priority papers have non-TODO method/results/limitations.
Limitations are not copy-pasted across many papers.
evidence_level is set correctly (abstract vs fulltext).

Evidence bank: papers/evidence_bank.jsonl exists and meets the selected profile (course paper >=4; A150++ >=7 items/paper on average).

Helper script (optional)

Quick Start

uv run python .codex/skills/paper-notes/scripts/run.py --help
uv run python .codex/skills/paper-notes/scripts/run.py --workspace <workspace>

All Options

See --help (this helper is intentionally minimal)

Examples

Generate notes, then optionally enrich priority=high papers:

- Run the helper once, then refine papers/paper_notes.jsonl (e.g., add full-text details for key papers and diversify limitations).

Notes

The helper writes deterministic metadata/abstract-level notes and marks key papers with priority=high.
In pipeline.py --strict it will be blocked if high-priority notes are incomplete (missing method/key_results/limitations) or contain placeholders.

Troubleshooting

Common Issues

Issue: High-priority notes still look like scaffolds

Symptom:

Quality gate reports missing method/key_results or TODO placeholders.

Causes:

Notes were generated from abstracts only; key papers weren’t enriched.

Solutions:

Fully enrich priority=high papers: method, ≥1 keyresults, ≥3 summarybullets, ≥1 concrete limitations.
If you need full text evidence, run pdf-text-extractor in fulltext mode for key papers.

Issue: Repeated limitations across many papers