section-merger_skill

Overview

This skill deterministically merges per-section markdown files from sections/ into a single output/DRAFT.md, preserving the outline order and injecting handoff text from outline/transitions.md. It produces a merge report and an optional appendix of tables, without rewriting or inventing prose. Use it to assemble a reviewable draft for polishing, conversion to LaTeX, or submission preparation.

How this skill works

The merger reads outline/outline.yml to determine chapter and subsection order, then concatenates the corresponding files under sections/ in that order. It injects transitions from outline/transitions.md following a strict format contract and appends outline/tables_appendix.md under a unified Appendix heading unless opted out. The tool is deterministic: it never alters original section text or adds facts, and it emits output/DRAFT.md plus output/MERGE_REPORT.md describing any issues.

When to use it

• You have finished per-section prose in sections/ and need a single draft file for review.
• You need a deterministic, auditable assembly step before polishing voice or citations.
• You want to append reader-facing appendix tables produced by the table-writer.
• You are preparing a draft for LaTeX conversion, submission, or collaborator review.

Best practices

• Ensure sections/ contains final prose (no scaffolding markers) before merging; fix via subsection-writer if needed.
• Keep outline/outline.yml authoritative for ordering; changing it controls merge order deterministically.
• Follow the transitions format (e.g., '- 3.1 -> 3.2: text') and run post-merge voice gating rather than editing the merged draft.
• Opt into H2 transitions by creating outline/transitions.insert_h2.ok; opt out of tables by creating outline/tables.insert.off.
• Verify outline/tables_appendix.md contains real, publishable tables (>=2) when using the appendix insertion.

Example use cases

• Assemble a multi-author paper draft from per-section contributions for a unified review pass.
• Produce a single DRAFT.md for conversion to LaTeX or PDF tooling downstream.
• Insert curated handoffs between subsections to improve narrative flow without changing section text.
• Generate an audit-friendly build step that guarantees reproducible draft assembly.