Prose Writer (Evidence-first)

Goal: produce a survey draft that reads like a real paper because it is driven by evidence packs, not by outline placeholders.

This skill should behave like a synthesis engine:

• inputs = subsection briefs + evidence drafts
• output = paragraph-level claim → evidence → synthesis (with citations)

Non-negotiables

• No prose without approval: for surveys, require Approve C2 in DECISIONS.md.
• No invented citations: only use keys present in citations/ref.bib.
• No placeholder leakage: if any upstream artifact still contains scaffold markers/ellipsis/TODO, do not write; block and request evidence fixes.
• No pipeline voice: do not leak internal scaffolding terms like “working claim”, “enumerate 2-4”, “scope/design space/evaluation practice”.

Inputs

• outline/outline.yml
• outline/subsection_briefs.jsonl
• outline/transitions.md
• outline/evidence_drafts.jsonl
• Optional: outline/tables.md, outline/timeline.md, outline/figures.md
• Optional: outline/claim_evidence_matrix.md
• citations/ref.bib
• DECISIONS.md

Outputs

• output/DRAFT.md and/or output/SNAPSHOT.md

Decision: snapshot vs draft

• Snapshot: bullets-first, ~1 page; summarize what evidence exists + what is missing.
• Draft: section-by-section prose that follows each subsection’s paragraph_plan and uses paragraph-level citations.

Workflow (v3: planner↔writer, section-by-section)

Before writing, load the structural and coherence inputs: outline/outline.yml (section order) and outline/transitions.md (transition map). Optionally consult outline/claim_evidence_matrix.md as an evidence index.

1. Gate check (HITL)

   • Read DECISIONS.md.
   • If Approve C2 is not ticked, write a short request block (what you plan to write + which evidence packs you will rely on), then stop.

2. Input integrity check (fail fast)

   • Read outline/subsection_briefs.jsonl and confirm every H3 has a brief and the following fields are filled and non-placeholder: scope_rule, rq, axes, clusters, paragraph_plan.
   • Read outline/evidence_drafts.jsonl and confirm every H3 has an evidence pack with:
     • blocking_missing empty,
     • evidence_snippets non-empty,
     • concrete_comparisons >= 3.

3. Planner pass (NO PROSE YET)

   • For each H3 subsection, read its brief + evidence pack and decide:
     • Thesis: 1 sentence that is true for this subsection and would be false in other subsections.
     • Two contrasts: 2 sentences of the form “A vs B” where each side is grounded in specific cited works (not “they differ”).
     • One limitation/failure mode: 1 sentence grounded in the evidence pack’s failures_limitations or snippet provenance.
     • Cite placement: which citations will appear in which paragraph (so citations are evidence, not decoration).
   • If you cannot do this without guessing, stop and push the gap upstream (strengthen briefs/notes/evidence packs) rather than writing template prose.

4. Writer pass (write per subsection; avoid global dump)

   • Write 2–3 paragraphs per H3 following paragraph_plan.
   • Keep prose natural, but make every paragraph an argument: claim → cited evidence → synthesis.
   • Evidence note placement: if the run is abstract-only, put a single short evidence note once (e.g., in the introduction or an “Evidence note” subsection). Do not repeat the same “abstract-only” disclaimer sentence in every H3; only mention verification needs when they are subsection-specific.
   • Enforce scope_rule strictly to prevent silent drift; if you include an out-of-scope paper as a bridge, justify it once and keep it secondary.

5. Weave transitions (coherence)

   • Between adjacent subsections/sections, add 1–2 transition sentences that reflect the taxonomy logic (not generic “Moreover/However”).

6. Integrate cross-cutting artifacts

   • Insert outline/tables.md (>=2 tables), outline/timeline.md (>=8 cited milestones), and outline/figures.md (>=2 specs) into the draft.
   • Prefer referencing tables in prose over restating an identical “axes list” sentence in every subsection.

7. Self-check + revise (hard fail signals)

   • If the draft contains ..., unicode ellipsis …, scaffold phrases (e.g., “enumerate 2-4 …”), or repeated boilerplate sentences, treat it as a pipeline failure signal and rewrite.
   • If tables contain truncation or instruction-like text, regenerate them upstream (C4) rather than patching them into the prose.

Anti-template bans (hard fail)

Do not emit any of the following in final prose (rewrite upstream instead):

• “Scope and definitions … / Design space … / Evaluation practice …”
• “enumerate 2-4 …”
• “We use the following working claim …”
• “Across representative works, the dominant trade-offs …”
• “A useful way to compare approaches is …”
• “abstracts are treated as verification targets …”
• “The main axes we track are …”

Quality checklist

• No …, TODO, (placeholder), or <!-- SCAFFOLD --> remains in output/DRAFT.md.
• Every subsection has citations and at least one paragraph with >=2 citations (cross-paper synthesis).
• No undefined citation keys (all keys exist in citations/ref.bib).
• Scope is consistent with GOAL.md and scope_rule.

Helper script (bootstrap)

The helper script is a gate wrapper: it blocks until approvals + prerequisites are satisfied and a real output/DRAFT.md exists (no scaffold markers). Writing itself is LLM-driven.

Quick Start

• python .codex/skills/prose-writer/scripts/run.py --help
• python .codex/skills/prose-writer/scripts/run.py --workspace <workspace_dir>

All Options

• See --help.

Examples

• Run the gate wrapper after approval (it will block until output/DRAFT.md is written):
  • Tick Approve C2 in DECISIONS.md then run:
  • python .codex/skills/prose-writer/scripts/run.py --workspace workspaces/<ws>

Troubleshooting

Issue: writer outputs ellipsis / scaffold text

Symptom: output/DRAFT.md contains …, enumerate 2-4 ..., or repeats the same paragraph template.

Causes:

• outline/subsection_briefs.jsonl is missing or generic.
• outline/evidence_drafts.jsonl has blocking_missing or scaffold markers.

Solutions:

• Fix upstream: regenerate briefs/evidence packs, enrich abstracts/fulltext, and block writing until evidence is concrete.

Issue: scope drift (e.g., T2I vs T2V)

Symptom: subsections cite many out-of-scope papers without justification.

Solutions:

• Tighten scope_rule in subsection briefs and rerun evidence packs.
• Tighten queries.md excludes and rerun retrieval/dedupe/mapping.