| name | transition-weaver |
| description | Generate lightweight section/subsection transitions (NO NEW FACTS) to prevent “island” subsections; outputs a transition map that merging/writing can weave in.
**Trigger**: transition weaver, weave transitions, coherence, 过渡句, 承接句, 章节连贯性.
**Use when**: `outline/subsection_briefs.jsonl` exists and you want coherent flow before/after drafting (typically Stage C5).
|
Transition Weaver (LLM-first; NO NEW FACTS)
Purpose: produce a small, low-risk “transition map” so adjacent subsections do not read like islands.
This skill is intentionally low-risk and deterministic:
- the script writes
outline/transitions.md from adjacent subsection titles + brief bridge handles
- the generated transitions stay paper-safe and avoid adding new facts or citations
Transitions should answer:
- what the previous unit established
- what gap/tension remains
- why the next unit follows
Injection contract (treat transitions as draft text)
outline/transitions.md is not planning notes: section-merger injects it into output/DRAFT.md.
So each transition line must be safe to read as paper prose.
Format contract (for merge insertion):
- Only lines matching
- 3.1 -> 3.2: <text> are inserted by default (within-chapter H3 -> next H3).
- Keep
<text> as one sentence without list formatting.
Notes:
- Use the ASCII arrow
-> (not a unicode arrow) to avoid invisible/control-character encoding issues.
section-merger accepts both -> and → for backward compatibility, but -> is the preferred contract.
Hard rules:
- Write the transition sentence as final prose: content-bearing, not process-bearing.
- No planner-talk openers: avoid stems like "To keep ...", "The remaining uncertainty is ...", "setting up a cleaner ...".
- No slash-list axis labels (A / B / C; planning/memory). Rewrite using natural prose.
- Keep it short: one sentence is preferred; rarely two.
- Avoid semicolon-heavy multi-clause construction notes.
Rewrite triggers (if you see these, rewrite):
- "To keep ..." / "We next focus on ..." / "The remaining uncertainty is ..."
- "as the comparison lens" / "reference point" / "to make the next trade-offs easier to interpret"
Role prompt: Linker (coherence without narration)
You are the coherence linker for a survey.
Your job is to write short, content-bearing transitions between adjacent subsections:
- restate what was established (one clause)
- name the remaining tension/gap (one clause)
- justify why the next subsection is the right lens (one clause)
Style:
- argument bridge, not navigation
- no “Now we discuss / Next we move / In this section…”
- no semicolon planning notes
Constraints:
- NO NEW FACTS
- NO citations
- only reuse handles that already exist (titles, RQs, bridge_terms)
Style targets (paper-like, still NO NEW FACTS):
- Prefer argument bridges: content-bearing sentences, not outline narration.
- Keep it short (often 1 sentence).
- Avoid title narration once merged: do not write “From Section A to Section B”.
- Avoid “Now we discuss / Next we introduce / In this section we ...”.
CRITICAL: Transitions must be real content sentences, NOT construction notes.
- Bad: “After X, Y makes the bridge explicit via …; …; setting up a cleaner A-vs-B comparison.”
- Good: “While loop design determines what actions are possible, tool interfaces define how those actions are grounded in executable APIs and orchestration policies.”
Also avoid (reads like axis/planning notes once merged):
- Slash-list axis labels (e.g.,
A/B/C, planning/memory); rewrite using natural prose (and/or).
Inputs
outline/outline.yml (ordering + titles)outline/subsection_briefs.jsonl (expects rq and optional bridge_terms/contrast_hook)
Output
outline/transitions.md (used by section-merger; keep paper voice)
Workflow (NO NEW FACTS)
- Read
outline/outline.yml to determine adjacency (which H3 follows which).
- Read
outline/subsection_briefs.jsonl to extract each subsection’s rq and any bridge handles (bridge_terms, contrast_hook).
- For each boundary, write 1–2 transition sentences:
- no new facts
- no citations
- no explicit “we organize this section as …” meta narration
- no placeholders (
TODO, …, <!-- SCAFFOLD -->)
- Write
outline/transitions.md.
Role cards (use explicitly)
Linker (argument bridge)
Mission: write short, content-bearing transitions without narration.
Do:
- Restate what was established (one clause).
- Name the remaining tension/gap (one clause).
- Justify why the next unit follows (one clause).
Avoid:
- Title narration ("From X to Y") and slide navigation ("Now we turn").
- Semicolon planning notes or meta commentary.
Skeptic (template killer)
Mission: delete anything that reads like construction notes.
Do:
- Remove generic transitions that could fit any subsection.
- Force subsection-specific nouns from titles/RQs/bridge terms.
Avoid:
- Smuggling new facts into transitions.
Script (generator + validation)
You usually do not run this manually; it exists so a pipeline runner can deterministically generate and validate the artifact.
Quick Start
uv run python .codex/skills/transition-weaver/scripts/run.py --workspace <workspace>
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; default validates outline/transitions.md)--checkpoint <C#>: checkpoint id (optional; for logs)
Examples
- Validate after you write
outline/transitions.md:
uv run python .codex/skills/transition-weaver/scripts/run.py --workspace <workspace>
Troubleshooting
Issue: transitions read like templates
Fix:
- Ensure subsection briefs include subsection-specific bridge signals (
bridge_terms / contrast_hook).
- Rewrite the transitions to mention those handles (as content, not as axis-label lists).
Note: insertion is explicit
By default, section-merger does not insert generated transitions. Create
outline/transitions.insert_h3.ok for within-chapter H3 transitions or
outline/transitions.insert_h2.ok for between-H2 transitions, then run the
post-merge voice gate.
