survey-visuals
为一项调查起草非散文视觉工件(表格、时间线、图形规格),以证据为基础,并使用来自“引用/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.ymloutline/claim_evidence_matrix.mdpapers/paper_notes.jsonlcitations/ref.bib
Outputs
outline/tables.mdoutline/timeline.mdoutline/figures.md
Workflow (heuristic)
Uses: outline/outline.yml, outline/claim_evidence_matrix.md.
- 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
- Tables (
outline/tables.md):- Write ≥2 Markdown tables with real entries and citations.
- Prefer one “method matrix” and one “evaluation/benchmark matrix”.
- Timeline (
outline/timeline.md):- Write year → key milestone bullets (aim for breadth and citations).
- 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)
- Write 2–4 figure specs that a human could draw:
- Use only citation keys present in
citations/ref.bib.
Quality checklist
- No
TODOand no<!-- SCAFFOLD ... -->markers remain in the outputs. -
outline/tables.mdcontains ≥2 Markdown tables with real content and citations. -
outline/timeline.mdcontains ≥8 year bullets and each bullet has ≥1 citation marker[@...]. -
outline/figures.mdcontains ≥2 figure specs and each mentions at least one supporting citation.
Helper script (optional)
Quick Start
python .codex/skills/survey-visuals/scripts/run.py --helppython .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.mdfor better coverage/accuracy (without leaving placeholders).
- Run the helper once, then refine
Notes
- The helper generates baseline visuals and never overwrites non-placeholder artifacts.
- If
papers/paper_notes.jsonlexists it will prefill candidate rows/bullets withpaper_id+bibkeycitation markers. - In
pipeline.py --strictit 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-visualsoutputs.
Causes:
- Helper script generated scaffolds, but tables/timeline/figures were not rewritten.
Solutions:
- Fill
outline/tables.mdwith ≥2 real comparison tables (include citations in rows). - Fill
outline/timeline.mdwith ≥8 dated milestones (each with citations). - Fill
outline/figures.mdwith ≥2 figure specs (purpose/elements/citations).
Issue: Missing citation keys
Symptom:
- You can’t cite in visuals (no
[@Key]).
Causes:
citations/ref.bibnot generated yet, or notes have nobibkey.
Solutions:
- Run
citation-verifierand ensurepapers/paper_notes.jsonlincludesbibkey.
Recovery Checklist
- No
TODO/scaffold markers remain in visuals artifacts. - Tables/timeline/figures contain citations from
citations/ref.bib.