Opener Variator (H3 first paragraph rewrite)

Purpose: fix a high-signal automation tell that survives structural gates:

• many H3s begin with the same rhetorical shape

• "overview" narration replaces content-bearing framing

This skill is intentionally narrow:

• only rewrite the first paragraph (or first 2–4 sentences) of the flagged H3 files

• keep the argument moves and citations intact

Inputs

Required:

• output/WRITER_SELFLOOP_TODO.md (Style Smells section)

• the referenced sections/S<sub_id>.md files

Optional (helps you stay aligned):

• outline/writer_context_packs.jsonl (use opener_mode , tension_statement , thesis )

Outputs

Note: keep this as an openers-last pass. Run it after paragraph-curator so you do not keep rewriting paragraph 1 while the body is still changing. Current compatibility policy: the script is marker-only; substantive opener repair should happen upstream in subsection-writer / chapter-lead-writer , not through blind regex rewriting.

• Updated sections/S<sub_id>.md files (still body-only; no headings)

Workflow (route from the self-loop report)

• Open output/WRITER_SELFLOOP_TODO.md and locate ## Style Smells .

• Treat the flagged sections/S*.md list as the only scope for this pass.

• For each flagged file:

• Optional: look up its entry in outline/writer_context_packs.jsonl and read opener_mode / tension_statement / thesis to stay aligned.

• Do the real rewrite upstream in subsection-writer or chapter-lead-writer ; do not rely on blind local regex passes.

• Best-of-3 opener sampling (recommended): draft 2-3 candidate opener paragraphs (different opener modes), then keep the one that is most content-bearing and least repetitive across H3s.

• Rerun writer-selfloop and confirm the Style Smells list shrinks.

Role prompt: Opener Editor (paper voice)

You are rewriting the opening paragraph of a survey subsection.

Goal:

• replace narration/overview openers with a content-bearing framing
• vary opener cadence across subsections so the paper reads authored

Constraints:

• do not invent facts
• do not add/remove/move citation keys
• do not change the subsection’s thesis

Checklist:

• sentence 1 is content-bearing (tension/decision/failure/protocol/contrast), not “what we do in this section”
• paragraph 1 ends with a clear thesis/takeaway
• no slide navigation (“Next, we…”, “In this subsection…”, “This section provides an overview…“)

What to delete (high-signal narration)

Rewrite immediately if the opener contains any of:

• “This section/subsection provides an overview …”

• “In this section/subsection, we …”

• “This subsection surveys/argues …”

• “Next, we move/turn …”

• repeated opener labels (“Key takeaway:” spam)

What to replace with (opener moves)

Pick one opener mode per H3 (the writer pack may suggest opener_mode ). Do not copy labels; write as natural prose.

Allowed opener moves (choose 1; keep it concrete):

• Tension-first: state the real trade-off; why it matters; end with thesis.

• Decision-first: frame the builder’s choice under constraints; end with thesis.

• Failure-first: start from a failure mode that motivates the lens; end with thesis.

• Protocol-first: start from comparability constraints (budget/tool access); end with thesis.

• Contrast-first: open with an A-vs-B sentence, then explain why; end with thesis.

• Lens-first: state the chapter lens and narrow to this subsection’s question.

Mini examples (paraphrase; do not copy)

Bad (overview narration):

• This subsection provides an overview of tool interfaces for agents.

Better (content-bearing):

• Tool interfaces define what actions are executable; interface contracts therefore determine which evaluation claims transfer across environments.

Bad (process narration):

• In this subsection, we discuss memory mechanisms and then review retrieval methods.

Better (tension-first):

• Memory improves long-horizon coherence, but it also expands the failure surface: retrieval can be stale, wrong, or adversarial, and agents rarely know which.

Done checklist

• No flagged file starts with “overview/narration” stems.

• Paragraph 1 ends with a thesis/takeaway (same meaning).

• Citation keys are unchanged (no adds/removes/moves).

• writer-selfloop still PASSes and Style Smells shrink.

Script

Quick Start

• python .codex/skills/opener-variator/scripts/run.py --workspace workspaces/<ws>

All Options

• --workspace <dir> (required)

• --unit-id <U###>

• --inputs <semicolon-separated>

• --outputs <semicolon-separated>

• --checkpoint <C#>

Examples

• Rewrite openers in a survey workspace:

• python .codex/skills/opener-variator/scripts/run.py --workspace workspaces/survey-llm-agents