outline-refiner_skill

Overview

This skill runs a deterministic planner pass that audits an outline and its mapping, producing a coverage report and a run-state record. It flags low evidence per subsection, reuse hotspots, scaffold-y axes, and structural mismatch with a target ToC budget. The outputs are machine-verifiable artifacts, not prose.

How this skill works

It parses outline/outline.yml to enumerate H2/H3 structure and uses outline/mapping.tsv to compute per-H3 coverage and paper reuse statistics. Optional inputs (paper notes, subsection briefs, budget report, GOAL.md) are ingested to add evidence-level, axis-specificity, and change-log context. The skill writes outline/coverage_report.md (bullet diagnostics and small tables only) and appends a JSONL record to outline/outline_state.jsonl.

When to use it

• After section-mapper produced outline/outline.yml and outline/mapping.tsv
• Before starting draft writing to confirm mapped evidence is sufficient
• When you need a verifiable, NO-PROSE planner pass that guides structural edits
• When you suspect repeated reuse of a small set of papers across subsections
• When you want an auditable run history of outline refinement

Best practices

• Provide optional inputs when available: papers/paper_notes.jsonl and outline/subsection_briefs.jsonl to enable richer diagnostics
• Keep the final ToC target in mind (≈6–8 H2); use the report to merge or split sections accordingly
• Treat the report as prescriptive bullets only—do not expect narrative prose or invented citations
• Respect the freeze policy: if outline/coverage_report.refined.ok exists, rerun only after intentional unfreeze
• Run the skill iteratively after mapping updates to track coverage changes over time

Example use cases

• Detect H3s with zero or single-paper coverage and list actions (map more evidence, merge, or drop)
• Identify reuse hotspots where the same papers are mapped to many H3s and suggest diversification actions
• Flag generic subsection axes (scaffold-y) and propose axis-specific rewrites as bullet items
• Compare current structure to OUTLINE_BUDGET_REPORT.md to explain recent merges and recommend further consolidation
• Produce an append-only outline/outline_state.jsonl entry for CI auditing and reproducibility