-
Pin down the venue's conventions. Read venues/conferences/<id>.yml
(fields: family, format.template, review.blind, track page limits)
and the family file it references. Profiles are a starting point, never
ground truth — re-verify anything that affects the draft (template, blind
level, page budget) against the live cfp_url before relying on it.
Then read references/placement-conventions.md
for where the section goes, how long it runs, citation-command style, and
self-citation rules at that venue family. When conventions are unclear,
confirm empirically: pull 3–5 recent papers from the venue itself
(find-papers DBLP toc query, study-exemplars) and observe placement.
-
Derive the REQUIRED clusters from the paper's claimed scope — before
looking at what was retrieved. Enumerate the paper's contributions,
sub-tasks, and requirements from the brief/intro. For each, name the
cluster of direct prior approaches a reviewer would expect to see
positioned against, plus the foundational-lineage / canonical anchor that
sub-area is built on (the originating method, not only the latest
refinement). This list is the target; it does not yet have citations.
Driving it from claimed scope (not the corpus) is what makes it generalize
across papers and venues, and is what surfaces the hole the retrieved pile
hides. Method and worked examples:
references/clustering-and-deltas.md
(§ Required clusters from claimed scope).
-
Assemble the candidate pool — retrieved papers only. Sources:
the user's .bib, find-papers results, the references and citations of
the 1–2 closest known papers (find-papers --paper style lookups). Pull
deliberately toward the required clusters from step 2, not just whatever
a topic search returned. Target 10–25 candidates. A paper enters the pool
only with a concrete identifier (DOI or arXiv ID). If the user names a
paper without one, find it first; if it cannot be found, say so — never
proceed on a guessed reference.
-
Build the clustering worksheet. Run:
python3 scripts/gather_candidates.py <DOI> <arXiv-ID> ... [--from-file ids.txt]
It fetches each paper's metadata one polite request at a time (title,
year, venue, citation count, abstract, tldr) and prints a worksheet with
empty cluster: / delta: slots. Treat the output as transient working
material — it contains abstracts; never commit it. Identifiers it flags
as unresolved (exit 3) are unverified: park them until cleared. Where the
abstract is missing or the paper is pivotal, read it via fetch-paper.
-
Map the pool onto the required clusters and run the coverage gate.
Assign each retrieved paper to one of the step-2 required clusters (a
paper that fits none is an outlier — keep only if reviewer-expected).
Write the assignment into a small plan file (one block per required
cluster, listing the cite keys assigned). Tag each key by evidence tier
so precision stays visible and the floor cannot be met by padding — append
!graph / !keyword / !heuristic to a key the paper is not confirmed
to cite (an untagged key means "the paper is known to cite this"):
"refs": ["li2018deep", "yao2019computing", # confirmed-cited
"smith2023!graph", # surfaced by citation-graph edge — plausible
"doe2022!heuristic"] # 'a strong paper would cite this' — weakest
Then run:
python3 scripts/check_coverage.py plan.json # or plan.txt (see --help)
Only confirmed-cited refs count toward the floor. The gate FAILs
(exit 3) on any required cluster with zero confirmed cites — including
one "covered" only by speculative refs (padding masks a real hole) — and
WARNs below the floor (default 2). It also prints a precision estimate
(confirmed / total) and caps heuristic-only additions (default 2 across the
plan, --heuristic-cap) so the core set stays scope-justified. On a failing
or thin cluster, take its emitted second-pass retrieval worklist back
to find-papers and fill the gap with confirmed cites, then re-run — do
NOT draft over an empty required cluster, satisfy the floor by padding with
speculative refs, or ship a gap as a silent author to-do. Only when the gate
clears (or the user explicitly accepts a documented thin cluster) proceed to
clustering prose.
-
Cluster and articulate the delta per cluster. With coverage cleared,
group the pool into 3–6 themes along the axis that makes this paper's
gap visible, then write one delta sentence per cluster: what the cluster
achieves, what it lacks for this paper's problem, what this paper does
about it. Method, patterns, and anti-patterns:
references/clustering-and-deltas.md.
Show the user the cluster plan (cluster names, members, delta sentences)
before writing prose — restructuring is cheap now, expensive later.
-
Draft the section. One paragraph per cluster (claim sentence →
representative works → limitation → delta), a dedicated paragraph for the
single closest competitor, and a closing positioning paragraph. Match the
venue: citation commands and self-citation voice per step 1; calibrate
length and breadth to the venue family's measured exemplar median, not
to maximal coverage — read the profile's exemplar_distribution
(related_work band when present) or measure 3–5 recent venue papers via
study-exemplars, falling back to the family norm in
references/placement-conventions.md
only when neither exists. Emit .tex (or markdown if the draft is not
LaTeX) plus BibTeX entries for any citation not already in the user's
.bib — entries built strictly from retrieved metadata. Add a comparison
table only when the criteria in the clustering reference are met.
-
Audit deterministically. Run:
python3 scripts/audit_bib.py refs.bib --tex related-work.tex
Fix every blocking finding: cite keys missing from the .bib, duplicate
entries, entries with no DOI/eprint/URL (unverifiable — the classic
hallucinated-reference shape), incomplete entries. The style census in
its output must match the venue's convention.
-
Gate through verify-citations. Every entry cited by the new section
gets verified against Crossref/DBLP/S2 before delivery. Anything that
fails verification is removed from the prose or explicitly flagged to the
user as unconfirmed — never left in silently, and never "fixed" by
inventing plausible fields.
