survey-visuals

WILLOSCAR 的头像作者 WILLOSCAR

为一项调查起草非散文视觉工件(表格、时间线、图形规格),以证据为基础,并使用来自“引用/ref.bib”的引文键。**触发器**:调查视觉效果、表格、时间线、图形、视觉效果、图表、时间线、图形规格。**使用时间**:调查的 C4(无散文),现有大纲 + 声明/证据 +引用,先把对比表/放置时间线/图规格落盘。**跳过如果**:缺少引用`s/ref.bib`(或证据不够完善,导致表格只能写空洞模板)。**网络**:无。**Guardrail**:不需要PROSE;表格/时间线/图规格必须具体且可核对(含引用),禁止继承TODO/SCAFFOLD。

📖 中文导读:为一项调查起草非散文视觉工件(表格、时间线、图形规格),以证据为基础,并使用来自“引用/ref.bib”的引文键。**触发器**:调查视觉效果、表格、时间线、图形、视觉效果、图表、时间线、图形规格。**使用时间**:调查的 C4(无散文),现有大纲 + 声明/证据 +引用,先把对比表/放置时间线/图规格落盘。**跳过如果**:缺少引用`s/ref.bib`(或证据不够完善,导致表格只能写空洞模板)。**网络**:无。**Guardrail**:不需要PROSE;表格/时间线/图规格必须具体且可核对(含引用),禁止继承TODO/SCAFFOLD。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: survey-visuals description: | Draft non-prose visuals artifacts (tables, timeline, figure specs) for a survey, grounded in evidence and using citation keys from citations/ref.bib. Trigger: survey visuals, tables, timeline, figures, visuals, 图表, 时间线, figure spec. Use when: survey 的 C4(NO PROSE),已有 outline + claim/evidence + citations,需要先把对比表/演化时间线/图规格落盘。 Skip if: 缺少 citations/ref.bib(或 evidence 还没整理到位,导致表格只能写空洞模板)。 Network: none. Guardrail: NO PROSE;表格/时间线/图规格必须具体且可核对(含 citations),禁止遗留 TODO/SCAFFOLD。

Survey Visuals (NO PROSE)

Create non-prose “visual thinking” artifacts that make the actual writing stage less template-y:

  • comparison tables (method + evaluation)
  • timeline / evolution bullets
  • figure specs (what to draw, why it matters, what papers support it)

Inputs

  • outline/outline.yml
  • outline/claim_evidence_matrix.md
  • papers/paper_notes.jsonl
  • citations/ref.bib

Outputs

  • outline/tables.md
  • outline/timeline.md
  • outline/figures.md

Workflow (heuristic)

Uses: outline/outline.yml, outline/claim_evidence_matrix.md.

  1. Read the outline + claim–evidence matrix and pick the comparison axes that recur across sections:
    • control loop / planner-executor split
    • tool interface & orchestration
    • memory / retrieval / reflection
    • environments & benchmarks
    • safety / security / alignment surfaces
  2. Tables (outline/tables.md):
    • Write ≥2 Markdown tables with real entries and citations.
    • Prefer one “method matrix” and one “evaluation/benchmark matrix”.
  3. Timeline (outline/timeline.md):
    • Write year → key milestone bullets (aim for breadth and citations).
  4. Figures (outline/figures.md):
    • Write 2–4 figure specs that a human could draw:
      • purpose (“what insight this figure communicates”)
      • required elements (boxes/arrows/axes)
      • what papers support each element (cite keys)
  5. Use only citation keys present in citations/ref.bib.

Quality checklist

  • No TODO and no <!-- SCAFFOLD ... --> markers remain in the outputs.
  • outline/tables.md contains ≥2 Markdown tables with real content and citations.
  • outline/timeline.md contains ≥8 year bullets and each bullet has ≥1 citation marker [@...].
  • outline/figures.md contains ≥2 figure specs and each mentions at least one supporting citation.

Helper script (optional)

Quick Start

  • python .codex/skills/survey-visuals/scripts/run.py --help
  • python .codex/skills/survey-visuals/scripts/run.py --workspace <workspace_dir>

All Options

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

Examples

  • Generate baseline visuals, then refine manually:
    • Run the helper once, then refine outline/tables.md, outline/timeline.md, outline/figures.md for better coverage/accuracy (without leaving placeholders).

Notes

  • The helper generates baseline visuals and never overwrites non-placeholder artifacts.
  • If papers/paper_notes.jsonl exists it will prefill candidate rows/bullets with paper_id + bibkey citation markers.
  • In pipeline.py --strict it will be blocked only if placeholder markers remain (and if minimum table/timeline/figure requirements are not met).

Troubleshooting

Common Issues

Issue: Visuals are still scaffolds (TODO/template)

Symptom:

  • Quality gate blocks survey-visuals outputs.

Causes:

  • Helper script generated scaffolds, but tables/timeline/figures were not rewritten.

Solutions:

  • Fill outline/tables.md with ≥2 real comparison tables (include citations in rows).
  • Fill outline/timeline.md with ≥8 dated milestones (each with citations).
  • Fill outline/figures.md with ≥2 figure specs (purpose/elements/citations).

Issue: Missing citation keys

Symptom:

  • You can’t cite in visuals (no [@Key]).

Causes:

  • citations/ref.bib not generated yet, or notes have no bibkey.

Solutions:

  • Run citation-verifier and ensure papers/paper_notes.jsonl includes bibkey.

Recovery Checklist

  • No TODO/scaffold markers remain in visuals artifacts.
  • Tables/timeline/figures contain citations from citations/ref.bib.