survey-visuals

Original source / Raw 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`.