section-merger

Original：🇺🇸 English

Translated

1 scripts

Deterministically merge per-section files under `sections/` into `output/DRAFT.md`, preserving outline order and weaving transitions from `outline/transitions.md`. **Trigger**: merge sections, merge draft, combine section files, sections/ -> output/DRAFT.md, 合并小节, 拼接草稿. **Use when**: you have per-unit prose files under `sections/` and want a single `output/DRAFT.md` for polishing/review/LaTeX. **Skip if**: section files are missing or still contain scaffolding markers (fix `subsection-writer` first). **Network**: none. **Guardrail**: deterministic merge only (no new facts/citations); preserve section order from `outline/outline.yml`.

1installs

Sourcewilloscar/research-units-pipeline-skills

Added on2026-02-09

NPX Install

npx skill4agent add willoscar/research-units-pipeline-skills section-merger

SKILL.md Content

View Translation Comparison →

Section Merger

Goal: assemble a paper-like

output/DRAFT.md

from:

```
sections/
```
(per-section/per-subsection prose)
```
outline/transitions.md
```
(short hand-offs; generated by
```
transition-weaver
```
)

outline/tables_appendix.md

(reader-facing Appendix tables; generated by

appendix-table-writer

)

Merge order is driven by

outline/outline.yml

. The draft title is taken from

GOAL.md

when present.

sections/sections_manifest.jsonl

is an optional diagnostics input.

This skill is deterministic: it does not rewrite content or invent prose; it only merges already-generated artifacts.

Transitions (injected text)

By default,
```
section-merger
```
inserts only within-chapter H3->H3 transitions.
Optional: if you want between-H2 transitions inserted too, create
```
outline/transitions.insert_h2.ok
```
in the workspace.
Format contract: only lines matching
```
- 3.1 -> 3.2: <text>
```
are injected by default.
Compatibility:
```
→
```
is accepted, but
```
->
```
is the preferred contract (avoids control-character encoding issues).
Treat transitions as injected draft text: run
```
post-merge-voice-gate
```
after merging, and route fixes back to
```
outline/transitions.md
```
(do not patch the merged draft).

Tables (two layers)

This pipeline uses two table layers:

```
outline/tables_index.md
```
(internal index; produced by
```
table-filler
```
)
- planning/debugging artifact
- should NOT be inserted into the paper
```
outline/tables_appendix.md
```
(reader-facing Appendix tables; produced by
```
appendix-table-writer
```
)
- publishable tables (clean layout + high information density)
- inserted by
```
section-merger
```
  under a single Appendix heading

Appendix insertion behavior

section-merger

inserts

outline/tables_appendix.md

at the end of the draft under

## Appendix: Tables

.

The inserted block is heading-free (any accidental
```
#
```
headings inside the tables file are stripped).
Opt-out (rare): create
```
outline/tables.insert.off
```
in the workspace.

Inputs

```
outline/outline.yml
```
(drives section/subsection order)
```
outline/transitions.md
```
(required)
```
sections/sections_manifest.jsonl
```
(optional diagnostics)
```
GOAL.md
```
(optional title)

For arxiv-survey pipelines (default contract):

```
outline/tables_appendix.md
```
(required unless opted out)

Outputs

```
output/DRAFT.md
```
```
output/MERGE_REPORT.md
```

Script

Quick Start

python .codex/skills/section-merger/scripts/run.py --help

python .codex/skills/section-merger/scripts/run.py --workspace workspaces/<ws>

All Options

```
--workspace <workspace_dir>
```
(required)
```
--unit-id <id>
```
(optional; used only for runner bookkeeping)
```
--inputs <a;b;c>
```
(optional; override inputs; defaults are profile-aware)

--outputs <draft_rel;report_rel>

(optional; defaults to

output/DRAFT.md;output/MERGE_REPORT.md

)

```
--checkpoint <C#>
```
(optional; ignored by the merger)

Examples

Merge with defaults (profile-aware table insertion):

python .codex/skills/section-merger/scripts/run.py --workspace workspaces/<ws>

Merge with explicit outputs:

python .codex/skills/section-merger/scripts/run.py --workspace workspaces/<ws> --outputs output/DRAFT.md;output/MERGE_REPORT.md

Troubleshooting

Issue: merge report says a subsection file is missing

Likely cause:

A required
```
sections/*.md
```
file has not been written yet.

Fix:

Write the missing units under
```
sections/
```
(typically via
```
subsection-writer
```
) and rerun merge.

Issue: Appendix tables are missing in the merged draft