transition-weaver_skill

Overview

This skill generates concise, content-bearing transition sentences that weave adjacent subsections into a coherent narrative without introducing new facts. It produces an outline/transitions.md file formatted for automatic insertion so merged drafts avoid isolated “island” subsections. The output follows a strict injection contract and guards against planner-talk or generic templates.

How this skill works

The skill reads outline/outline.yml for adjacency and subsection_briefs.jsonl for RQs, bridge_terms, and contrast_hook handles. For each H3->H3 boundary it writes one short transition sentence that restates what the prior unit established, names the remaining tension, and justifies why the next unit follows. It validates format and guardrails so transitions are safe to inject directly into output/DRAFT.md.

When to use it

• When outline/subsection_briefs.jsonl exists and you want coherent flow before or after drafting (typically Stage C5)
• Before running section-merger to ensure inserted prose is content-bearing and paper-ready
• When subsections read like isolated islands and need light argumentative linking
• When bridge handles (rq, bridge_terms, contrast_hook) are available in briefs

Best practices

• Keep each transition to one concise sentence that could appear in the draft as-is
• Reuse only titles, research questions, and bridge_terms present in subsection_briefs.jsonl — do not introduce new facts
• Avoid planner language and navigation phrases; write argument bridges instead of meta notes
• Prefer specific nouns from the briefs to avoid generic, re-usable templates
• Validate transitions with the included script to ensure arrow-format lines match injection rules

Example use cases

• Linking a methods subsection that establishes experimental assumptions to an evaluation subsection that explores limitations using the same bridge_terms
• Bridging a background subsection that outlines related work to a contrast subsection that highlights a remaining gap named in contrast_hook
• Connecting a subsection that reports empirical patterns to a following subsection that interprets those patterns under a stated RQ
• Weaving transitions between technical subcomponents so the merged draft reads like a single argument