Annotative Caption Visualization Lens
Philosophical Mode: Annotative
Primary Question: "Are figure captions and axis labels fully self-contained?"
Focus: Declarative titles (state the result, not "Figure N: Results"), axis labels with
units, error definition in legend (CI95 / std / SEM), baseline references cited in
caption, sample sizes disclosed per condition, venue-specific caption format
Arguments
/autoskillit:vis-lens-caption-annot [context_path] [experiment_plan_path]
- context_path (optional positional arg 1) — Absolute path to a lens context file
containing IV/DV tables, H0/H1 hypotheses, controlled variables, and success criteria.
If provided, read this file before beginning analysis to obtain structured context.
If omitted, discover context by exploring the CWD.
- experiment_plan_path (optional positional arg 2) — Absolute path to the full
experiment plan. If provided, read for complete experimental methodology and design.
If omitted, locate the experiment plan by exploring the CWD.
When to Use
- Auditing figure captions before paper submission
- Checking whether axis labels carry units and direction information
- Verifying error bars are defined in the legend or caption
- Ensuring baseline conditions are referenced explicitly
- Disclosing sample size per plotted condition
- User invokes
/autoskillit:vis-lens-caption-annot
Critical Constraints
NEVER:
- Modify any source code files
- Do not litter the codebase with useless comments, TODO markers, or explanatory annotations — the skill output and diagram speak for themselves
- Create files outside
{{AUTOSKILLIT_TEMP}}/vis-lens-caption-annot/
- Use a non-declarative title like "Results" or "Figure 3: Performance" — titles must state the takeaway (e.g., "Model A outperforms baseline on all benchmarks")
- Omit units from axis labels (e.g., write "Latency (ms)", not "Latency")
ALWAYS:
Check every figure title for declarative language
Verify every axis label carries a unit or categorical scale description
Confirm error bars / shaded regions are defined (CI95, ±1 std, IQR, etc.) in the legend or caption
Flag any figure that references a baseline without naming it explicitly
Report sample size per plotted condition (n=X seeds, N=X subjects, etc.)
BEFORE creating any diagram, LOAD the /autoskillit:mermaid skill using the Skill tool — this is MANDATORY
If the Skill tool cannot be used (disable-model-invocation) or refuses this invocation, do NOT proceed with diagram creation. Abort this step and omit the diagram from output.
Write output to {{AUTOSKILLIT_TEMP}}/vis-lens-caption-annot/vis_spec_caption_annot_{YYYY-MM-DD_HHMMSS}.md (relative to the current working directory)
After writing the file, emit the structured output token as literal plain text with no
markdown formatting on the token name (the adjudicator performs a regex match):
diagram_path = /absolute/path/to/{{AUTOSKILLIT_TEMP}}/vis-lens-caption-annot/vis_spec_caption_annot_{...}.md
Analysis Workflow
Step 0: Parse optional arguments
If positional arg 1 (context_path) is provided and the file exists, read it to obtain
IV/DV tables, H0/H1 hypotheses, controlled variables, and success criteria. If positional
arg 2 (experiment_plan_path) is provided and exists, read the experiment plan for full
methodology. Use this structured context as the foundation for Steps 1–4; skip the CWD
exploration for these fields if the context file supplies them.
Step 1: Inventory Figure Titles
For every figure in the experiment plan or codebase:
- Collect the current title string
- Classify: DECLARATIVE (states a result) vs DESCRIPTIVE (labels the figure)
- FAIL if title is purely descriptive (e.g. "Ablation Results", "Performance Comparison")
- PASS if title states the key finding (e.g. "Removing component X degrades accuracy by 8 pp")
Step 2: Axis Label and Unit Audit
For every axis in every figure:
- Confirm the label is present (no unlabeled axes)
- Confirm units are stated for continuous quantities: time (ms/s), memory (MB/GB), accuracy (%), loss (nats/bits), etc.
- Confirm categorical axes name the grouping variable
- FLAG WARNING for any axis missing a unit on a continuous quantity
Step 3: Error and Uncertainty Definition Audit
For every figure that shows error bars, shaded regions, or confidence intervals:
- Identify the error representation: CI (90/95/99%), ±1 std, ±1 SEM, IQR, min/max
- Verify the definition appears in the legend or caption text
- FLAG FAIL if error bars are shown but not defined
Step 4: Baseline and Sample Size Disclosure
- Identify every "baseline" referenced in a figure or caption
- Verify the baseline name and source are stated (e.g. "GPT-4 (OpenAI, 2023)")
- For each plotted group/condition, verify sample size n is disclosed (seeds, subjects, runs)
- FLAG WARNING for any undisclosed baseline or missing n
Step 5: Emit yaml:figure-spec Blocks
For each figure, emit one yaml:figure-spec fenced block with the annotations field
describing the caption audit result. Then LOAD /autoskillit:mermaid and create a diagram
showing: title audit → axis audit → error definition → baseline/n disclosure → verdict.
Output Template
# Annotative Caption Spec: {System / Experiment Name}
**Lens:** Annotative Caption (Annotative)
**Question:** Are figure captions and axis labels fully self-contained?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}
## Caption Audit Summary
| Figure | Declarative Title | Axis Units | Error Defined | Baseline Named | Sample n | Status |
|--------|-------------------|-----------|---------------|----------------|----------|--------|
| fig-01 | FAIL (descriptive) | PASS | PASS | N/A | PASS | FAIL |
| fig-02 | PASS | PASS | PASS | PASS | PASS | OK |
## Figure Specs
```yaml
# yaml:figure-spec — canonical schema (spec_version: "1.0")
figure_id: "fig-02-ablation-comparison"
figure_title: "Removing component X degrades accuracy by 8 pp"
spec_version: "1.0"
chart_type: "bar"
chart_type_fallback: "table"
perceptual_justification: "Grouped bar chart shows per-component contribution directly."
data_source: "results/ablation.csv"
data_mapping:
x: "variant"
y: "accuracy_delta_pp"
color: "component"
size: ""
facet: ""
layout:
width_inches: 5.0
height_inches: 3.5
dpi: 300
stat_overlay:
type: "error_bar"
measure: "CI95"
n_seeds: 5
annotations: ["Declarative title PASS; axis labels with units PASS; CI95 defined in legend PASS; n=5 seeds per condition PASS"]
anti_patterns: []
palette: "okabe-ito"
format: "pdf"
target_dpi: 300
library: "matplotlib"
report_section: "Section 5 Ablation"
priority: "P1"
placement_tier: "main"
conflicts: []
metadata:
created_by: "vis-lens-caption-annot"
reviewed_by: ""
last_updated: "{YYYY-MM-DD}"
Caption Annotation Diagram
%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
flowchart TB
%% CLASS DEFINITIONS %%
classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
subgraph Titles ["TITLE AUDIT"]
T1["title = {text}<br/>━━━━━━━━━━<br/>declarative: PASS / FAIL"]
end
subgraph Axes ["AXIS LABEL AUDIT"]
A1["x-axis: {label} ({unit})<br/>y-axis: {label} ({unit})<br/>━━━━━━━━━━<br/>units present: PASS / FAIL"]
end
subgraph Errors ["ERROR DEFINITION"]
E1["error type: {CI95/std/SEM}<br/>━━━━━━━━━━<br/>defined in legend: PASS / FAIL"]
end
subgraph Disclosure ["BASELINE & SAMPLE n"]
D1["baseline: {name}<br/>n per condition: {N}<br/>━━━━━━━━━━<br/>disclosed: PASS / FAIL"]
end
subgraph Verdict ["VERDICT"]
V1["{OK / WARNING / FAIL}<br/>━━━━━━━━━━<br/>{reason}"]
end
T1 --> A1
A1 --> E1
E1 --> D1
D1 --> V1
class T1 stateNode;
class A1 handler;
class E1 cli;
class D1 output;
class V1 detector;
Color Legend:
| Color |
Category |
Description |
| Dark Teal |
Title |
Declarative title audit |
| Orange |
Axes |
Axis label and unit audit |
| Dark Blue |
Error |
Error bar definition check |
| Teal |
Disclosure |
Baseline and sample size disclosure |
| Red |
Verdict |
OK / WARNING / FAIL assessment |
---
## Pre-Diagram Checklist
Before creating the diagram, verify:
- [ ] LOADED `/autoskillit:mermaid` skill using the Skill tool
- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)
- [ ] Diagram will include a color legend table
- [ ] Every figure with a non-declarative title is flagged as FAIL
- [ ] Every axis missing units on a continuous quantity is flagged as WARNING
- [ ] Every figure with undefined error bars is flagged as FAIL
1---2name: vis-lens-caption-annot3categories: [vis-lens]4activate_deps: [mermaid]5description: "Create Annotative Caption visualization planning spec showing declarative titles, axis labels with units, error definition in legend, baseline references, sample sizes, and venue-specific caption format. Annotative lens answering \"Are figure captions and axis labels fully self-contained?\""6hooks:7 PreToolUse:8 - matcher: "*"9 hooks:10 - type: command11 command: "echo 'Caption Annotation Lens - Auditing caption completeness...'"12 once: true13metadata:14 source: https://skillmd.com/skills/talont-org/vis-lens-caption-annot15---1617# Annotative Caption Visualization Lens1819**Philosophical Mode:** Annotative20**Primary Question:** "Are figure captions and axis labels fully self-contained?"21**Focus:** Declarative titles (state the result, not "Figure N: Results"), axis labels with22 units, error definition in legend (CI95 / std / SEM), baseline references cited in23 caption, sample sizes disclosed per condition, venue-specific caption format2425## Arguments2627`/autoskillit:vis-lens-caption-annot [context_path] [experiment_plan_path]`2829- **context_path** (optional positional arg 1) — Absolute path to a lens context file30 containing IV/DV tables, H0/H1 hypotheses, controlled variables, and success criteria.31 If provided, read this file before beginning analysis to obtain structured context.32 If omitted, discover context by exploring the CWD.33- **experiment_plan_path** (optional positional arg 2) — Absolute path to the full34 experiment plan. If provided, read for complete experimental methodology and design.35 If omitted, locate the experiment plan by exploring the CWD.3637## When to Use3839- Auditing figure captions before paper submission40- Checking whether axis labels carry units and direction information41- Verifying error bars are defined in the legend or caption42- Ensuring baseline conditions are referenced explicitly43- Disclosing sample size per plotted condition44- User invokes `/autoskillit:vis-lens-caption-annot`4546## Critical Constraints4748**NEVER:**49- Modify any source code files50- Do not litter the codebase with useless comments, TODO markers, or explanatory annotations — the skill output and diagram speak for themselves51- Create files outside `{{AUTOSKILLIT_TEMP}}/vis-lens-caption-annot/`52- Use a non-declarative title like "Results" or "Figure 3: Performance" — titles must state the takeaway (e.g., "Model A outperforms baseline on all benchmarks")53- Omit units from axis labels (e.g., write "Latency (ms)", not "Latency")5455**ALWAYS:**56- Check every figure title for declarative language57- Verify every axis label carries a unit or categorical scale description58- Confirm error bars / shaded regions are defined (CI95, ±1 std, IQR, etc.) in the legend or caption59- Flag any figure that references a baseline without naming it explicitly60- Report sample size per plotted condition (n=X seeds, N=X subjects, etc.)61- BEFORE creating any diagram, LOAD the `/autoskillit:mermaid` skill using the Skill tool — this is MANDATORY62- If the Skill tool cannot be used (disable-model-invocation) or refuses this invocation, do NOT proceed with diagram creation. Abort this step and omit the diagram from output.63- Write output to `{{AUTOSKILLIT_TEMP}}/vis-lens-caption-annot/vis_spec_caption_annot_{YYYY-MM-DD_HHMMSS}.md` (relative to the current working directory)64- After writing the file, emit the structured output token as **literal plain text** with no65 markdown formatting on the token name (the adjudicator performs a regex match):6667 ```68 diagram_path = /absolute/path/to/{{AUTOSKILLIT_TEMP}}/vis-lens-caption-annot/vis_spec_caption_annot_{...}.md69 ```7071---7273## Analysis Workflow7475### Step 0: Parse optional arguments7677If positional arg 1 (context_path) is provided and the file exists, read it to obtain78IV/DV tables, H0/H1 hypotheses, controlled variables, and success criteria. If positional79arg 2 (experiment_plan_path) is provided and exists, read the experiment plan for full80methodology. Use this structured context as the foundation for Steps 1–4; skip the CWD81exploration for these fields if the context file supplies them.8283### Step 1: Inventory Figure Titles8485For every figure in the experiment plan or codebase:86- Collect the current title string87- Classify: DECLARATIVE (states a result) vs DESCRIPTIVE (labels the figure)88- FAIL if title is purely descriptive (e.g. "Ablation Results", "Performance Comparison")89- PASS if title states the key finding (e.g. "Removing component X degrades accuracy by 8 pp")9091### Step 2: Axis Label and Unit Audit9293For every axis in every figure:94- Confirm the label is present (no unlabeled axes)95- Confirm units are stated for continuous quantities: time (ms/s), memory (MB/GB), accuracy (%), loss (nats/bits), etc.96- Confirm categorical axes name the grouping variable97- FLAG WARNING for any axis missing a unit on a continuous quantity9899### Step 3: Error and Uncertainty Definition Audit100101For every figure that shows error bars, shaded regions, or confidence intervals:102- Identify the error representation: CI (90/95/99%), ±1 std, ±1 SEM, IQR, min/max103- Verify the definition appears in the legend or caption text104- FLAG FAIL if error bars are shown but not defined105106### Step 4: Baseline and Sample Size Disclosure107108- Identify every "baseline" referenced in a figure or caption109- Verify the baseline name and source are stated (e.g. "GPT-4 (OpenAI, 2023)")110- For each plotted group/condition, verify sample size n is disclosed (seeds, subjects, runs)111- FLAG WARNING for any undisclosed baseline or missing n112113### Step 5: Emit yaml:figure-spec Blocks114115For each figure, emit one `yaml:figure-spec` fenced block with the `annotations` field116describing the caption audit result. Then LOAD `/autoskillit:mermaid` and create a diagram117showing: title audit → axis audit → error definition → baseline/n disclosure → verdict.118119---120121## Output Template122123```markdown124# Annotative Caption Spec: {System / Experiment Name}125126**Lens:** Annotative Caption (Annotative)127**Question:** Are figure captions and axis labels fully self-contained?128**Date:** {YYYY-MM-DD}129**Scope:** {What was analyzed}130131## Caption Audit Summary132133| Figure | Declarative Title | Axis Units | Error Defined | Baseline Named | Sample n | Status |134|--------|-------------------|-----------|---------------|----------------|----------|--------|135| fig-01 | FAIL (descriptive) | PASS | PASS | N/A | PASS | FAIL |136| fig-02 | PASS | PASS | PASS | PASS | PASS | OK |137138## Figure Specs139140```yaml141# yaml:figure-spec — canonical schema (spec_version: "1.0")142figure_id: "fig-02-ablation-comparison"143figure_title: "Removing component X degrades accuracy by 8 pp"144spec_version: "1.0"145chart_type: "bar"146chart_type_fallback: "table"147perceptual_justification: "Grouped bar chart shows per-component contribution directly."148data_source: "results/ablation.csv"149data_mapping:150 x: "variant"151 y: "accuracy_delta_pp"152 color: "component"153 size: ""154 facet: ""155layout:156 width_inches: 5.0157 height_inches: 3.5158 dpi: 300159stat_overlay:160 type: "error_bar"161 measure: "CI95"162 n_seeds: 5163annotations: ["Declarative title PASS; axis labels with units PASS; CI95 defined in legend PASS; n=5 seeds per condition PASS"]164anti_patterns: []165palette: "okabe-ito"166format: "pdf"167target_dpi: 300168library: "matplotlib"169report_section: "Section 5 Ablation"170priority: "P1"171placement_tier: "main"172conflicts: []173metadata:174 created_by: "vis-lens-caption-annot"175 reviewed_by: ""176 last_updated: "{YYYY-MM-DD}"177```178179## Caption Annotation Diagram180181```mermaid182%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%183flowchart TB184 %% CLASS DEFINITIONS %%185 classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;186 classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;187 classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;188 classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;189 classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;190191 subgraph Titles ["TITLE AUDIT"]192 T1["title = {text}<br/>━━━━━━━━━━<br/>declarative: PASS / FAIL"]193 end194195 subgraph Axes ["AXIS LABEL AUDIT"]196 A1["x-axis: {label} ({unit})<br/>y-axis: {label} ({unit})<br/>━━━━━━━━━━<br/>units present: PASS / FAIL"]197 end198199 subgraph Errors ["ERROR DEFINITION"]200 E1["error type: {CI95/std/SEM}<br/>━━━━━━━━━━<br/>defined in legend: PASS / FAIL"]201 end202203 subgraph Disclosure ["BASELINE & SAMPLE n"]204 D1["baseline: {name}<br/>n per condition: {N}<br/>━━━━━━━━━━<br/>disclosed: PASS / FAIL"]205 end206207 subgraph Verdict ["VERDICT"]208 V1["{OK / WARNING / FAIL}<br/>━━━━━━━━━━<br/>{reason}"]209 end210211 T1 --> A1212 A1 --> E1213 E1 --> D1214 D1 --> V1215216 class T1 stateNode;217 class A1 handler;218 class E1 cli;219 class D1 output;220 class V1 detector;221```222223**Color Legend:**224| Color | Category | Description |225|-------|----------|-------------|226| Dark Teal | Title | Declarative title audit |227| Orange | Axes | Axis label and unit audit |228| Dark Blue | Error | Error bar definition check |229| Teal | Disclosure | Baseline and sample size disclosure |230| Red | Verdict | OK / WARNING / FAIL assessment |231```232233---234235## Pre-Diagram Checklist236237Before creating the diagram, verify:238239- [ ] LOADED `/autoskillit:mermaid` skill using the Skill tool240- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)241- [ ] Diagram will include a color legend table242- [ ] Every figure with a non-declarative title is flagged as FAIL243- [ ] Every axis missing units on a continuous quantity is flagged as WARNING244- [ ] Every figure with undefined error bars is flagged as FAIL