outline-builder

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

Convert a taxonomy (`outline/taxonomy.yml`) into a bullet-only outline (`outline/outline.yml`) with sections/subsections. **Trigger**: outline builder, bullet outline, outline.yml, 大纲生成, bullets-only. **Use when**: structure 阶段（NO PROSE），已有 taxonomy，需要生成可映射/可写作的章节与小节骨架（每小节≥3 bullets）。 **Skip if**: 已经有批准过且可映射的 outline（避免无意义 churn）。 **Network**: none. **Guardrail**: bullets-only；移除 TODO/模板语句；每小节至少 3 个可检查 bullets。

2installs

Sourcewilloscar/research-units-pipeline-skills

Added on2026-02-16

NPX Install

npx skill4agent add willoscar/research-units-pipeline-skills outline-builder

SKILL.md Content

View Translation Comparison →

Outline Builder

Convert a taxonomy into a checkable, mappable outline (bullets only).

Bullets should describe what the section must cover, not draft prose.

Role cards (prompt-level guidance)

Use these roles explicitly while drafting the outline. They guide decisions, not phrasing; avoid producing copyable prose sentences.

Outline Architect
- Mission: design a paper-like ToC (few, thick chapters) that a reader would expect.
- Do: budget H2/H3 counts; ensure each H3 is writeable (has a real comparison lens + evaluation angle).
- Avoid: H3 explosion (many tiny buckets) and generic axis lists repeated everywhere.
Writer Proxy
- Mission: simulate the downstream writer and ask: “Could I draft this H3 without guessing?”
- Do: make each H3’s bullets encode tension + contrasts + evaluation anchors + failure modes.
- Avoid: bullets that sound like narration (“This subsection…”) or slide transitions (“Next, we…”).
Scope Guardian
- Mission: prevent silent scope drift.
- Do: make in/out scope cues explicit in bullets (especially for boundaries like single-agent vs multi-agent, tool use vs RAG, etc.).
- Avoid: leaving scope implicit and hoping the writer fixes it in prose.

When to use

You have a taxonomy and need an outline for mapping papers and building evidence.
You want each subsection to have concrete “coverage requirements” (axes, comparisons, evaluation).

When not to use

You already have an approved outline (don’t rewrite for style).

Input

```
outline/taxonomy.yml
```

Optional style references (paper-like section sizing):

```
ref/agent-surveys/STYLE_REPORT.md
```
```
ref/agent-surveys/text/
```

Output

```
outline/outline.yml
```

Workflow (heuristic)

Uses:

outline/taxonomy.yml

.

Optional style calibration (recommended for paper-like structure):

Read
```
ref/agent-surveys/STYLE_REPORT.md
```
to sanity-check top-level section counts and typical subsection sizing.
Skim 1–2 examples under
```
ref/agent-surveys/text/
```
to imitate structure (not wording).
- Target final ToC: ~6–8 H2 sections.
- Note: this pipeline appends
```
Discussion
```
  +
```
Conclusion
```
  as global sections in C5 merge, so keep the outline itself <=6 H2 sections (often 5–6 including Intro+Related).

Translate taxonomy nodes into section headings that read like a survey structure.
For each H3 subsection, write bullets using the Stage A contract (verifiable, no prose paragraphs).
- Minimum required bullets (first 4):
  - Intent:
    what the reader should learn (subsection-specific).
  - RQ:
    the question this subsection answers (1 line).
  - Evidence needs:
    what kinds of evidence must appear later (benchmarks/metrics/protocols/failure modes).
  - Expected cites:
    expected cite density / cite types (avoid placeholders like TBD/TODO).
- Then add 2–6 subsection-specific bullets (comparisons/axes/eval anchors/failure modes).
For each subsection, ensure bullets are:
- topic-specific (names of mechanisms, tasks, benchmarks, failure modes)
- checkable (someone can verify whether the subsection covered it)
- useful for mapping (papers can be assigned to each bullet/axis)
Prefer bullets that force synthesis later:
- “Compare X vs Y along axes A/B/C”
- “What evaluation setups are standard, and what they miss”
- “Where methods fail (latency, tool errors, jailbreaks, reward hacking…)”

Quality checklist

```
outline/outline.yml
```
exists and is bullets-only (no paragraphs).
Every subsection has the Stage A bullets:
```
Intent:
```
/
```
RQ:
```
/
```
Evidence needs:
```
/
```
Expected cites:
```
.
Every subsection has ≥3 additional non-generic bullets after the Stage A fields.
Bullets are not copy-pasted templates across subsections.

Common failure modes (and fixes)

Template bullets everywhere → replace with domain terms + evaluation axes specific to that subsection.
Bullets too vague (“Discuss limitations”) → name which limitations and how to test them.
Outline too flat/too deep → aim for a paper-like ToC (final ~6–8 H2) with fewer, thicker H3s.
Too many H3 subsections → merge adjacent H3s and write fewer, thicker subsections (paper-like default; budget depends on queries.md draft_profile: survey<=10, deep<=12).
Missing Stage A fields → add
```
Intent/RQ/Evidence needs/Expected cites
```
bullets so later mapping/evidence drafting can be audited.

Helper script (optional)

Quick Start

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

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

All Options

See
```
--help
```
(this helper is intentionally minimal)

Examples

Generate a baseline bullets-only outline, then refine bullets:
- Run the helper once, then replace every generic bullet /
```
TODO
```
  with topic-specific, checkable bullets.

Notes

The script generates a baseline bullets-only outline and never overwrites non-placeholder work.
Paper-like default: it inserts
```
Introduction
```
and
```
Related Work
```
as fixed H2 sections before taxonomy-driven chapters.
In
```
pipeline.py --strict
```
it will be blocked only if placeholder markers (TODO/TBD/FIXME/(placeholder)) remain.

Refinement marker (recommended; completion signal)

When you are satisfied with the outline (and after C2 approval if applicable), create:

```
outline/outline.refined.ok
```

This is an explicit "I reviewed/refined this" signal:

makes it harder for a scaffold-y outline to silently pass in strict runs
documents that bullets were rewritten into subsection-specific, checkable requirements

Troubleshooting

Common Issues

Issue: Outline still has

TODO

/ scaffold bullets

Symptom:

Quality gate blocks
```
outline_scaffold
```
.

Causes:

Helper script generated a scaffold; bullets were not rewritten.

Solutions:

Replace every generic bullet with topic-specific, checkable bullets (axes, comparisons, evaluation setups, failure modes).
Keep bullets-only (no prose paragraphs).

Issue: Outline bullets are mostly generic templates