Draft Polisher (Audit-style editing)
Goal: turn a first-pass draft into readable survey prose without breaking the evidence contract.
This is a local polish pass: de-template + coherence + terminology + redundancy pruning.
Role cards (use explicitly)
Style Harmonizer (editor)
Mission: remove generator voice and make prose read like one author wrote it.
Do:
- Delete narration openers and slide navigation; replace with argument bridges.
- Vary rhythm; remove repeated template stems.
- Collapse repeated disclaimers into one front-matter methodology paragraph.
Avoid:
- Adding or removing citation keys.
- Moving citations across subsections.
Evidence Contract Guard (skeptic)
Mission: prevent polishing from inflating claims beyond evidence.
Do:
- Keep quantitative statements scoped (task/metric/constraint) or weaken them.
- Treat missing evidence as a failure signal; route upstream rather than rewriting around gaps.
Avoid:
- Overconfident language when evidence is abstract-only.
Role prompt: Style Harmonizer (editor expert)
You are the style and coherence editor for a technical survey.
Your goal is to make the draft read like one careful author wrote it, without changing the evidence contract.
Hard constraints:
- do not add/remove citation keys
- do not move citations across ### subsections
- do not strengthen claims beyond what existing citations support
High-leverage edits:
- delete generator voice (This subsection..., Next we move..., We now turn...)
- replace navigation with argument bridges (content-bearing handoffs)
- collapse repeated disclaimers into one methodology paragraph in front matter
- keep quantitative statements well-scoped (task/metric/constraint in the same sentence)
Working style:
- rewrite sentences so they carry content, not process
- vary rhythm, but avoid “template stems” repeating across H3s
Inputs
output/DRAFT.md- Optional context (read-only; helps avoid “polish drift”):
outline/outline.ymloutline/subsection_briefs.jsonloutline/evidence_drafts.jsonlcitations/ref.bib
Outputs
output/DRAFT.md (in-place refinement)output/citation_anchors.prepolish.jsonl (baseline, generated on first run by the script)
Non-negotiables (hard rules)
- Citation keys are immutable
- Do not add new
[@BibKey] keys.
- Do not delete citation markers.
- If
citations/ref.bib exists, do not introduce any key that is not defined there.
- Citation anchoring is immutable
- Do not move citations across
### subsections.
- If you must restructure across subsections, stop and push the change upstream (outline/briefs/evidence), then regenerate.
- No evidence inflation
- If a sentence sounds stronger than the evidence level (abstract-only), rewrite it into a qualified statement.
- When in doubt, check the subsection’s evidence pack in
outline/evidence_drafts.jsonl and keep claims aligned to snippets.
- Quantitative claim hygiene
- If you keep a number, ensure the sentence also states (without guessing): task type + metric definition + relevant constraint (budget/cost/tool access), and the citation is embedded in that sentence.
- Avoid ambiguous model naming (e.g., “GPT-5”) unless the cited paper uses that exact label; otherwise use the paper’s naming or a neutral description.
- No pipeline voice
- Remove scaffolding phrases like:
- “We use the following working claim …”
- “The main axes we track are …”
- “abstracts are treated as verification targets …”
- “Method note (evidence policy): …” (avoid labels; rewrite as plain survey methodology)
- “this run is …” (rewrite as survey methodology: “This survey is …”)
- “Scope and definitions / Design space / Evaluation practice …”
- “Next, we move from …”
- “We now turn to …”
- “From to , ...” (title narration; rewrite as an argument bridge)
- “In the next section/subsection …”
- “Therefore/As a result, survey synthesis/comparisons should …” (rewrite as literature-facing observation)
- Also remove generator-like thesis openers that read like outline narration:
- “This subsection surveys …”
- “This subsection argues …”
Three passes (recommended)
Pass 1 — Subsection polish (structure + de-template)
Role split:
- Editor: rewrite sentences for clarity and flow.
- Skeptic: deletes any generic/template sentence.
Targets:
- Each H3 reads like: tension → contrast → evidence → limitation.
- Remove repeated “disclaimer paragraphs”; keep evidence-policy in one place (prefer a single paragraph in Introduction or Related Work phrased as survey methodology, not as pipeline/execution logs).
- Use
outline/outline.yml (if present) to avoid heading drift during edits.
- If present, use
outline/subsection_briefs.jsonl to keep each H3’s scope/RQ consistent while improving flow.
- Do a quick “pattern sweep” (semantic, not mechanical):
- delete outline narration:
This subsection ..., In this subsection ...
- delete slide navigation:
Next, we move from ..., We now turn to ..., In the next section ...
- delete title narration:
From <X> to <Y>, ...
- replace with: content claims + argument bridges + organization sentences (no new facts/citations)
- If
citation-injector was used, smooth any budget-injection sentences so they read paper-like:
- Keep the citation keys unchanged.
- Avoid list-injection stems (e.g., “A few representative references include …”, “Notable lines of work include …”, “Concrete examples ... include ...”).
- Prefer integrating the added citations into an existing argument sentence, or rewrite as a short parenthetical
e.g., ... clause tied to the subsection’s lens (no new facts).
- Vary phrasing; avoid repeating the same opener stem across many H3s.
- Tone: keep it calm and academic; remove hype words and repeated opener labels (e.g., literal
Key takeaway: across many H3s).
- Reduce repeated synthesis stems (e.g., many paragraphs starting with
Taken together, ...); vary synthesis phrasing and keep it content-bearing.
- Treat repeated "Taken together," as a generator-voice smell. If it appears more than twice (or clusters in one chapter), rewrite to vary phrasing and keep each synthesis sentence content-specific.
- Vary synthesis openings: "In summary," "Across these studies," "The pattern that emerges," "A key insight," "Collectively," "The evidence suggests," or directly state the conclusion without a synthesis marker.
- Each synthesis opening should be content-specific, not a template label.
Rewrite recipe for subsection openers (paper voice, no new facts):
- Delete:
This subsection surveys/argues... / In this subsection, we...
- Replace with a compact opener that does 2–3 of these (no labels; vary across subsections):
- Content claim: the subsection-specific tension/trade-off (optionally with 1–2 embedded citations)
- Why it matters: link the claim to evaluation/engineering constraints (benchmark/protocol/cost/tool access)
- Preview: what you will contrast next and on what lens (A vs B; then evaluation anchors; then limitations)
- Example skeletons (paraphrase; don’t reuse verbatim):
- Tension-first:
A central tension is ...; ...; we contrast ...
- Decision-first:
For builders, the crux is ...; ...
- Lens-first:
Seen through the lens of ..., ...
Pass 2 — Terminology normalization
Role split:
- Taxonomist: chooses canonical terms and synonym policy.
- Integrator: applies consistent replacements across the draft.
Targets:
- One concept = one name across sections.
- Headings, tables, and prose use the same canonical terms.
Pass 3 — Redundancy pruning (global repetition)
Role split:
- Compressor: collapses repeated boilerplate.
- Narrative keeper: ensures removing repetition does not break the argument chain.
Targets:
- Cross-section repeated intros/outros are removed.
- Only subsection-specific content remains inside subsections.
Script
Quick Start
python .codex/skills/draft-polisher/scripts/run.py --helppython .codex/skills/draft-polisher/scripts/run.py --workspace workspaces/<ws>
All Options
--workspace <dir>: workspace root--unit-id <U###>: unit id (optional; for logs)--inputs <semicolon-separated>: override inputs (rare; prefer defaults)--outputs <semicolon-separated>: override outputs (rare; prefer defaults)--checkpoint <C#>: checkpoint id (optional; for logs)
Examples
Acceptance checklist
Troubleshooting
Issue: polishing causes citation drift across subsections
Fix:
- Keep citations inside the same
### subsection; if restructuring is intentional, delete output/citation_anchors.prepolish.jsonl and regenerate a new baseline.
Issue: draft polishing is requested before writing approval
Fix:
- Record the relevant approval in
DECISIONS.md (typically Approve C2) before doing prose-level edits.
1---2name: draft-polisher3description: Audit-style editing pass for `output/DRAFT.md`: remove template boilerplate, improve coherence, and enforce citation anchoring. **Trigger**: polish draft, de-template, coherence pass, remove boilerplate, 润色, 去套话, 去重复, 统一术语. **Use when**: a first-pass draft exists but reads like scaffolding (repetition/ellipsis/template phrases) or needs a coherence pass before global review/LaTeX. **Skip if**: the draft already reads human-grade and passes quality gates; or prose is not approved in `DECISIONS.md`. **Network**: none. **Guardrail**: do not add/remove/invent citation keys; do not move citations across subsections; do not change claims beyond what existing citations support.4---5
6# Draft Polisher (Audit-style editing)
7
8Goal: turn a first-pass draft into readable survey prose **without breaking the evidence contract**.
9
10This is a local polish pass: de-template + coherence + terminology + redundancy pruning.
11
12
13## Role cards (use explicitly)
14
15### Style Harmonizer (editor)
16
17Mission: remove generator voice and make prose read like one author wrote it.
18
19Do:
20- Delete narration openers and slide navigation; replace with argument bridges.
21- Vary rhythm; remove repeated template stems.
22- Collapse repeated disclaimers into one front-matter methodology paragraph.
23
24Avoid:
25- Adding or removing citation keys.
26- Moving citations across subsections.
27
28### Evidence Contract Guard (skeptic)
29
30Mission: prevent polishing from inflating claims beyond evidence.
31
32Do:
33- Keep quantitative statements scoped (task/metric/constraint) or weaken them.
34- Treat missing evidence as a failure signal; route upstream rather than rewriting around gaps.
35
36Avoid:
37- Overconfident language when evidence is abstract-only.
38
39
40## Role prompt: Style Harmonizer (editor expert)
41
42```text
43You are the style and coherence editor for a technical survey.
44
45Your goal is to make the draft read like one careful author wrote it, without changing the evidence contract.
46
47Hard constraints:
48- do not add/remove citation keys
49- do not move citations across ### subsections
50- do not strengthen claims beyond what existing citations support
51
52High-leverage edits:
53- delete generator voice (This subsection..., Next we move..., We now turn...)
54- replace navigation with argument bridges (content-bearing handoffs)
55- collapse repeated disclaimers into one methodology paragraph in front matter
56- keep quantitative statements well-scoped (task/metric/constraint in the same sentence)
57
58Working style:
59- rewrite sentences so they carry content, not process
60- vary rhythm, but avoid “template stems” repeating across H3s
61```
62
63## Inputs
64
65- `output/DRAFT.md`
66- Optional context (read-only; helps avoid “polish drift”):
67 - `outline/outline.yml`
68 - `outline/subsection_briefs.jsonl`
69 - `outline/evidence_drafts.jsonl`
70 - `citations/ref.bib`
71
72## Outputs
73
74- `output/DRAFT.md` (in-place refinement)
75- `output/citation_anchors.prepolish.jsonl` (baseline, generated on first run by the script)
76
77## Non-negotiables (hard rules)
78
791) **Citation keys are immutable**
80- Do not add new `[@BibKey]` keys.
81- Do not delete citation markers.
82- If `citations/ref.bib` exists, do not introduce any key that is not defined there.
83
842) **Citation anchoring is immutable**
85- Do not move citations across `###` subsections.
86- If you must restructure across subsections, stop and push the change upstream (outline/briefs/evidence), then regenerate.
87
883) **No evidence inflation**
89- If a sentence sounds stronger than the evidence level (abstract-only), rewrite it into a qualified statement.
90- When in doubt, check the subsection’s evidence pack in `outline/evidence_drafts.jsonl` and keep claims aligned to snippets.
91
924) **Quantitative claim hygiene**
93- If you keep a number, ensure the sentence also states (without guessing): task type + metric definition + relevant constraint (budget/cost/tool access), and the citation is embedded in that sentence.
94- Avoid ambiguous model naming (e.g., “GPT-5”) unless the cited paper uses that exact label; otherwise use the paper’s naming or a neutral description.
95
965) **No pipeline voice**
97- Remove scaffolding phrases like:
98 - “We use the following working claim …”
99 - “The main axes we track are …”
100 - “abstracts are treated as verification targets …”
101 - “Method note (evidence policy): …” (avoid labels; rewrite as plain survey methodology)
102 - “this run is …” (rewrite as survey methodology: “This survey is …”)
103 - “Scope and definitions / Design space / Evaluation practice …”
104 - “Next, we move from …”
105 - “We now turn to …”
106 - “From <X> to <Y>, ...” (title narration; rewrite as an argument bridge)
107 - “In the next section/subsection …”
108 - “Therefore/As a result, survey synthesis/comparisons should …” (rewrite as literature-facing observation)
109- Also remove generator-like thesis openers that read like outline narration:
110 - “This subsection surveys …”
111 - “This subsection argues …”
112
113## Three passes (recommended)
114
115### Pass 1 — Subsection polish (structure + de-template)
116
117Role split:
118- **Editor**: rewrite sentences for clarity and flow.
119- **Skeptic**: deletes any generic/template sentence.
120
121Targets:
122- Each H3 reads like: tension → contrast → evidence → limitation.
123- Remove repeated “disclaimer paragraphs”; keep evidence-policy in **one** place (prefer a single paragraph in Introduction or Related Work phrased as survey methodology, not as pipeline/execution logs).
124- Use `outline/outline.yml` (if present) to avoid heading drift during edits.
125- If present, use `outline/subsection_briefs.jsonl` to keep each H3’s scope/RQ consistent while improving flow.
126- Do a quick “pattern sweep” (semantic, not mechanical):
127 - delete outline narration: `This subsection ...`, `In this subsection ...`
128 - delete slide navigation: `Next, we move from ...`, `We now turn to ...`, `In the next section ...`
129 - delete title narration: `From <X> to <Y>, ...`
130 - replace with: content claims + argument bridges + organization sentences (no new facts/citations)
131- If `citation-injector` was used, smooth any budget-injection sentences so they read paper-like:
132 - Keep the citation keys unchanged.
133 - Avoid list-injection stems (e.g., “A few representative references include …”, “Notable lines of work include …”, “Concrete examples ... include ...”).
134 - Prefer integrating the added citations into an existing argument sentence, or rewrite as a short parenthetical `e.g., ...` clause tied to the subsection’s lens (no new facts).
135 - Vary phrasing; avoid repeating the same opener stem across many H3s.
136- Tone: keep it calm and academic; remove hype words and repeated opener labels (e.g., literal `Key takeaway:` across many H3s).
137- **Reduce repeated synthesis stems** (e.g., many paragraphs starting with `Taken together, ...`); vary synthesis phrasing and keep it content-bearing.
138 - Treat repeated "Taken together," as a generator-voice smell. If it appears more than twice (or clusters in one chapter), rewrite to vary phrasing and keep each synthesis sentence content-specific.
139 - Vary synthesis openings: "In summary," "Across these studies," "The pattern that emerges," "A key insight," "Collectively," "The evidence suggests," or directly state the conclusion without a synthesis marker.
140 - Each synthesis opening should be content-specific, not a template label.
141
142Rewrite recipe for subsection openers (paper voice, no new facts):
143- Delete: `This subsection surveys/argues...` / `In this subsection, we...`
144- Replace with a compact opener that does 2–3 of these (no labels; vary across subsections):
145 - **Content claim**: the subsection-specific tension/trade-off (optionally with 1–2 embedded citations)
146 - **Why it matters**: link the claim to evaluation/engineering constraints (benchmark/protocol/cost/tool access)
147 - **Preview**: what you will contrast next and on what lens (A vs B; then evaluation anchors; then limitations)
148- Example skeletons (paraphrase; don’t reuse verbatim):
149 - Tension-first: `A central tension is ...; ...; we contrast ...`
150 - Decision-first: `For builders, the crux is ...; ...`
151 - Lens-first: `Seen through the lens of ..., ...`
152
153### Pass 2 — Terminology normalization
154
155Role split:
156- **Taxonomist**: chooses canonical terms and synonym policy.
157- **Integrator**: applies consistent replacements across the draft.
158
159Targets:
160- One concept = one name across sections.
161- Headings, tables, and prose use the same canonical terms.
162
163### Pass 3 — Redundancy pruning (global repetition)
164
165Role split:
166- **Compressor**: collapses repeated boilerplate.
167- **Narrative keeper**: ensures removing repetition does not break the argument chain.
168
169Targets:
170- Cross-section repeated intros/outros are removed.
171- Only subsection-specific content remains inside subsections.
172
173## Script
174
175### Quick Start
176
177- `python .codex/skills/draft-polisher/scripts/run.py --help`
178- `python .codex/skills/draft-polisher/scripts/run.py --workspace workspaces/<ws>`
179
180### All Options
181
182- `--workspace <dir>`: workspace root
183- `--unit-id <U###>`: unit id (optional; for logs)
184- `--inputs <semicolon-separated>`: override inputs (rare; prefer defaults)
185- `--outputs <semicolon-separated>`: override outputs (rare; prefer defaults)
186- `--checkpoint <C#>`: checkpoint id (optional; for logs)
187
188### Examples
189
190- First polish pass (creates anchoring baseline `output/citation_anchors.prepolish.jsonl`):
191 - `python .codex/skills/draft-polisher/scripts/run.py --workspace workspaces/<ws>`
192
193- Reset the anchoring baseline (only if you intentionally accept citation drift):
194 - Delete `output/citation_anchors.prepolish.jsonl`, then rerun the polisher.
195
196## Acceptance checklist
197
198- [ ] No `TODO/TBD/FIXME/(placeholder)`.
199- [ ] No `…` or `...` truncation.
200- [ ] No repeated boilerplate sentence across many subsections.
201- [ ] Citation anchoring passes (no cross-subsection drift).
202- [ ] Each H3 has at least one cross-paper synthesis paragraph (>=2 citations).
203
204## Troubleshooting
205
206### Issue: polishing causes citation drift across subsections
207
208**Fix**:
209- Keep citations inside the same `###` subsection; if restructuring is intentional, delete `output/citation_anchors.prepolish.jsonl` and regenerate a new baseline.
210
211### Issue: draft polishing is requested before writing approval
212
213**Fix**:
214- Record the relevant approval in `DECISIONS.md` (typically `Approve C2`) before doing prose-level edits.
majiayu000