AI agent skill · by @WILLOSCAR

Section Merger

Deterministically merge the final fingerprinted section snapshot into `output/DRAFT.md`, preserving outline order and inserting transitions only when explicitly enabled.

Archived 2026-10-23 · Source updated 2026-10-05. Check the original repository for the latest version.

SKILL.md instructions

# Section Merger

## Triggers & routing

- **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.


Goal: assemble a paper-like `output/DRAFT.md` from:
- `sections/` (per-section/per-subsection prose)
- `outline/transitions.md` (optional hand-off suggestions; 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 derived from
`GOAL.md` when present. When `sections/sections_manifest.jsonl` is supplied by
the Pipeline contract, every merged section must match its recorded bytes and
SHA-256 hash.

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

## Transitions (explicit opt-in)

- By default, generated transitions are not inserted.
- To insert H3 transitions, create `outline/transitions.insert_h3.ok`.
- To insert H2 transitions, create `outline/transitions.insert_h2.ok`.
- Format contract: H3 entries use `- 3.1 -> 3.2: <text>`.
- 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` (required by the executable survey Pipeline; freshness gate)
- `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

- `uv run python .codex/skills/section-merger/scripts/run.py --help`
- `uv run python .codex/skills/section-merger/scripts/run.py --workspace <workspace>`

### All Options

- `--workspace <workspace>` (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):

  `uv run python .codex/skills/section-merger/scripts/run.py --workspace <workspace>`

- Merge with explicit outputs:

  `uv run python .codex/skills/section-merger/scripts/run.py --workspace <workspace> --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

Fix:
- Ensure `outline/tables_appendix.md` exists and contains the profile minimum
  (course paper: >=1; survey/deep: >=2) with no placeholders.
- Ensure you did not create `outline/tables.insert.off`.
- Rerun `section-merger`.