Back to Details

outline-refiner

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Outline Refiner (Planner pass, NO PROSE)

大纲优化器（Planner pass，禁止生成正文内容）

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.
目标：通过添加一个明确的planner阶段，让大纲具备可审计性，该阶段需回答以下问题：
  • 每个H3小节是否有足够的映射证据？
  • 是否存在少数论文被反复复用的情况？
  • 子小节的维度是否仍过于通用/框架化？
  • 该大纲是否可能生成类论文的结构（最终目录预算：约6–8个H2；更少、更详实的H3）？
这是一个确定性的“planner”单元：不得撰写调研类正文内容。

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)
必填：
  • outline/outline.yml
  • outline/mapping.tsv
可选（尽最大努力诊断；在流程早期可能缺失）：
  • outline/OUTLINE_BUDGET_REPORT.md
    （若存在：解释近期的合并操作；有助于解读映射/覆盖率变化）
  • papers/paper_notes.jsonl
    （用于证据级别判断）
  • outline/subsection_briefs.jsonl
    （用于维度特异性判断）
  • GOAL.md
    （用于提示明显的范围偏离）

Outputs

输出项

  • outline/coverage_report.md
    (bullets + small tables; NO PROSE)
  • outline/outline_state.jsonl
    (append-only JSONL; one record per run)
  • outline/coverage_report.md
    （项目符号+小型表格；无正文内容）
  • outline/outline_state.jsonl
    （追加式JSONL文件；每次运行生成一条记录）

Workflow (planner pass, NO PROSE)

工作流（Planner pass，禁止生成正文内容）

  1. 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.
  2. Read 
    outline/mapping.tsv
    and compute per-H3 coverage and reuse hotspots.
  3. If 
    papers/paper_notes.jsonl
    exists, summarize evidence levels (fulltext/abstract/title) for mapped papers.
  4. If 
    outline/subsection_briefs.jsonl
    exists, compute axis specificity (generic vs specific axes) per H3.
  5. Optionally use 
    GOAL.md
    to flag obvious scope drift (keywords not reflected in outline).
  6. Write 
    outline/coverage_report.md
    and append a run record to 
    outline/outline_state.jsonl
    .
  1. 解析
    outline/outline.yml
    ，枚举H2章节 + H3子小节（章节规模/预算）。
    • 若
      outline/OUTLINE_BUDGET_REPORT.md
      存在，将其作为合并/变更日志，以便覆盖率报告能解释结构变更的原因。
  2. 读取
    outline/mapping.tsv
    ，计算每个H3小节的覆盖率和复用热点。
  3. 若
    papers/paper_notes.jsonl
    存在，汇总已映射论文的证据级别（全文/摘要/标题）。
  4. 若
    outline/subsection_briefs.jsonl
    存在，计算每个H3小节的维度特异性（通用维度vs特定维度）。
  5. 可选：使用
    GOAL.md
    标记明显的范围偏离（大纲中未体现的关键词）。
  6. 生成
    outline/coverage_report.md
    并向
    outline/outline_state.jsonl
    追加一条运行记录。

Freeze policy

冻结策略

  • If 
    outline/coverage_report.refined.ok
    exists, the script will not overwrite 
    outline/coverage_report.md
    .
  • 若
    outline/coverage_report.refined.ok
    文件存在，脚本将不会覆盖
    outline/coverage_report.md
    。

Script

脚本

Quick Start

快速开始

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

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)
  • --workspace <dir>
    ：工作区根目录
  • --unit-id <U###>
    ：单元ID（可选；用于日志）
  • --inputs <semicolon-separated>
    ：覆盖输入项（罕见；优先使用默认值）
  • --outputs <semicolon-separated>
    ：覆盖输出项（罕见；优先使用默认值）
  • --checkpoint <C#>
    ：检查点ID（可选；用于日志）

Examples

示例

  • Planner-pass diagnostics after 
    section-mapper
    : 
    • python .codex/skills/outline-refiner/scripts/run.py --workspace workspaces/<ws>
  • 在
    section-mapper
    之后执行Planner-pass诊断： 
    • python .codex/skills/outline-refiner/scripts/run.py --workspace workspaces/<ws>

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
    .
原因：
  • 可选输入项缺失（无
    papers/paper_notes.jsonl
    和/或无
    outline/subsection_briefs.jsonl
    ）。
解决方法：
  • 运行
    paper-notes
    和/或
    subsection-briefs
    ，然后重新运行
    outline-refiner
    。