Paper Notes
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.
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.
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)
Output
papers/paper_notes.jsonl (JSONL; one record per paper)
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
paper_id in papers/core_set.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
Helper script (optional)
Quick Start
python .codex/skills/paper-notes/scripts/run.py --helppython .codex/skills/paper-notes/scripts/run.py --workspace <workspace_dir>
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 key_results, ≥3 summary_bullets, ≥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
Symptom:
- Quality gate reports repeated limitation boilerplate.
Causes:
- Copy-pasted limitations instead of paper-specific failure modes/assumptions.
Solutions:
- Replace boilerplate with paper-specific limitations (setup, data, evaluation gaps, failure cases).
Recovery Checklist
1---2name: paper-notes3description: Write structured notes for each paper in the core set into `papers/paper_notes.jsonl` (summary/method/results/limitations). **Trigger**: paper notes, structured notes, reading notes, 论文笔记, paper_notes.jsonl. **Use when**: survey 的 evidence 阶段（C3），已有 `papers/core_set.csv`（以及可选 fulltext），需要为后续 claims/citations/writing 准备可引用证据。 **Skip if**: 还没有 core set（先跑 `dedupe-rank`），或你只做极轻量 snapshot 不需要细粒度证据。 **Network**: none. **Guardrail**: 具体可核对（method/metrics/limitations），避免大量重复模板；保持结构化字段而非长 prose。4---5
6# Paper Notes
7
8Produce consistent, searchable paper notes that later steps (claims, visuals, writing) can reliably synthesize.
9
10This is still **NO PROSE**: keep notes as bullets / short fields, not narrative paragraphs.
11
12## Role cards (prompt-level guidance)
13
14- **Close Reader**
15 - Mission: extract what is *specific* and *checkable* (setup, method, metrics, limits).
16 - Do: name concrete tasks/benchmarks and what the paper actually measures.
17 - Avoid: generic summary boilerplate that could fit any paper.
18
19- **Results Recorder**
20 - Mission: capture evaluation anchors that later writing needs.
21 - Do: record task + metric + constraints (budget/tool access) whenever available.
22 - Avoid: copying numbers without the evaluation setting that makes them meaningful.
23
24- **Limitation Logger**
25 - Mission: capture the caveats that change interpretation.
26 - Do: write paper-specific limitations (protocol mismatch, missing ablations, threat model gaps).
27 - Avoid: repeated generic limitations like “may not generalize” without specifics.
28
29
30## When to use
31
32- After you have a core set (and ideally a mapping) and need evidence-ready notes.
33- Before writing a survey draft.
34
35## Inputs
36
37- `papers/core_set.csv`
38- Optional: `outline/mapping.tsv` (to prioritize)
39- Optional: `papers/fulltext_index.jsonl` + `papers/fulltext/*.txt` (if running in fulltext mode)
40
41## Output
42
43- `papers/paper_notes.jsonl` (JSONL; one record per paper)
44
45## Decision: evidence depth
46
47- If you have extracted text (`papers/fulltext/*.txt`) → enrich key papers using fulltext snippets and set `evidence_level: "fulltext"`.
48- If you only have abstracts (default) → keep long-tail notes abstract-level, but still fully enrich **high-priority** papers (see below).
49
50## Workflow (heuristic)
51Uses: `outline/mapping.tsv`, `papers/fulltext_index.jsonl`.
52
53
541. Ensure **coverage**: every `paper_id` in `papers/core_set.csv` must have one JSONL record.
552. Use mapping to choose **high-priority papers**:
56 - heavily reused across subsections
57 - pinned classics (ReAct/Toolformer/Reflexion… if in scope)
583. For high-priority papers, capture:
59 - 3–6 summary bullets (what’s new, what problem setting, what’s the loop)
60 - `method` (mechanism and architecture; what differs from baselines)
61 - `key_results` (benchmarks/metrics; include numbers if available)
62 - `limitations` (specific assumptions/failure modes; avoid generic boilerplate)
634. For long-tail papers:
64 - keep summary bullets short (abstract-derived is OK)
65 - still include at least one limitation, but make it specific when possible
665. Assign a stable `bibkey` for each paper for citation generation.
67
68## Quality checklist
69
70- [ ] Coverage: every `paper_id` in `papers/core_set.csv` appears in `papers/paper_notes.jsonl`.
71- [ ] High-priority papers have non-`TODO` method/results/limitations.
72- [ ] Limitations are not copy-pasted across many papers.
73- [ ] `evidence_level` is set correctly (`abstract` vs `fulltext`).
74
75## Helper script (optional)
76
77### Quick Start
78
79- `python .codex/skills/paper-notes/scripts/run.py --help`
80- `python .codex/skills/paper-notes/scripts/run.py --workspace <workspace_dir>`
81
82### All Options
83
84- See `--help` (this helper is intentionally minimal)
85
86### Examples
87
88- Generate notes, then optionally enrich `priority=high` papers:
89 - Run the helper once, then refine `papers/paper_notes.jsonl` (e.g., add full-text details for key papers and diversify limitations).
90
91### Notes
92
93- The helper writes deterministic metadata/abstract-level notes and marks key papers with `priority=high`.
94- In `pipeline.py --strict` it will be blocked if high-priority notes are incomplete (missing method/key_results/limitations) or contain placeholders.
95
96## Troubleshooting
97
98### Common Issues
99
100#### Issue: High-priority notes still look like scaffolds
101
102**Symptom**:
103- Quality gate reports missing `method/key_results` or `TODO` placeholders.
104
105**Causes**:
106- Notes were generated from abstracts only; key papers weren’t enriched.
107
108**Solutions**:
109- Fully enrich `priority=high` papers: `method`, ≥1 `key_results`, ≥3 `summary_bullets`, ≥1 concrete `limitations`.
110- If you need full text evidence, run `pdf-text-extractor` in `fulltext` mode for key papers.
111
112#### Issue: Repeated limitations across many papers
113
114**Symptom**:
115- Quality gate reports repeated limitation boilerplate.
116
117**Causes**:
118- Copy-pasted limitations instead of paper-specific failure modes/assumptions.
119
120**Solutions**:
121- Replace boilerplate with paper-specific limitations (setup, data, evaluation gaps, failure cases).
122
123### Recovery Checklist
124
125- [ ] `papers/paper_notes.jsonl` covers all `papers/core_set.csv` paper_ids.
126- [ ] ≥80% of `priority=high` notes satisfy method/results/limitations completeness.
127- [ ] No `TODO` remains in high-priority notes.
majiayu000