Outline Refiner

Outline Refiner (Planner pass, NO PROSE)

Goal: make the outline *auditable* by adding an explicit planner stage that answers:

• Do we have enough mapped evidence per H3?
• Are the same few papers reused everywhere?
• Are subsection axes still generic/scaffold-y?
• Is the outline likely to produce a paper-like structure (final ToC budget: ~6–8 H2; fewer, thicker H3s)?

This is a deterministic “planner” unit: it must not write survey prose.

Inputs

Required:

• outline/outline.yml
• outline/mapping.tsv

Optional (best-effort diagnosis; may be missing early in the pipeline):

• outline/OUTLINE_BUDGET_REPORT.md (if present: explains recent merges; helps interpret mapping/coverage changes)
• papers/paper_notes.jsonl (for evidence levels)
• outline/subsection_briefs.jsonl (for axis specificity)
• GOAL.md (for scope drift hints)

Outputs

• outline/coverage_report.md (bullets + small tables; NO PROSE)
• outline/outline_state.jsonl (append-only JSONL; one record per run)

Workflow (planner pass, NO PROSE)

• Parse outline/outline.yml to enumerate H2 sections + H3 subsections (section sizing / budget).
• If outline/OUTLINE_BUDGET_REPORT.md exists, use it as the merge/change log so the coverage report can explain *why* structure changed.
• Read outline/mapping.tsv and compute per-H3 coverage and reuse hotspots.
• If papers/paper_notes.jsonl exists, summarize evidence levels (fulltext/abstract/title) for mapped papers.
• If outline/subsection_briefs.jsonl exists, compute axis specificity (generic vs specific axes) per H3.
• Optionally use GOAL.md to flag obvious scope drift (keywords not reflected in outline).
• Write outline/coverage_report.md and append a run record to outline/outline_state.jsonl.

Freeze policy

• If outline/coverage_report.refined.ok exists, the script will not overwrite outline/coverage_report.md.

Script

Quick Start

• uv run python .codex/skills/outline-refiner/scripts/run.py --help
• uv run python .codex/skills/outline-refiner/scripts/run.py --workspace <workspace>

All Options

• --workspace <dir>: workspace root
• --unit-id <U###>: unit id (optional; for logs)
• --inputs <semicolon-separated>: override inputs (rare; prefer defaults)
• --outputs <semicolon-separated>: override outputs (rare; prefer defaults)
• --checkpoint <C#>: checkpoint id (optional; for logs)

Examples

• Planner-pass diagnostics after section-mapper:
• uv run python .codex/skills/outline-refiner/scripts/run.py --workspace <workspace>

Troubleshooting

Issue: report is missing evidence-level or axis-specificity columns

Cause:

• Optional inputs are missing (no papers/paper_notes.jsonl and/or no outline/subsection_briefs.jsonl).

Fix:

• Run paper-notes and/or subsection-briefs, then rerun outline-refiner.