Compositional Layout Visualization Lens
Philosophical Mode: Compositional
Primary Question: "Which layout — small multiples vs overlay — best reveals the comparison?"
Focus: Small Multiples vs Overlay, Faceting Strategy (row/col), Shared-Axis Alignment,
Grouped vs Stacked Bars, Factorial Interaction Plots, Panel Reading Order
Arguments
/autoskillit:vis-lens-multi-compare [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
- Designing layouts for experiments with multiple conditions, factors, or treatments
- Deciding whether to use small multiples or overlapping traces in a figure
- Planning faceted grids for factorial designs (2+ independent variables × 2+ levels)
- Evaluating whether grouped or stacked bars serve the comparison goal
- User invokes
/autoskillit:vis-lens-multi-compare
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-multi-compare/
- Use overlapping traces when ≥ 4 conditions are compared — prefer small multiples
- Use stacked bars for comparisons where the baseline shifts — use grouped bars instead
ALWAYS:
Prefer small multiples over overlays when: num_conditions ≥ 5, OR data series overlap
heavily, OR the comparison requires individual-panel annotation
Apply consistent shared-axis limits across all panels in a small-multiples layout
Enforce left-to-right, top-to-bottom panel reading order matching the experimental
factor order (main factor changes columns; secondary factor changes rows)
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-multi-compare/vis_spec_multi_compare_{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-multi-compare/vis_spec_multi_compare_{...}.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 Conditions and Factors
Scan experiment plan, context file, and codebase for:
Condition and Factor Count
- Count num_DVs (dependent variables), num_conditions (levels per factor), num_factors (IVs)
- Look for: condition lists, treatment arms,
conditions = [...], groups = [...], factor tables
Series Overlap
- Assess whether plotting all conditions on a single axes would create heavy visual overlap
- Look for: overlapping confidence bands, dense line clusters, label collisions
Factorial Structure
- Detect whether the design is factorial (2+ IVs × 2+ levels each)
- Look for: interaction terms, crossed factors,
factorial, grid_search
Step 2: Apply Small-Multiples vs Overlay Decision Rule
For each figure that shows multi-condition data, determine the layout strategy:
Overlay (single axes):
- ≤ 3 conditions, no label collision, primary message is aggregate trend
- Use when: the comparison is a single-axis trend, conditions are well-separated visually
Small Multiples (faceted grid):
- ≥ 4 conditions, OR heavy overlap, OR per-panel annotation needed
- OR factorial (2+ IVs × 2+ levels): always use small multiples
- Assign
row_factor and col_factor explicitly
Stacked vs Grouped Bars:
- Stacked bars: only when part-to-whole is the story AND baselines are shared
- Grouped bars: when individual comparison matters more than the total
Step 3: Assign Facet Layout
For small-multiples layouts:
- Assign
col_factor to the main independent variable (most levels or primary interest)
- Assign
row_factor to the secondary independent variable
- Set shared x-axis and y-axis limits across all panels
- Document reading order: left-to-right (col_factor levels), top-to-bottom (row_factor levels)
Step 4: Emit yaml:figure-spec Blocks
For each figure, emit one yaml:figure-spec fenced block with facet field populated.
Then LOAD /autoskillit:mermaid and create a panel-layout schematic diagram (boxes
representing panel grid with row/col labels).
Output Template
# Compositional Layout Spec: {System / Experiment Name}
**Lens:** Compositional Layout (Compositional)
**Question:** Which layout — small multiples vs overlay — best reveals the comparison?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}
**num_conditions detected:** {N}
## Layout Decision Summary
| Figure | num_conditions | num_factors | Strategy | row_factor | col_factor |
|--------|---------------|-------------|----------|------------|------------|
| {fig-01} | 6 | 2 | small-multiples | method | dataset |
| {fig-02} | 3 | 1 | overlay | — | — |
## Figure Specs
```yaml
# yaml:figure-spec — canonical schema (spec_version: "1.0")
figure_id: "fig-01-factorial-accuracy"
figure_title: "Accuracy Across Methods × Datasets"
spec_version: "1.0"
chart_type: "line"
chart_type_fallback: "grouped-bar"
perceptual_justification: "Small multiples prevent overlap; shared y-axis enables cross-panel comparison."
data_source: "results/accuracy.csv"
data_mapping:
x: "epoch"
y: "accuracy"
color: "variant"
size: ""
facet: "col=dataset, row=method"
layout:
width_inches: 10.0
height_inches: 6.0
dpi: 300
stat_overlay:
type: "error_bar"
measure: "CI95"
n_seeds: 5
annotations: ["shared y-axis; panel grid: 3 cols × 2 rows"]
anti_patterns: ["ap-overplotting"]
palette: "okabe-ito"
format: "pdf"
target_dpi: 300
library: "matplotlib"
report_section: "Section 4 Results"
priority: "P1"
placement_tier: "main"
conflicts: []
metadata:
created_by: "vis-lens-multi-compare"
reviewed_by: ""
last_updated: "{YYYY-MM-DD}"
Compositional Layout 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 Conditions ["CONDITION COUNT"]
C1["num_conditions = {N}<br/>━━━━━━━━━━<br/>{factorial: yes/no}"]
end
subgraph Strategy ["LAYOUT STRATEGY"]
S1["overlay / small-multiples<br/>━━━━━━━━━━<br/>{decision rule applied}"]
end
subgraph Facet ["FACET ASSIGNMENT"]
F1["col_factor = {X}<br/>row_factor = {Y}<br/>━━━━━━━━━━<br/>shared axes: yes/no"]
end
subgraph Verdict ["VERDICT"]
V1["{layout type}<br/>━━━━━━━━━━<br/>{reading order note}"]
end
C1 --> S1
S1 --> F1
F1 --> V1
class C1 stateNode;
class S1 cli;
class F1 handler;
class V1 output;
Color Legend:
| Color |
Category |
Description |
| Dark Teal |
Condition Count |
Number of conditions and factorial structure |
| Dark Blue |
Strategy |
Overlay vs small-multiples decision |
| Orange |
Facet Assignment |
Row/col factor and shared-axis configuration |
| Teal |
Verdict |
Final layout recommendation |
---
## 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 ≥ 4 conditions has been assigned a small-multiples layout
- [ ] Every `yaml:figure-spec` has the `facet` field filled (or explicitly empty for overlays)
1---2name: vis-lens-multi-compare3categories: [vis-lens]4activate_deps: [mermaid]5description: "Create Compositional Layout visualization planning spec showing small-multiples vs overlay decisions, faceting strategy (row/col), shared-axis alignment, grouped vs stacked bars, factorial interaction plots, and panel reading order. Compositional lens answering \"Which layout best reveals the comparison structure?\""6hooks:7 PreToolUse:8 - matcher: "*"9 hooks:10 - type: command11 command: "echo 'Multi-Compare Lens - Analyzing compositional layout strategy...'"12 once: true13metadata:14 source: https://skillmd.com/skills/talont-org/vis-lens-multi-compare15---1617# Compositional Layout Visualization Lens1819**Philosophical Mode:** Compositional20**Primary Question:** "Which layout — small multiples vs overlay — best reveals the comparison?"21**Focus:** Small Multiples vs Overlay, Faceting Strategy (row/col), Shared-Axis Alignment,22 Grouped vs Stacked Bars, Factorial Interaction Plots, Panel Reading Order2324## Arguments2526`/autoskillit:vis-lens-multi-compare [context_path] [experiment_plan_path]`2728- **context_path** (optional positional arg 1) — Absolute path to a lens context file29 containing IV/DV tables, H0/H1 hypotheses, controlled variables, and success criteria.30 If provided, read this file before beginning analysis to obtain structured context.31 If omitted, discover context by exploring the CWD.32- **experiment_plan_path** (optional positional arg 2) — Absolute path to the full33 experiment plan. If provided, read for complete experimental methodology and design.34 If omitted, locate the experiment plan by exploring the CWD.3536## When to Use3738- Designing layouts for experiments with multiple conditions, factors, or treatments39- Deciding whether to use small multiples or overlapping traces in a figure40- Planning faceted grids for factorial designs (2+ independent variables × 2+ levels)41- Evaluating whether grouped or stacked bars serve the comparison goal42- User invokes `/autoskillit:vis-lens-multi-compare`4344## Critical Constraints4546**NEVER:**47- Modify any source code files48- Do not litter the codebase with useless comments, TODO markers, or explanatory annotations — the skill output and diagram speak for themselves49- Create files outside `{{AUTOSKILLIT_TEMP}}/vis-lens-multi-compare/`50- Use overlapping traces when ≥ 4 conditions are compared — prefer small multiples51- Use stacked bars for comparisons where the baseline shifts — use grouped bars instead5253**ALWAYS:**54- Prefer small multiples over overlays when: num_conditions ≥ 5, OR data series overlap55 heavily, OR the comparison requires individual-panel annotation56- Apply consistent shared-axis limits across all panels in a small-multiples layout57- Enforce left-to-right, top-to-bottom panel reading order matching the experimental58 factor order (main factor changes columns; secondary factor changes rows)59- BEFORE creating any diagram, LOAD the `/autoskillit:mermaid` skill using the Skill tool — this is MANDATORY60- 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.61- Write output to `{{AUTOSKILLIT_TEMP}}/vis-lens-multi-compare/vis_spec_multi_compare_{YYYY-MM-DD_HHMMSS}.md` (relative to the current working directory)62- After writing the file, emit the structured output token as **literal plain text** with no63 markdown formatting on the token name (the adjudicator performs a regex match):6465 ```66 diagram_path = /absolute/path/to/{{AUTOSKILLIT_TEMP}}/vis-lens-multi-compare/vis_spec_multi_compare_{...}.md67 ```6869---7071## Analysis Workflow7273### Step 0: Parse optional arguments7475If positional arg 1 (context_path) is provided and the file exists, read it to obtain76IV/DV tables, H0/H1 hypotheses, controlled variables, and success criteria. If positional77arg 2 (experiment_plan_path) is provided and exists, read the experiment plan for full78methodology. Use this structured context as the foundation for Steps 1–4; skip the CWD79exploration for these fields if the context file supplies them.8081### Step 1: Inventory Conditions and Factors8283Scan experiment plan, context file, and codebase for:8485**Condition and Factor Count**86- Count num_DVs (dependent variables), num_conditions (levels per factor), num_factors (IVs)87- Look for: condition lists, treatment arms, `conditions = [...]`, `groups = [...]`, factor tables8889**Series Overlap**90- Assess whether plotting all conditions on a single axes would create heavy visual overlap91- Look for: overlapping confidence bands, dense line clusters, label collisions9293**Factorial Structure**94- Detect whether the design is factorial (2+ IVs × 2+ levels each)95- Look for: interaction terms, crossed factors, `factorial`, `grid_search`9697### Step 2: Apply Small-Multiples vs Overlay Decision Rule9899For each figure that shows multi-condition data, determine the layout strategy:100101**Overlay (single axes):**102- ≤ 3 conditions, no label collision, primary message is aggregate trend103- Use when: the comparison is a single-axis trend, conditions are well-separated visually104105**Small Multiples (faceted grid):**106- ≥ 4 conditions, OR heavy overlap, OR per-panel annotation needed107- OR factorial (2+ IVs × 2+ levels): always use small multiples108- Assign `row_factor` and `col_factor` explicitly109110**Stacked vs Grouped Bars:**111- Stacked bars: only when part-to-whole is the story AND baselines are shared112- Grouped bars: when individual comparison matters more than the total113114### Step 3: Assign Facet Layout115116For small-multiples layouts:117- Assign `col_factor` to the main independent variable (most levels or primary interest)118- Assign `row_factor` to the secondary independent variable119- Set shared x-axis and y-axis limits across all panels120- Document reading order: left-to-right (col_factor levels), top-to-bottom (row_factor levels)121122### Step 4: Emit yaml:figure-spec Blocks123124For each figure, emit one `yaml:figure-spec` fenced block with `facet` field populated.125Then LOAD `/autoskillit:mermaid` and create a panel-layout schematic diagram (boxes126representing panel grid with row/col labels).127128---129130## Output Template131132```markdown133# Compositional Layout Spec: {System / Experiment Name}134135**Lens:** Compositional Layout (Compositional)136**Question:** Which layout — small multiples vs overlay — best reveals the comparison?137**Date:** {YYYY-MM-DD}138**Scope:** {What was analyzed}139**num_conditions detected:** {N}140141## Layout Decision Summary142143| Figure | num_conditions | num_factors | Strategy | row_factor | col_factor |144|--------|---------------|-------------|----------|------------|------------|145| {fig-01} | 6 | 2 | small-multiples | method | dataset |146| {fig-02} | 3 | 1 | overlay | — | — |147148## Figure Specs149150```yaml151# yaml:figure-spec — canonical schema (spec_version: "1.0")152figure_id: "fig-01-factorial-accuracy"153figure_title: "Accuracy Across Methods × Datasets"154spec_version: "1.0"155chart_type: "line"156chart_type_fallback: "grouped-bar"157perceptual_justification: "Small multiples prevent overlap; shared y-axis enables cross-panel comparison."158data_source: "results/accuracy.csv"159data_mapping:160 x: "epoch"161 y: "accuracy"162 color: "variant"163 size: ""164 facet: "col=dataset, row=method"165layout:166 width_inches: 10.0167 height_inches: 6.0168 dpi: 300169stat_overlay:170 type: "error_bar"171 measure: "CI95"172 n_seeds: 5173annotations: ["shared y-axis; panel grid: 3 cols × 2 rows"]174anti_patterns: ["ap-overplotting"]175palette: "okabe-ito"176format: "pdf"177target_dpi: 300178library: "matplotlib"179report_section: "Section 4 Results"180priority: "P1"181placement_tier: "main"182conflicts: []183metadata:184 created_by: "vis-lens-multi-compare"185 reviewed_by: ""186 last_updated: "{YYYY-MM-DD}"187```188189## Compositional Layout Diagram190191```mermaid192%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%193flowchart TB194 %% CLASS DEFINITIONS %%195 classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;196 classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;197 classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;198 classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;199 classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;200201 subgraph Conditions ["CONDITION COUNT"]202 C1["num_conditions = {N}<br/>━━━━━━━━━━<br/>{factorial: yes/no}"]203 end204205 subgraph Strategy ["LAYOUT STRATEGY"]206 S1["overlay / small-multiples<br/>━━━━━━━━━━<br/>{decision rule applied}"]207 end208209 subgraph Facet ["FACET ASSIGNMENT"]210 F1["col_factor = {X}<br/>row_factor = {Y}<br/>━━━━━━━━━━<br/>shared axes: yes/no"]211 end212213 subgraph Verdict ["VERDICT"]214 V1["{layout type}<br/>━━━━━━━━━━<br/>{reading order note}"]215 end216217 C1 --> S1218 S1 --> F1219 F1 --> V1220221 class C1 stateNode;222 class S1 cli;223 class F1 handler;224 class V1 output;225```226227**Color Legend:**228| Color | Category | Description |229|-------|----------|-------------|230| Dark Teal | Condition Count | Number of conditions and factorial structure |231| Dark Blue | Strategy | Overlay vs small-multiples decision |232| Orange | Facet Assignment | Row/col factor and shared-axis configuration |233| Teal | Verdict | Final layout recommendation |234```235236---237238## Pre-Diagram Checklist239240Before creating the diagram, verify:241242- [ ] LOADED `/autoskillit:mermaid` skill using the Skill tool243- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)244- [ ] Diagram will include a color legend table245- [ ] Every figure with ≥ 4 conditions has been assigned a small-multiples layout246- [ ] Every `yaml:figure-spec` has the `facet` field filled (or explicitly empty for overlays)