outline-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

在起草大纲时需明确遵循这些角色要求。它们用于指导决策，而非措辞；避免生成可直接复制的完整句子。

大纲架构师
- 目标：设计类似论文的目录结构（章节数量少、内容充实），符合读者预期。
- 执行：合理规划H2/H3章节数量；确保每个H3章节具备可写性（包含明确的对比维度和评估角度）。
- 避免：H3章节泛滥（过多细碎分类）以及在各处重复通用维度列表。
写手代理
- 目标：模拟后续写手的视角，自问：“我能否无需猜测就能起草这个H3章节？”
- 执行：让每个H3章节的项目符号包含冲突点、对比项、评估锚点和失效模式。
- 避免：项目符号采用叙述式表述（如“本小节将…”）或幻灯片过渡式表述（如“接下来，我们…”）。
范围守护者
- 目标：防止范围悄然偏离。
- 执行：在项目符号中明确标注范围边界（尤其是单Agent与多Agent、工具使用与RAG等边界）。
- 避免：让范围隐含其中，寄希望于写手在正文中自行修正。

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/
```

```
outline/taxonomy.yml
```

可选的风格参考（类论文章节规模）：

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

Output

输出

```
outline/outline.yml
```

```
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…)”

使用文件：

outline/taxonomy.yml

。

可选的风格校准（推荐用于类论文结构）：

阅读
```
ref/agent-surveys/STYLE_REPORT.md
```
，对顶级章节数量和典型小节规模进行合理性检查。
浏览
```
ref/agent-surveys/text/
```
下的1-2个示例，模仿其结构（而非措辞）。
- 目标最终目录：约6-8个H2章节。
- 注意：该流水线会在C5合并阶段自动添加
```
Discussion
```
  和
```
Conclusion
```
  作为全局章节，因此大纲本身的H2章节数量需控制在≤6个（通常包含引言和相关工作在内共5-6个）。

将分类体系节点转换为符合综述结构的章节标题。
针对每个H3小节，按照Stage A约定编写项目符号（可验证，无正文段落）。
- 必备的核心项目符号（前4个）：
  - ```
  Intent:
```
  读者应从本小节学到的内容（针对小节定制）。
- ```
RQ:
```
    本小节要解答的问题（单行）。
  - ```
  Evidence needs:
```
  后续必须包含的证据类型（基准测试/指标/协议/失效模式）。
- ```
Expected cites:
```
    预期的引用密度/引用类型（避免使用TBD/TODO等占位符）。
- 然后添加2-6个小节专属的项目符号（对比项/维度/评估锚点/失效模式）。
针对每个小节，确保项目符号：
- 具备主题特异性（包含机制、任务、基准测试、失效模式的名称）
- 可检查（有人能验证该小节是否涵盖了对应内容）
- 便于映射（论文可分配到每个项目符号/维度）
优先选择能推动后续内容整合的项目符号：
- “沿A/B/C维度对比X与Y”
- “标准的评估设置有哪些，它们存在哪些遗漏”
- “方法在哪些场景下失效（延迟、工具错误、越狱、奖励黑客攻击…）”

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.

```
outline/outline.yml
```
已生成且仅包含项目符号（无段落）。
每个小节都包含Stage A核心项目符号：
```
Intent:
```
/
```
RQ:
```
/
```
Evidence needs:
```
/
```
Expected cites:
```
。
每个小节在Stage A核心字段后至少包含3个非通用项目符号。
项目符号未在各小节间复制模板内容。

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.

模板化项目符号泛滥 → 替换为该小节专属的领域术语和评估维度。
项目符号过于模糊（如“讨论局限性”）→ 明确指出具体哪些局限性以及如何测试这些局限性。
大纲结构过平或过深 → 目标为类论文目录（最终约6-8个H2章节），采用数量更少、内容更充实的H3章节。
H3小节数量过多 → 合并相邻的H3小节，编写数量更少、内容更充实的小节（类论文默认风格；数量上限取决于queries.md中的draft_profile：综述≤10，深度分析≤12）。
缺失Stage A核心字段 → 添加
```
Intent/RQ/Evidence needs/Expected cites
```
项目符号，以便后续的映射/证据起草工作可被审计。

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>

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)

查看
```
--help
```
（本辅助脚本设计得尽量简洁）

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.

生成基础的纯项目符号大纲，然后优化项目符号：
- 运行一次辅助脚本，然后将所有通用项目符号/
```
TODO
```
  替换为主题特异性、可检查的项目符号。

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.

该脚本仅生成基础的纯项目符号大纲，绝不会覆盖非占位符内容。
类论文默认设置：它会在分类体系驱动的章节前自动插入
```
Introduction
```
和
```
Related Work
```
作为固定H2章节。
在
```
pipeline.py --strict
```
模式下，若仍存在占位符标记（TODO/TBD/FIXME/(placeholder)），则会被拦截。

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

当你对大纲满意后（若适用，需在C2批准后），创建文件：

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

这是一个明确的“已审核/优化完成”信号：

可避免脚手架式大纲在严格模式下悄然通过
记录项目符号已被重写为小节专属、可检查的要求

Troubleshooting

故障排查

Common Issues

常见问题

Issue: Outline still has

TODO

/ scaffold bullets

问题：大纲仍包含

TODO

/脚手架式项目符号

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

症状：

质量检查环节拦截
```
outline_scaffold
```
。

原因：

辅助脚本生成了脚手架，但项目符号未被重写。

解决方案：

将所有通用项目符号替换为主题特异性、可检查的项目符号（维度、对比项、评估设置、失效模式）。
仅保留项目符号（无正文段落）。

Issue: Outline bullets are mostly generic templates

问题：大纲项目符号多为通用模板