Subsection Polisher (local, pre-merge)

Purpose: upgrade one sections/S<sub_id>.md (H3 body-only) so it reads like survey prose before you merge into output/DRAFT.md .

This is intentionally local: fix one unit at a time, rerun gates, and converge without rewriting the whole paper.

Role cards (use explicitly)

Local Section Editor

Mission: improve one H3’s argument density and paper voice without changing citation keys.

Do:

• Rewrite the opener as tension -> why it matters -> thesis (end paragraph 1 with thesis).

• Add explicit contrasts and one evaluation anchor when missing.

• Add a subsection-specific limitation that changes interpretation.

Avoid:

• Adding/removing citation keys or moving citations across subsections.

• Replacing content with generic boilerplate.

Evidence Steward (stop padding)

Mission: prevent polishing from turning into invention when evidence is thin.

Do:

• If you cannot write a contrast or evaluation anchor without guessing, stop and route upstream.

Avoid:

• Strengthening claims beyond what the existing citations can support.

Role prompt: Local Section Editor (one H3 at a time)

You are editing one survey subsection to make it read like paper prose.

Your goal is to remove generator voice and strengthen argument moves without changing citation keys:

• opener: tension + why-it-matters + thesis (no narration)
• add explicit contrasts and an evaluation anchor if missing
• make at least one cross-paper synthesis paragraph (>=2 citations)
• add a subsection-specific limitation (not boilerplate)

Constraints:

• do not add/remove citation keys
• do not invent facts
• keep scope local to this H3

Inputs

• Target file: sections/S<sub_id>.md (H3 body-only)

• Preferred context: outline/writer_context_packs.jsonl

• Fallback context: outline/subsection_briefs.jsonl

• outline/evidence_drafts.jsonl

• citations/ref.bib

Output

• Updated sections/S<sub_id>.md (same path; citation keys unchanged)

Non-negotiables (contract)

• Citation keys are immutable: do not add/remove any [@BibKey] markers.

• Scope is immutable: keep all citations within this H3’s allowed scope (outline/evidence_bindings.jsonl / writer pack allowed_bibkeys_* ).

• No invented facts: if you cannot write a concrete contrast or evaluation anchor without guessing, stop and fix upstream evidence.

• Body-only: no headings; section-merger adds headings.

Target quality (what “polished” means)

A polished H3 reads like an argument, not a topic list:

• Paragraph 1 ends with a thesis (conclusion-first takeaway) and does not use narration templates.

• At least two explicit contrasts (A vs B) using contrast words.

• At least one evaluation anchor paragraph (task/benchmark + metric + constraint/budget/tool access when relevant).

• At least one cross-paper synthesis paragraph with >=2 citations in the same paragraph.

• At least one limitation/caveat tied to protocol mismatch / missing details / unclear threat model (not boilerplate).

Paper voice constraints (high signal anti-patterns)

Delete / rewrite these (they read like a generator):

• Outline narration: This subsection ... , In this subsection, we ... .

• Slide navigation: Next, we move ... , We now turn to ... , In the next section ... .

• Meta guidance: survey synthesis/comparisons should ... .

• Evidence-policy disclaimer spam: repeated abstract-only/title-only/provisional boilerplate inside H3.

• Count-based slot openers: repeated "Two limitations..." / "Three takeaways..." used as paragraph starters.

Prefer these (paper voice):

• Content-first openers: A central tension is ... , In practice, ... , One recurring pattern is ... .

• Argument bridges (not navigation): This contrast matters because ... , These assumptions shape ... .

• Embedded citations as evidence (no trailing dump tags).

Workflow (one subsection)

• Load the subsection contract

• Read this subsection’s pack in outline/writer_context_packs.jsonl .

• If the pack is missing/thin, fall back to outline/subsection_briefs.jsonl (thesis/tension/paragraph_plan) + outline/evidence_drafts.jsonl (comparisons/eval/limitations).

• Extract (write down, not in the prose):

• tension_statement

• thesis

• 2–3 comparison_cards you will use for A-vs-B contrasts

• 1 evaluation_anchor_minimal (task/metric/constraint)

• 1 limitation hook from the evidence pack

• Preflight (kept out of the final prose)

• Draft 4 one-line sentences:

• Tension

• Contrast (A vs B; >=2 citations)

• Evaluation anchor (task/metric/constraint)

• Limitation If you cannot write these without guessing, stop and push the gap upstream (paper-notes / evidence-draft ).

• Opener rewrite (paragraph 1)

• Remove narration openers.

• Write: 1–2 sentences tension/decision/lens + 1 sentence why it matters + end with the thesis.

Bad:

• This subsection surveys tool interfaces for agents.

Better:

• A central tension in tool interfaces is balancing expressive action spaces with verifiable execution; interface contracts largely determine which evaluation claims are meaningful.

• Paragraph pass (argument moves > listing)

• Rewrite paragraph-by-paragraph using the grad-paragraph micro-structure:

• Best-of-2 rewrite (recommended): when a paragraph feels slot-like, draft 2 candidate rewrites and keep the one with clearer argument move + less template cadence (citations unchanged).

• tension → contrast → evaluation anchor → limitation

• Ensure you include:

=2 explicit contrasts (not “A then B” summaries)

=1 evaluation anchor paragraph

=1 cross-paper synthesis paragraph (>=2 citations)

=1 limitation paragraph/clause that is subsection-specific

• Citation embedding pass (no dumps)

• Rewrite paragraphs where citations appear only at the end as [@a; @b; @c] .

• Ensure every citation key you keep is defined in citations/ref.bib .

Bad (dump):

• Many systems adopt tool schemas. [@a; @b; @c]

Better (cite-as-evidence):

• Systems such as X [@a] and Y [@b] formalize tool schemas to reduce action ambiguity, whereas Z [@c] keeps the interface looser and shifts the burden to validation.

• Rhythm + de-template pass

• Vary paragraph openings; avoid repeating the same synthesis stem across many paragraphs (especially Taken together ).

• Delete empty glue sentences that don’t add a claim, contrast, protocol detail, or limitation.

• Recheck (do not skip)

• Run section-logic-polisher and address FAILs (thesis + connector density) without changing citation keys.

• Rerun writer-selfloop (or the strict quality gate) and fix only what the report flags.

Rewrite recipes (common failure -> fix)

Use these as rewrite intentions, not copy-paste templates.

• Narration opener -> content claim

• This subsection surveys ... -> A central tension is ...; this matters because ... (end paragraph 1 with the thesis).

• Slide navigation -> argument bridge

• Next, we move from planning to memory. -> Planning specifies how decisions are made; memory determines what information those decisions can reliably condition on under a fixed protocol.

• Disclaimer spam -> one policy paragraph + local caveat only

• Delete repeated abstract-only evidence boilerplate.

• Keep evidence policy once in Intro/Related Work; in H3, only add a local caveat when it changes the interpretation of a specific comparison.

• Meta “survey should” -> literature-facing observation

• Therefore, survey comparisons should control for tool access. -> Across reported protocols, tool access and budget assumptions vary widely, making head-to-head comparison fragile unless those constraints are normalized.

• Too-vague quantitative claim -> add minimal context (or weaken)

• If a paragraph keeps a number, add: task type / metric definition / constraint (budget/cost/tool access) in the same paragraph and keep the citation embedded.

• If the context is unknown from the evidence pack, rewrite the claim as qualitative and mark the missing field as a verification target (without boilerplate).

Stop conditions (when polishing is the wrong move)

Stop and go upstream if:

• you cannot write a contrast without guessing (evidence pack is title/abstract-only)

• the subsection lacks evaluation anchors (no benchmarks/metrics/protocol details in notes)

• you keep needing out-of-scope citations to make the argument work

Acceptance checklist

• Paragraph 1 ends with a thesis (no narration templates).

• =2 explicit contrasts, >=1 evaluation anchor, >=1 synthesis paragraph (>=2 citations), >=1 limitation.

• No slide-like navigation / meta guidance / repeated evidence-policy boilerplate.

• No citation-dump paragraphs; citations are embedded in claim sentences.

• section-logic-polisher and writer-selfloop no longer flag this file.