Outline Builder

Build outline/outline.yml from either:

• outline/taxonomy.yml (legacy H3-first compatibility path)

• outline/chapter_skeleton.yml

• outline/section_briefs.jsonl (section-first transition path)

Compatibility mode is active: this migration keeps the current output contract while moving intro/related defaults, Stage A bullet templates, and domain-specific comparison framing into references/ and assets/ .

Load Order

Always read:

• references/overview.md

• references/stage_a_contract.md

Read by task:

• references/intro_related_patterns.md when changing Introduction / Related Work defaults

• references/examples_good.md and references/examples_bad.md for bullet calibration

Machine-readable asset:

• assets/outline_defaults.yaml

Inputs

Required:

• outline/taxonomy.yml

Optional human calibration only:

• ref/agent-surveys/STYLE_REPORT.md

• ref/agent-surveys/text/

Output

Keep the current output contract:

• outline/outline.yml

Compatibility mode

Current mode is reference-first with script compatibility:

• front-chapter defaults live in assets/outline_defaults.yaml

• Stage A bullet defaults and comparison-axis packs live in assets/outline_defaults.yaml

• examples and boundary rules live in references/

• scripts/run.py still owns outline materialization, section-first input selection, and placeholder-safe overwrite behavior

Script boundary

Use scripts/run.py only for:

• loading taxonomy or section-first structure inputs plus the defaults asset

• rendering the outline skeleton deterministically

• preserving existing non-placeholder outlines

• choosing comparison-axis packs from machine-readable defaults

Do not treat the script as the main place for:

• domain framing for Introduction / Related Work

• long bullet banks or writing exemplars

• prompt-heavy guidance about how a good outline should read

Output shape rules

Keep these stable:

• outline/outline.yml is a YAML list

• Introduction and Related Work remain the first two H2 sections

• each H3 subsection contains the Stage A bullets: Intent: / RQ: / Evidence needs: / Expected cites:

• each H3 subsection adds several topic-specific bullets after the Stage A fields

• the helper never overwrites non-placeholder user work

Quick Start

• python .codex/skills/outline-builder/scripts/run.py --help

• python .codex/skills/outline-builder/scripts/run.py --workspace <workspace_dir>

Execution notes

When running this skill in compatibility mode, scripts/run.py currently reads:

• outline/taxonomy.yml , or

• outline/chapter_skeleton.yml

• outline/section_briefs.jsonl

• assets/outline_defaults.yaml

The optional style references under ref/agent-surveys/ are for human calibration only:

• use ref/agent-surveys/STYLE_REPORT.md to sanity-check chapter counts / thickness

• skim ref/agent-surveys/text/ only to calibrate structure rather than wording

Script

Quick Start

• python .codex/skills/outline-builder/scripts/run.py --workspace <workspace_dir>

All Options

• --workspace <dir>

• --unit-id <id>

• --inputs <path1;path2>

• --outputs <path1;path2>

• --checkpoint <C*>

Examples

• python .codex/skills/outline-builder/scripts/run.py --workspace workspaces/<ws>

Troubleshooting

• If Related Work still carries domain-specific framing, patch assets/outline_defaults.yaml before changing Python.

• If subsection bullets feel generic, review references/stage_a_contract.md and references/examples_good.md .

• If the outline is structurally valid but too fragmented, reroute to outline-budgeter rather than expanding this script.