Initial commit

skills/visualization-choice-reporting/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: visualization-choice-reporting
+description: Use when you need to choose the right visualization for your data and question, then create a narrated report that highlights insights and recommends actions. Invoke when analyzing data for patterns (trends, comparisons, distributions, relationships, compositions), building dashboards or reports, presenting metrics to stakeholders, monitoring KPIs, exploring datasets for insights, communicating findings from analysis, or when user mentions "visualize this", "what chart should I use", "create a dashboard", "analyze this data", "show trends", "compare these metrics", "report on", "what does this data tell us", or needs to turn data into actionable insights. Apply to business analytics (revenue, growth, churn, funnel, cohort, segmentation), product metrics (usage, adoption, retention, feature performance, A/B tests), marketing analytics (campaign ROI, attribution, funnel, customer acquisition), financial reporting (P&L, budget, forecast, variance), operational metrics (uptime, performance, capacity, SLA), sales analytics (pipeline, forecast, territory, quota attainment), HR metrics (headcount, turnover, engagement, DEI), and any scenario where data needs to become a clear, actionable story with the right visual form.
+---
+# Visualization Choice & Reporting
+
+## Overview
+
+**Visualization choice & reporting** matches visualization types to questions and data, then creates narrated dashboards that highlight signal and recommend actions.
+
+**Three core components:**
+
+**1. Chart selection:** Match chart type to question type and data structure (comparison → bar chart, trend → line chart, distribution → histogram, relationship → scatter, composition → treemap, geographic → map, hierarchy → tree diagram, flow → sankey)
+
+**2. Visualization best practices:** Apply perceptual principles (position > length > angle > area > color for accuracy), reduce chart junk, use pre-attentive attributes (color, size, position) to highlight signal, respect accessibility (colorblind-safe palettes, alt text), choose appropriate scales (linear, log, normalized)
+
+**3. Narrative reporting:** Lead with insight headline, annotate key patterns, provide context (vs benchmark, vs target, vs previous period), interpret what it means, recommend next actions
+
+**When to use:** Data analysis, dashboards, reports, presentations, monitoring, exploration, stakeholder communication
+
+## Workflow
+
+Copy this checklist and track your progress:
+
+```
+Visualization Choice & Reporting Progress:
+- [ ] Step 1: Clarify question and profile data
+- [ ] Step 2: Select visualization type
+- [ ] Step 3: Design effective chart
+- [ ] Step 4: Narrate insights and actions
+- [ ] Step 5: Validate and deliver
+```
+
+**Step 1: Clarify question and profile data**
+
+Define the question you're answering (What's the trend? How do X and Y compare? What's the distribution? What drives Z? What's the composition?). Profile your data: type (categorical, numerical, temporal, geospatial), granularity (daily, user-level, aggregated), size (10 rows, 10K, 10M), dimensions (1D, 2D, multivariate). See [Question-Data Profiling](#question-data-profiling).
+
+**Step 2: Select visualization type**
+
+Match question type to chart family using [Chart Selection Guide](#chart-selection-guide). Consider data size (small → tables, medium → standard charts, large → heatmaps/binned), number of series (1-3 → standard, 4-10 → small multiples, 10+ → interactive/aggregated), and audience expertise (executives → simple with insights, analysts → detailed exploration).
+
+**Step 3: Design effective chart**
+
+For simple cases → Apply [Design Checklist](#design-checklist) (clear title, labeled axes, legend if needed, annotations, accessible colors). For complex cases (multivariate, dashboards, interactive) → Study [resources/methodology.md](resources/methodology.md) for advanced techniques (small multiples, layered charts, dashboard layout, interaction patterns).
+
+**Step 4: Narrate insights and actions**
+
+Lead with insight headline ("Revenue up 30% YoY driven by Enterprise segment"), annotate key patterns (arrows, labels, shading), provide context (vs benchmark, target, previous), interpret meaning ("Suggests product-market fit in Enterprise"), recommend actions ("Double down on Enterprise sales hiring"). See [Narrative Framework](#narrative-framework).
+
+**Step 5: Validate and deliver**
+
+Self-assess using [resources/evaluators/rubric_visualization_choice_reporting.json](resources/evaluators/rubric_visualization_choice_reporting.json). Check: Does chart answer the question clearly? Are insights obvious at a glance? Are next actions clear? Create `visualization-choice-reporting.md` with question, data summary, visualization spec, narrative, and actions. See [Delivery Format](#delivery-format).
+
+---
+
+## Question-Data Profiling
+
+**Question Types → Chart Families**
+
+| Question Type | Example | Primary Chart Families |
+|---------------|---------|------------------------|
+| **Trend** | How has X changed over time? | Line, area, sparkline, horizon |
+| **Comparison** | How do categories compare? | Bar (horizontal for names), column, dot plot, slope chart |
+| **Distribution** | What's the spread/frequency? | Histogram, box plot, violin, density plot |
+| **Relationship** | How do X and Y relate? | Scatter, bubble, connected scatter, hexbin |
+| **Composition** | What are the parts? | Treemap, pie/donut, stacked bar, waterfall, sankey |
+| **Geographic** | Where is it happening? | Choropleth, bubble map, flow map, dot map |
+| **Hierarchical** | What's the structure? | Tree, dendrogram, sunburst, circle packing |
+| **Multivariate** | How do many variables interact? | Small multiples, parallel coordinates, heatmap, SPLOM |
+
+**Data Type → Encoding Considerations**
+
+- **Categorical** (product, region, status): Use position, color hue, shape. Bar length better than pie angle for accuracy.
+- **Numerical** (revenue, count, score): Use position, length, size. Prefer linear scales; use log only when spanning orders of magnitude.
+- **Temporal** (date, timestamp): Always use consistent intervals. Annotate events. Show seasonality if relevant.
+- **Geospatial** (lat/lon, region): Use maps for absolute location; use tables/charts if geography not central to insight.
+
+---
+
+## Chart Selection Guide
+
+| Question Type | Chart Types | When to Use |
+|---------------|-------------|-------------|
+| **Comparison** | Bar (horizontal), Column, Grouped bar, Dot plot, Slope chart | Categorical → Numerical. Horizontal bar for long names/ranking. Grouped for 2-3 metrics. Slope for before/after. |
+| **Trend** | Line, Area, Sparkline, Step, Candlestick | Time → Numerical. Line for continuous trends. Area for cumulative/part-to-whole. Sparkline for inline. Step for discrete changes. |
+| **Distribution** | Histogram, Box plot, Violin, Density plot | Numerical → Frequency. Histogram for shape/outliers. Box for quartiles across groups. Violin for full density. |
+| **Relationship** | Scatter, Bubble, Hexbin, Connected scatter | Numerical X → Numerical Y. Scatter for correlation. Bubble for 3rd/4th variable (size/color). Hexbin for dense data. |
+| **Composition** | Treemap, Pie/Donut, Stacked bar (100%), Waterfall, Sankey | Parts of whole. Treemap for hierarchy. Pie for 2-5 categories (part-to-whole key). Waterfall for cumulative. Sankey for flow. |
+| **Geographic** | Choropleth, Bubble map, Flow map | Spatial patterns. Choropleth for regions. Bubble for precise locations. Flow for origin-destination. |
+| **Multivariate** | Small multiples, Heatmap, Parallel coordinates | Many variables. Small multiples for consistent comparison. Heatmap for matrix (time×day). Parallel for dimensions. |
+
+---
+
+## Design Checklist
+
+**Essential Elements**
+
+- [ ] **Insight headline title:** Not "Revenue by Month" but "Revenue Up 30% YoY, Driven by Enterprise"
+- [ ] **Clear axis labels with units:** "Revenue ($M)", "Month (2024)", not just "Revenue", "Date"
+- [ ] **Legend if multiple series:** Position near chart, use direct labels on lines when possible
+- [ ] **Annotations for key points:** Arrows, labels, shading for important events/patterns
+- [ ] **Source and timestamp:** "Source: Analytics DB, as of 2024-11-14" builds trust
+
+**Perceptual Best Practices**
+
+- [ ] **Start Y-axis at zero for bar/column charts** (to avoid exaggerating differences)
+- [ ] **Use position over angle/area** (bar > pie for accuracy, scatter > bubble when size isn't critical)
+- [ ] **Colorblind-safe palette:** Avoid red-green only; use blue-orange or add patterns
+- [ ] **Limit colors to 5-7 distinct hues** (more requires legend lookup, slows comprehension)
+- [ ] **Use pre-attentive attributes** (color, size, position) to highlight signal, not decoration
+
+**Declutter**
+
+- [ ] **Remove chart junk:** No 3D, no gradients, no heavy gridlines, no background images
+- [ ] **Mute non-data ink:** Light gray gridlines, thin axes, subtle colors for reference lines
+- [ ] **Use white space:** Don't cram; let data breathe
+
+**Accessibility**
+
+- [ ] **Alt text describing insight:** "Line chart showing revenue grew from $2M to $2.6M (30% increase) from Q1 to Q4 2024, with Enterprise segment contributing 80% of growth."
+- [ ] **Sufficient contrast:** Text readable, lines distinguishable
+- [ ] **Patterns in addition to color** for critical distinctions (dashed/solid lines, hatched fills)
+
+---
+
+## Narrative Framework
+
+**Structure: Headline → Pattern → Context → Meaning → Action**
+
+**1. Headline (one sentence, insight-first):**
+- Not: "This chart shows monthly revenue."
+- **But:** "Revenue grew 30% YoY, driven by Enterprise segment."
+
+**2. Pattern (what do you see?):**
+- "Q1-Q2 flat at $2M/month, then steady climb to $2.6M in Q4."
+- "Enterprise segment grew 120% while SMB declined 10%."
+
+**3. Context (compared to what?):**
+- "vs target: 15% above plan"
+- "vs last year: Q4 2023 was $2.0M, now $2.6M"
+- "vs industry: Our 30% growth vs 10% industry average"
+
+**4. Meaning (why does it matter?):**
+- "Suggests product-market fit in Enterprise; SMB churn indicates pricing mismatch."
+- "If sustained, Q1 2025 could hit $3M/month."
+
+**5. Action (what should we do?):**
+- "Prioritize: Hire 2 Enterprise AEs, launch SMB annual plans to reduce churn."
+- "Monitor: Enterprise win rate, SMB churn by plan type."
+
+**Example Full Narrative:**
+
+> **Headline:** Enterprise revenue up 120% YoY while SMB declined 10%, resulting in overall 30% growth.
+>
+> **Pattern:** Revenue grew from $2M/month (Q1) to $2.6M (Q4). Enterprise segment contributed $1.5M in Q4 (up from $680K in Q1), while SMB dropped from $1.3M to $1.1M.
+>
+> **Context:** Total revenue 15% above plan. Enterprise growth (120%) far exceeds industry average (25%). SMB churn rate doubled from 5% to 10% in Q3-Q4.
+>
+> **Meaning:** Strong product-market fit in Enterprise; SMB pricing or feature set may be misaligned. Enterprise is now 58% of revenue vs 34% in Q1, reducing diversification.
+>
+> **Actions:**
+> 1. **Prioritize:** Hire 2 Enterprise AEs for Q1, double down on Enterprise playbook
+> 2. **Fix:** Launch SMB annual plans (Q1) to reduce churn; interview churned SMB customers to identify gaps
+> 3. **Monitor:** Enterprise win rate, SMB churn by plan type, revenue concentration risk
+
+---
+
+## Delivery Format
+
+Create `visualization-choice-reporting.md` with these sections:
+
+**1. Question:** The question you're answering with data (e.g., "How has revenue trended over the past year?")
+
+**2. Data Summary:** Source, time period, granularity, dimensions, size (e.g., "Analytics DB, Jan-Dec 2024, monthly, revenue by segment, 24 rows")
+
+**3. Visualization:**
+- Chart type selected (e.g., "Multi-line chart with annotations")
+- Rationale (why this chart? question type, data structure, chart advantages)
+- Design decisions (Y-axis scale, labels, annotations, colors)
+- Chart specification (embed image, code, or detailed spec with axes, series, annotations)
+
+**4. Narrative:** (Headline → Pattern → Context → Meaning → Action structure from above)
+- Headline: Insight-first one-liner
+- Pattern: What you see
+- Context: vs benchmark/target/history
+- Meaning: Why it matters
+- Actions: What to do next
+
+**5. Validation:** Self-check with rubric (Clarity ✓, Accuracy ✓, Insight ✓, Actionability ✓, Accessibility ✓)
+
+**6. Appendix (optional):** Raw data, alternatives considered, statistical tests, assumptions
+
+See [resources/template.md](resources/template.md) for full template with examples.
+
+---
+
+## Common Mistakes
+
+**Chart Selection Errors**
+
+❌ **Pie chart for >5 categories:** Hard to compare angles accurately
+✓ **Use horizontal bar chart:** Position on common scale is more accurate
+
+❌ **Line chart for categorical data:** Implies continuity that doesn't exist (e.g., revenue by product)
+✓ **Use bar chart:** Discrete categories
+
+❌ **3D charts:** Perspective distorts values, adds no information
+✓ **Use 2D with color/size:** Clearer, more accurate
+
+**Design Mistakes**
+
+❌ **Y-axis doesn't start at zero (bar chart):** Exaggerates differences
+✓ **Start at zero for bar/column:** Accurate visual proportion
+
+❌ **Dual Y-axes with different scales:** Misleading correlations
+✓ **Use small multiples or index to 100:** Compare shapes, not scales
+
+❌ **Rainbow color scheme:** Not colorblind-safe, no perceptual ordering
+✓ **Sequential (light→dark) or diverging (blue→white→red) palette**
+
+**Narrative Failures**
+
+❌ **Title: "Revenue by Month":** Descriptive, not insightful
+✓ **"Revenue up 30% YoY, driven by Enterprise":** Insight-first
+
+❌ **No context:** "Revenue is $2.6M" (vs what?)
+✓ **Add benchmark:** "Revenue $2.6M, 15% above $2.25M target"
+
+❌ **Pattern without meaning:** "Revenue increased" (so what?)
+✓ **Interpret:** "Revenue up 30%, suggests Enterprise product-market fit, informs 2025 hiring plan"
+
+❌ **No actions:** Ends with "interesting pattern"
+✓ **Recommend:** "Hire 2 Enterprise AEs, investigate SMB churn"
+
+---
+
+## Resources
+
+- **Simple cases:** Use [resources/template.md](resources/template.md) for question profiling → chart selection → narrative
+- **Complex cases:** Study [resources/methodology.md](resources/methodology.md) for dashboards, small multiples, interactive visualizations, advanced chart types
+- **Self-assessment:** [resources/evaluators/rubric_visualization_choice_reporting.json](resources/evaluators/rubric_visualization_choice_reporting.json)
+
+**Further reading:**
+- "Storytelling with Data" by Cole Nussbaumer Knaflic (chart choice, decluttering, narrative)
+- "The Visual Display of Quantitative Information" by Edward Tufte (principles, chart junk, data-ink ratio)
+- "Show Me the Numbers" by Stephen Few (dashboard design, perceptual principles)

skills/visualization-choice-reporting/resources/evaluators/rubric_visualization_choice_reporting.json

@@ -0,0 +1,158 @@
+{
+  "criteria": [
+    {
+      "name": "Chart Selection Appropriateness",
+      "weight": 1.5,
+      "description": "Does the chart type match the question type and data structure?",
+      "levels": {
+        "5": "Perfect match: Chart type directly answers question (trend→line, comparison→bar, distribution→histogram, relationship→scatter, composition→treemap, geographic→map). Data dimensions fit chart (categorical for bar, numerical for scatter, temporal for line). Alternative charts would be clearly inferior. Example: Time series question gets line chart with proper temporal axis.",
+        "4": "Strong match: Chart type appropriate for question. Data fits well. Minor alternatives might work but chosen chart is defensible. Example: Grouped bar instead of slope chart for before/after comparison (both work, slight preference difference).",
+        "3": "Acceptable match: Chart type can answer question but not optimal. Data somewhat fits. Better alternatives exist. Example: Table for trend question (works but line chart would show pattern more clearly).",
+        "2": "Weak match: Chart type poorly suited to question. Data fit is awkward. Clear better alternatives ignored. Example: Pie chart with 8 slices for comparison (hard to compare angles; bar chart much better).",
+        "1": "Mismatch: Chart type doesn't answer question or data structure incompatible. Example: Line chart for categorical data (implies continuity that doesn't exist), or 3D pie chart (distorts values, adds no value)."
+      }
+    },
+    {
+      "name": "Design Quality",
+      "weight": 1.4,
+      "description": "Is the chart well-designed per perceptual best practices and free of chart junk?",
+      "levels": {
+        "5": "Excellent design: Insight-first title (not generic), axes labeled with units, appropriate scale (Y starts at zero for bar/column, appropriate range for line), legend clear or direct labels used, key points annotated (arrows, labels, shading), colorblind-safe palette, no chart junk (3D, gradients, heavy gridlines), non-data ink muted (light gray), white space used effectively, source & timestamp cited. Chart is immediately readable.",
+        "4": "Good design: Most best practices applied. Title insightful, axes labeled, scale appropriate, readable colors, minimal junk. Minor improvements possible (e.g., legend could be direct labels, one annotation missing). Overall professional.",
+        "3": "Acceptable design: Core elements present (title, axes, legend) but generic or incomplete. Scale issues (Y-axis doesn't start at zero for bar), some chart junk (heavy gridlines, unnecessary decorations), colors adequate but not optimized. Readable but not polished.",
+        "2": "Poor design: Missing key elements (unlabeled axes, no title or generic title like 'Chart'), misleading scale (truncated Y-axis exaggerating differences), excessive chart junk (3D, gradients, background images), poor color choices (rainbow palette, low contrast). Readable with effort.",
+        "1": "Unreadable: Critical failures (no axis labels, misleading scale, incomprehensible colors, heavy chart junk obscures data). Chart actively confuses or misleads."
+      }
+    },
+    {
+      "name": "Narrative Quality",
+      "weight": 1.5,
+      "description": "Does the narrative follow Headline → Pattern → Context → Meaning → Action structure effectively?",
+      "levels": {
+        "5": "Excellent narrative: Headline is insight-first one-liner (not generic). Pattern clearly described with specifics (not just 'increased' but 'grew from $2M to $2.6M, 30%'). Context provided (vs target/history/industry). Meaning interpreted (why it matters, implications). Actions recommended (specific, feasible, with owners/timelines if possible). Narrative tells a complete story from observation to action.",
+        "4": "Good narrative: Has all elements (headline, pattern, context, meaning, action) but some less developed. Headline good, pattern described, context provided, meaning stated, actions somewhat specific. Mostly complete story with minor gaps.",
+        "3": "Acceptable narrative: Has most elements but some weak or missing. Headline generic ('Revenue by Month'), pattern described but vague, context minimal (just one comparison), meaning surface-level, actions vague ('we should investigate'). Incomplete story.",
+        "2": "Weak narrative: Missing multiple elements. Headline generic, pattern barely described ('revenue increased'), no context (vs what?), meaning absent (no 'so what?'), actions missing or too vague to execute. More description than narrative.",
+        "1": "No narrative: Just describes chart ('this shows revenue'). No insight headline, no interpretation, no context, no actions. Chart without story."
+      }
+    },
+    {
+      "name": "Insight Clarity",
+      "weight": 1.4,
+      "description": "Is the key insight obvious at a glance? Can a busy reader extract the main takeaway in 5 seconds?",
+      "levels": {
+        "5": "Insight jumps out: Title states the insight ('Revenue Up 30% YoY, Driven by Enterprise'), visual encoding highlights signal (color, annotation, positioning), pattern is unmistakable at a glance. Busy executive can extract takeaway in 5 seconds. Chart does the cognitive work for the reader.",
+        "4": "Insight clear: Title helps ('Revenue Growth Accelerating'), chart design guides eye to key pattern (annotation, color), insight obvious with 10-15 seconds of review. Little cognitive effort required.",
+        "3": "Insight present but requires work: Title generic, pattern visible but not highlighted, reader must scan chart to find signal. Takes 30+ seconds to extract insight. Some cognitive effort needed.",
+        "2": "Insight buried: Title unhelpful, no highlighting, pattern hard to spot among noise, reader must study chart carefully to find signal. Takes 60+ seconds. Significant cognitive effort.",
+        "1": "No clear insight: Unclear what reader should take away. Chart shows data but doesn't guide to conclusion. Reader left to figure it out."
+      }
+    },
+    {
+      "name": "Actionability",
+      "weight": 1.3,
+      "description": "Are next steps clear, specific, and feasible?",
+      "levels": {
+        "5": "Highly actionable: Specific actions recommended (not vague). Has owners/timelines or clear enough to assign. Prioritized (what to do first, second, third). Feasible given context. Monitoring metrics defined. Example: '1. Prioritize: Hire 2 Enterprise AEs by Q1 (Hiring Manager). 2. Investigate: Interview 10 churned SMB customers by Dec 15 (PM). 3. Monitor: Enterprise win rate, SMB churn by plan type.'",
+        "4": "Actionable: Actions specific and clear (who/what/when mostly defined). Feasible. Monitoring mentioned. Slightly less detail but still executable. Example: 'Hire Enterprise AEs, investigate SMB churn through interviews, monitor win rate and churn.'",
+        "3": "Somewhat actionable: Actions identified but vague on details. Feasible direction but needs refinement to execute. Example: 'Focus on Enterprise growth, address SMB churn, track key metrics.' (What does 'focus' mean? Which metrics?)",
+        "2": "Weakly actionable: Actions too vague to execute. No owners/timelines. Not clear what to do. Example: 'We should look into this', 'Consider improvements', 'Monitor the situation.'",
+        "1": "Not actionable: No actions recommended, or actions are infeasible/irrelevant. Ends with observation, no 'what next?'"
+      }
+    },
+    {
+      "name": "Accuracy",
+      "weight": 1.5,
+      "description": "Are data, calculations, and visual encoding accurate and not misleading?",
+      "levels": {
+        "5": "Perfectly accurate: Data source credible and cited. Calculations correct (spot-checked). Visual encoding truthful (no truncated Y-axis on bar chart exaggerating differences, no 3D distorting values). Numbers in narrative match chart. Caveats noted (data quality issues, assumptions, limitations). No misleading elements.",
+        "4": "Accurate: Data credible, calculations correct, visual encoding truthful. Minor presentation choices debatable (e.g., Y-axis range) but not misleading. Numbers match. Most caveats noted.",
+        "3": "Mostly accurate: Data credible, calculations mostly correct (minor rounding), visual encoding slightly questionable (e.g., Y-axis starts at non-zero for line chart, overstates change but not egregiously). Numbers generally match. Some caveats missing.",
+        "2": "Questionable accuracy: Data source unclear, calculations suspect, visual encoding misleading (e.g., truncated Y-axis on bar chart, dual Y-axes with different scales creating false correlation). Numbers don't match between chart and narrative. Caveats absent.",
+        "1": "Inaccurate or misleading: Data errors, wrong calculations, intentionally misleading visual encoding (extreme Y-axis truncation, 3D distortion, cherry-picked data). Actively deceives reader."
+      }
+    },
+    {
+      "name": "Context & Benchmarking",
+      "weight": 1.2,
+      "description": "Does the visualization provide context (vs target, history, industry, expectation)?",
+      "levels": {
+        "5": "Rich context: Multiple comparisons provided (vs target, vs last year, vs industry/competitors, vs expectation/seasonality). Makes absolute numbers meaningful. Example: '$2.6M MRR (vs $2.25M target: +15%, vs Q4 2023: +30%, vs industry avg growth 10%: strong, vs typical Q4 seasonality +15%: exceeded).'",
+        "4": "Good context: 2-3 comparisons provided (e.g., vs target and vs last year). Enough to judge significance. Example: '$2.6M MRR (+15% vs $2.25M target, +30% YoY).'",
+        "3": "Some context: 1 comparison provided (e.g., vs target OR vs last year). Gives some sense of significance but limited. Example: '$2.6M MRR (+15% vs target)' (but no sense of historical trend).",
+        "2": "Minimal context: Vague comparison ('above average', 'growing') without specifics. Doesn't help judge significance much. Example: '$2.6M MRR (up from last quarter)' (by how much?).",
+        "1": "No context: Absolute numbers only ('$2.6M MRR'). No comparison, no sense of whether this is good/bad, improving/declining. Numbers exist in vacuum."
+      }
+    },
+    {
+      "name": "Accessibility",
+      "weight": 1.1,
+      "description": "Is the visualization accessible (colorblind-safe, alt text, sufficient contrast, patterns)?",
+      "levels": {
+        "5": "Fully accessible: Colorblind-safe palette (tested with simulator, or uses blue-orange not red-green). Alt text provided describing insight (not just 'chart'). Sufficient contrast (4.5:1+ for text, distinguishable lines/colors). Patterns in addition to color for critical distinctions (dashed/solid lines, hatched fills). Readable in black & white. Keyboard navigable (if interactive).",
+        "4": "Accessible: Colorblind-safe palette, alt text present, good contrast, mostly readable in B&W. Patterns used for most critical distinctions. Minor improvements possible.",
+        "3": "Somewhat accessible: Colors okay but not tested for colorblindness (uses blue-red, acceptable but not ideal), alt text generic ('chart of revenue'), adequate contrast, readable in B&W with effort. Patterns absent but colors sufficiently distinct.",
+        "2": "Limited accessibility: Red-green palette (problematic for 8% of men), alt text missing or useless ('image'), low contrast (hard to read), not readable in B&W. No patterns, relies solely on color.",
+        "1": "Inaccessible: Red-green critical distinction, no alt text, very low contrast, unreadable in B&W, relies on color alone for all meaning. Excludes colorblind and visually impaired users."
+      }
+    },
+    {
+      "name": "Audience Appropriateness",
+      "weight": 1.2,
+      "description": "Is the visualization tailored to the target audience's expertise, goals, and time constraints?",
+      "levels": {
+        "5": "Perfect fit: Complexity matches audience expertise (simple for execs, detailed for analysts). Addresses audience's primary goal (decision-makers get options/trade-offs, implementers get how-to, learners get understanding). Respects time constraints (execs: 1 screen no scrolling, analysts: drill-downs available). Medium appropriate (dashboard for monitoring, slide for presentation, static image for email).",
+        "4": "Good fit: Mostly tailored. Complexity appropriate, addresses goal, respects time mostly. Minor mismatches (e.g., slightly too detailed for exec, or slightly too simple for analyst).",
+        "3": "Acceptable fit: Somewhat tailored. Complexity okay, addresses goal partially, time constraints somewhat respected. Example: Exec dashboard with 2 screens (should be 1), or analyst dashboard without drill-downs.",
+        "2": "Poor fit: Mismatched. Too complex for audience or too simple. Doesn't address their goal (shows what they don't care about, omits what they do). Disrespects time (exec dashboard with 5 screens requiring scrolling).",
+        "1": "Wrong audience: Completely inappropriate. Technical deep-dive for exec (too complex), or high-level summary for analyst (too simple). Ignores audience goals and constraints."
+      }
+    },
+    {
+      "name": "Overall Visualization Quality",
+      "weight": 1.3,
+      "description": "Holistic assessment: Does this visualization effectively answer the question and drive action?",
+      "levels": {
+        "5": "Exceptional: Chart clearly answers question, insight obvious, narrative compelling, actions clear, design polished, accessible, appropriate for audience. Reader can extract insight in seconds and knows exactly what to do next. Professional-grade work. Example of best practices.",
+        "4": "Strong: Chart answers question well, insight clear, narrative solid, actions specific, design good, mostly accessible, fits audience. Minor improvements possible but overall high quality. Would be confident presenting to stakeholders.",
+        "3": "Adequate: Chart answers question, insight present but requires work to extract, narrative has most elements, actions somewhat vague, design acceptable, accessibility okay, audience fit decent. Gets the job done but not polished. Needs refinement before high-stakes presentation.",
+        "2": "Weak: Chart doesn't clearly answer question, insight buried, narrative incomplete, actions vague, design poor, accessibility limited, audience mismatch. Needs significant rework. Would not present as-is.",
+        "1": "Ineffective: Chart doesn't answer question, no clear insight, no narrative or actions, design problematic, inaccessible, wrong for audience. Does not achieve communication goal. Start over with different approach."
+      }
+    }
+  ],
+  "guidance": {
+    "visualization_context": {
+      "executive_dashboard": "Prioritize Insight Clarity (1.4x, must be obvious in 5 seconds), Narrative Quality (1.5x, lead with headline), Audience Appropriateness (1.2x, simple not complex, 1 screen no scroll). Design (1.4x, clean and polished). Chart Selection (1.5x, simplest chart that works).",
+      "analyst_deep_dive": "Prioritize Accuracy (1.5x, calculations correct, source cited), Chart Selection (1.5x, optimal for question), Design (1.4x, detailed but organized). Actionability (1.3x, investigation paths clear). Accessibility less critical if internal-only.",
+      "stakeholder_report": "Prioritize Narrative Quality (1.5x, complete story), Context (1.2x, multiple benchmarks), Insight Clarity (1.4x, takeaway obvious), Actionability (1.3x, specific next steps), Audience Appropriateness (1.2x, addresses stakeholder goals).",
+      "monitoring_dashboard": "Prioritize Insight Clarity (1.4x, signal obvious at glance), Design (1.4x, traffic lights, bullet charts, scorecard), Accuracy (1.5x, real-time data correct), Actionability (1.3x, alerts trigger actions). Update timestamp critical.",
+      "presentation": "Prioritize Insight Clarity (1.4x, audience sees pattern instantly), Narrative Quality (1.5x, compelling story), Design (1.4x, polished aesthetics), Audience Appropriateness (1.2x, appropriate detail level for room)."
+    },
+    "chart_type_guidance": {
+      "line_chart": "Ensure temporal axis is clear (consistent intervals, labeled), annotate key events, multiple series distinguishable (color + direct labels preferred over legend). For trend questions.",
+      "bar_chart": "Y-axis must start at zero (avoids exaggerating differences). Use horizontal bars for long category names. For comparison questions.",
+      "scatter_plot": "Add regression line if showing correlation. Label outliers. Size/color encode additional dimensions if relevant. For relationship questions.",
+      "pie_chart": "Limit to 2-5 slices (more → use bar chart). Only when part-to-whole is key message. Often bar chart is better choice. For composition questions.",
+      "heatmap": "Use sequential (light→dark) or diverging (blue→white→red) color scale. Sort rows/columns to reveal patterns. For matrix/multivariate questions.",
+      "map": "Choose choropleth (regions) vs bubble (points) based on data. Beware large area bias (Wyoming looks big but low population). For geographic questions.",
+      "dashboard": "F-pattern layout (top-left most important). 5-8 elements max for exec, 10-15 for analyst. Consistent color scheme throughout. For monitoring/overview questions."
+    },
+    "minimum_thresholds": {
+      "critical_criteria": "Chart Selection ≥3 (must match question type), Accuracy ≥3 (must be truthful, not misleading), Insight Clarity ≥3 (must have clear takeaway). If any <3, visualization fundamentally flawed.",
+      "overall_average": "Must be ≥3.5 across applicable criteria before delivering. Higher threshold (≥4.0) for high-stakes presentations (board, exec, external stakeholders).",
+      "accessibility_threshold": "For public-facing or legally required accessible content, Accessibility must be ≥4 (colorblind-safe, alt text, contrast, patterns)."
+    }
+  },
+  "common_failure_modes": {
+    "wrong_chart_type": "Chart Selection: 1-2. Example: Pie chart with 8 slices (angles hard to compare). Fix: Use horizontal bar chart (position on common scale more accurate). Or line chart for categorical data (implies false continuity). Fix: Use bar chart for discrete categories.",
+    "misleading_scale": "Accuracy: 1-2, Design: 1-2. Example: Bar chart with Y-axis starting at 950 instead of 0, exaggerating small differences. Fix: Start Y-axis at zero for bar/column charts. Or dual Y-axes with different scales creating false correlation. Fix: Use small multiples with consistent scales or index to 100.",
+    "no_insight": "Insight Clarity: 1-2, Narrative: 1-2. Example: Title 'Revenue by Month', no annotation, no interpretation. Reader sees chart but doesn't know what to conclude. Fix: Insight-first title ('Revenue Up 30% YoY, Driven by Enterprise'), annotate key patterns, provide narrative (Headline → Pattern → Context → Meaning → Action).",
+    "chart_junk": "Design: 1-2. Example: 3D pie chart with gradients, background image, heavy gridlines. Distorts values, slows comprehension, looks unprofessional. Fix: Remove 3D, gradients, background images. Use 2D chart, muted gridlines (light gray), white space.",
+    "no_context": "Context: 1-2, Narrative: 1-2. Example: '$2.6M revenue' (vs what? good or bad?). Fix: Add benchmark ('$2.6M, +15% vs $2.25M target, +30% YoY, vs industry avg +10%: strong').",
+    "vague_actions": "Actionability: 1-2. Example: 'We should monitor this', 'Consider improvements', 'Look into it'. Too vague to execute. Fix: Specific actions ('Hire 2 Enterprise AEs by Q1 (Hiring Manager), interview 10 churned SMB customers by Dec 15 (PM), monitor Enterprise win rate weekly').",
+    "wrong_audience": "Audience Appropriateness: 1-2. Example: 5-screen dashboard with technical drill-downs for exec (too complex, too long). Or high-level summary for analyst (too simple, no detail). Fix: Tailor complexity and length to audience (exec: 1 screen simple, analyst: 2-3 screens with detail).",
+    "colorblind_issues": "Accessibility: 1-2. Example: Red-green distinction critical but 8% of men are red-green colorblind. Fix: Use blue-orange palette instead, or add patterns (dashed/solid lines, hatched fills) in addition to color.",
+    "no_narrative": "Narrative: 1-2, Actionability: 1-2. Example: Chart with data but no story. Just description ('this shows revenue by month'). Fix: Apply Headline → Pattern → Context → Meaning → Action framework. Tell the story: what happened, why it matters, what to do."
+  }
+}

skills/visualization-choice-reporting/resources/methodology.md

@@ -0,0 +1,350 @@
+# Advanced Visualization Methodology
+
+This document covers advanced techniques for complex visualization scenarios: dashboards, multivariate data, interactive charts, specialized domains, and sophisticated narrative structures.
+
+---
+
+## 1. Dashboard Design Principles
+
+### Layout Patterns
+
+**F-Pattern Layout:** Users scan top-left → top-right → down-left side. Place most important KPIs top-left.
+
+**Inverted Pyramid:** Summary → Details → Deep Dive
+- **Level 1 (top):** Key metrics (3-5 big numbers with trend indicators)
+- **Level 2 (middle):** Supporting charts (2-4 visualizations showing drivers)
+- **Level 3 (bottom):** Detailed tables/drill-downs (for exploration)
+
+**Small Multiples Grid:** Same chart type repeated for each category with consistent scales
+- Enables quick comparison across categories
+- Example: 6 line charts showing MRR trend for each product line, same Y-axis scale
+
+**Dashboard Sizing:**
+- **Executive dashboard:** 1 screen, no scrolling, 5-8 total elements
+- **Analyst dashboard:** 2-3 screens, deep drill-downs, 10-15 elements
+- **Monitoring dashboard:** Real-time, auto-refresh, 6-12 key metrics
+
+### Dashboard Elements
+
+**Scorecard (Big Number):**
+```
+  +----------------------+
+  |   MRR: $2.6M        |
+  |   ↑ 15% vs target   |
+  |   ▲ 30% YoY         |
+  +----------------------+
+```
+- One metric, large font
+- Trend arrow (↑↓) and % change
+- Color: green (good), red (bad), yellow (caution)
+
+**Bullet Chart:** Performance vs target
+```
+Revenue:  ▓▓▓▓▓▓▓▓▓░  $2.6M (target: $2.25M)
+          ├──────┼──────┤
+          Poor  Good  Excellent
+```
+- Actual (dark bar), target (line), range bands (poor/good/excellent)
+
+**Traffic Light Indicators:**
+| Metric | Status | Value | Trend |
+|--------|--------|-------|-------|
+| MRR | 🟢 | $2.6M | ↑ 30% |
+| Churn | 🔴 | 8% | ↑ 2pp |
+| CAC | 🟡 | $450 | ↔ 0% |
+
+### Dashboard Best Practices
+
+✓ **Consistent color scheme:** One palette throughout (e.g., blue for primary metric, gray for secondary)
+✓ **Alignment:** Grid-based layout, elements aligned to invisible grid
+✓ **White space:** Don't cram; use spacing to group related elements
+✓ **Update timestamp:** "Last updated: 2024-11-14 10:30 AM" visible
+✓ **Interactivity (if web):** Filters (date range, segment), drill-downs, tooltips
+
+❌ **Too many colors:** Confusing, no hierarchy
+❌ **Misaligned elements:** Looks unprofessional
+❌ **No context:** "$2.6M" alone (vs what?)
+❌ **Stale data:** No timestamp, user doesn't know if current
+
+---
+
+## 2. Advanced Chart Types
+
+**Small Multiples:** Same chart repeated in grid with consistent scales. Best for comparing metric across >4 categories. Max 12 charts; use consistent Y-scale. Example: Revenue trend for 12 product lines in 3x4 grid.
+
+**Sparklines:** Tiny inline charts in tables (no axes). Shows trend shape at a glance. Example: Table with "Trend" column showing ▁▂▃▅▆▇█ for each product.
+
+**Horizon Chart:** Space-efficient time series using color intensity layers instead of Y-height. For 20+ metrics in limited space.
+
+**Connected Scatter:** Scatter plot with points connected in time order. Shows X-Y relationship evolving. Example: Revenue vs Profit by quarter (Q1→Q2→Q3→Q4).
+
+**Hexbin:** Dense scatter (1000s+ points) using hexagon grid colored by density. Avoids overlapping dots.
+
+**Alluvial Diagram:** Flow between states over time. Bands show entity movement. Example: User tier transitions (Free→Pro→Enterprise) across quarters.
+
+---
+
+## 3. Multivariate Visualization Techniques
+
+**Scatter Plot Matrix (SPLOM):** N×N grid of scatter plots for 3-5 numerical variables. Each cell = relationship between row/column variable. Example: 4 variables (MRR, Churn, CAC, LTV) = 4×4 grid.
+
+**Parallel Coordinates:** Vertical axes for each variable, entities as lines connecting values. Compare 20+ entities across 5-15 dimensions. Brush/filter one axis to highlight lines.
+
+**Heatmap Matrix:** Rows × Columns = Categories, cell color = metric. Example: Features × Segments, color = usage %. Use sequential (light→dark) or diverging (blue→white→red) scales. Sort by similarity to reveal patterns.
+
+**Bubble Chart:** 4D (X, Y, size, color). Example: Products (X: revenue, Y: margin, size: customers, color: category). Limit to <20 bubbles; label them.
+
+---
+
+## 4. Statistical Overlays
+
+**Regression Lines:** Linear/log/polynomial trend in scatter. Annotate R²: "R² = 0.85 (strong correlation)". Distinct color from points.
+
+**Confidence Intervals:** Shaded band (forecast uncertainty) or error bars (mean ± SE). Example: 95% CI band around forecast line.
+
+**Distribution Overlays:** Histogram + normal curve (actual vs expected), Box plot + strip plot (quartiles + individual points).
+
+---
+
+## 5. Geographic Visualization
+
+**Choropleth:** Filled regions (states/countries) colored by metric. Sequential (light→dark) or diverging (blue→white→red) scales. Pitfall: Large areas dominate; fix with cartogram or bubble map.
+
+**Bubble Map:** Precise locations with size = metric, color = category. Limit <100 bubbles; use clustering for density.
+
+**Flow Map:** Origin-destination lines, width = volume. For shipping, migration, traffic flows.
+
+---
+
+## 6. Hierarchical & Network Visualization
+
+**Treemap:** Nested rectangles, size = metric, nesting = hierarchy levels. Click to drill down. Example: Revenue by category → product.
+
+**Sunburst:** Radial treemap (center = root, rings = levels). More compact for deep hierarchies (4+ levels).
+
+**Dendrogram:** Tree diagram for clustering/hierarchy. Example: Customer segmentation tree.
+
+**Network Graph:** Nodes & edges for relationships. Force-directed (organic clustering) or hierarchical (directed A→B→C) layout. Limit <100 nodes; node size = importance, edge width = strength.
+
+---
+
+## 7. Color Theory & Accessibility
+
+### Color Scales
+
+**Sequential (Single Hue):** Light blue → Dark blue
+- For: One metric, low to high
+- Examples: Revenue, count, usage
+
+**Diverging (Two Hues):** Blue → White → Red
+- For: Metric with meaningful midpoint (zero, average, neutral)
+- Examples: Profit/loss, vs target, sentiment
+
+**Categorical (Distinct Hues):** Blue, Orange, Green, Purple
+- For: Discrete categories with no order
+- Limit: 5-7 colors (more requires legend lookup)
+
+### Colorblind-Safe Palettes
+
+**Common types:**
+- Red-green colorblindness (8% of men)
+- Blue-yellow colorblindness (rare)
+
+**Safe combinations:**
+- Blue + Orange (most common alternative)
+- Blue + Red (okay)
+- Avoid: Red + Green alone
+
+**Tools:** Use simulators (Color Oracle) to test designs
+
+### Accessibility Checklist
+
+- [ ] Color contrast ≥4.5:1 for text (WCAG AA)
+- [ ] Don't rely on color alone (add patterns, labels, shapes)
+- [ ] Alt text describes insight ("Revenue grew 30%, driven by Enterprise")
+- [ ] Interactive charts keyboard-navigable (tab, arrow keys)
+- [ ] Legends positioned near data (reduce eye movement)
+
+---
+
+## 8. Interactive Visualization Patterns
+
+**Filtering:** Dropdown (select one), multi-select (check multiple), date slider (range), cross-filter (click element filters other charts).
+
+**Drill-Down:** Click element to see breakdown. Breadcrumb navigation (Revenue > Product A > Feature X).
+
+**Tooltip:** Hover detail (exact value, context, metadata). Position near cursor, contrasting background, 2-4 lines max.
+
+**Brushing & Linking:** Select range on one chart updates others. Reveals cross-chart patterns.
+
+---
+
+## 9. Animation & Temporal Visualization
+
+### Animated Transitions
+
+**When:** Show change over time (especially for presentations)
+
+**Example:** Bar chart race (ranks change month-by-month)
+
+**Best practices:**
+- Pause controls (don't force auto-play through)
+- Slow enough to follow (1-2 seconds per frame)
+- Label current time period prominently
+
+### Before/After Comparison
+
+**Slope chart:** Show change for each entity
+- Left: Before values
+- Right: After values
+- Lines connect (slope = change)
+
+**Dumbbell chart:** Like slope but horizontal
+- Good for long category names
+
+---
+
+## 10. Domain-Specific Patterns
+
+### SaaS Metrics Dashboard
+
+**Key charts:**
+- MRR trend (line chart)
+- MRR by source (stacked area: new, expansion, churn)
+- Cohort retention (heatmap: cohort × month, color = retention %)
+- Funnel (inverted pyramid: leads → trials → paid)
+
+### Financial Reporting
+
+**P&L Waterfall:**
+- Start: Revenue (bar)
+- Subtract: COGS, OpEx (negative bars)
+- End: Net Income (bar)
+- Shows cumulative effect
+
+**Variance Analysis:**
+- Grouped bar: Actual vs Budget vs Last Year
+- Or diverging bar: (Actual - Budget), color by +/-
+
+### A/B Test Results
+
+**Forest plot (Confidence Intervals):**
+- Y-axis: Metrics
+- X-axis: Effect size (treatment vs control)
+- Points: Estimate
+- Error bars: 95% CI
+- Vertical line at zero (no effect)
+
+**Statistical annotation:**
+- "Conversion: +2.5% (95% CI: +1.2% to +3.8%), p<0.01"
+
+### Operational Monitoring
+
+**Status timeline:**
+- X-axis: Time
+- Y-axis: System/service
+- Color: Status (green, yellow, red)
+- Shows uptime/downtime patterns
+
+**Percentile charts:**
+- Line chart: P50, P90, P99 response times over time
+- Shows not just average but tail latency
+
+---
+
+## 11. Advanced Narrative Techniques
+
+### Multi-Chart Storytelling
+
+**Progression:** Question → Evidence → Conclusion
+- Chart 1: "Revenue growing, but is it sustainable?"
+- Chart 2: "New customer acquisition slowing (trend down)"
+- Chart 3: "But expansion revenue from existing customers up 40%"
+- Conclusion: "Growth shifting from acquisition to expansion; prioritize customer success"
+
+**Guided annotations:**
+- Progressive reveal: Show chart 1, then annotate with insight, then show chart 2
+- Highlight sequence: Circle region A → zoom in → annotate → circle region B
+
+### Scenario Comparison
+
+**Pattern:** Base case vs Alternative scenarios on same chart
+- Line chart: Actual (solid) + Forecast scenarios (dashed: optimistic, base, pessimistic)
+- Annotate assumptions for each scenario
+
+**Fan chart:** Uncertainty grows over time
+- Shaded bands widen into future (50% CI, 90% CI)
+
+### Insight Layering
+
+**Layer 1 (Surface):** "Revenue up 30%"
+**Layer 2 (Decomposition):** "Driven by Enterprise (+120%), SMB declined (-10%)"
+**Layer 3 (Root cause):** "Enterprise: new product launched Q2. SMB: pricing too high for segment"
+**Layer 4 (Action):** "Double Enterprise sales hiring; test SMB annual plans to reduce churn"
+
+---
+
+## 12. Tools & Implementation
+
+**Python:** Matplotlib (basic, full control), Seaborn (statistical, better defaults), Plotly (interactive), Altair (declarative, concise).
+
+**BI Tools:** Tableau (drag-and-drop, dashboards), Power BI (Microsoft, Excel integration), Looker (SQL, data governance), Metabase (open-source).
+
+**Presentation:** Excel/Sheets (quick), Slides/PowerPoint (static), Observable (interactive D3.js notebooks).
+
+---
+
+## 13. Quality Assurance Checklist
+
+Before publishing any visualization:
+
+**Accuracy**
+- [ ] Data source is credible and recent
+- [ ] Calculations are correct (spot-check numbers)
+- [ ] No misleading scales (Y-axis starts at zero for bar charts)
+- [ ] Outliers investigated (real or data error?)
+
+**Clarity**
+- [ ] Chart type matches question (trend→line, comparison→bar, etc.)
+- [ ] Title is insight-first headline
+- [ ] Axes labeled with units
+- [ ] Legend clear (or direct labels used)
+- [ ] Annotations explain key patterns
+
+**Aesthetic**
+- [ ] Colorblind-safe palette
+- [ ] Sufficient contrast
+- [ ] No chart junk (3D, gradients, heavy gridlines)
+- [ ] Aligned elements (grid-based layout)
+- [ ] White space used effectively
+
+**Actionability**
+- [ ] Narrative interprets pattern (not just describes)
+- [ ] Context provided (vs benchmark/target/history)
+- [ ] Actions recommended (specific, feasible, assigned)
+
+**Accessibility**
+- [ ] Alt text describes insight
+- [ ] Keyboard navigable (if interactive)
+- [ ] Readable in black & white (test print)
+
+---
+
+## 14. Further Reading
+
+**Books:**
+- "Storytelling with Data" by Cole Nussbaumer Knaflic (chart choice, decluttering, narrative)
+- "The Visual Display of Quantitative Information" by Edward Tufte (principles, data-ink ratio)
+- "Show Me the Numbers" by Stephen Few (dashboard design, perceptual principles)
+- "The Truthful Art" by Alberto Cairo (accuracy, ethics, statistical graphics)
+
+**Online Resources:**
+- Flowing Data (blog on visualization techniques)
+- Information is Beautiful (examples of creative visualizations)
+- PolicyViz (public policy and data visualization)
+- D3.js Gallery (interactive web visualization examples)
+
+**Color Tools:**
+- ColorBrewer (cartography color schemes, colorblind-safe)
+- Color Oracle (colorblind simulator)
+- Coolors (palette generator)

skills/visualization-choice-reporting/resources/template.md

@@ -0,0 +1,346 @@
+# Visualization Choice & Reporting Template
+
+Use this template to systematically choose the right chart and create a narrated report with insights and actions.
+
+---
+
+## Section 1: Question & Goal Clarification
+
+**What question are you answering?**
+
+[Be specific. Not "analyze revenue" but "How has revenue trended over the past year, and what's driving changes?"]
+
+**Question type (check one):**
+- [ ] Trend (How has X changed over time?)
+- [ ] Comparison (How do categories compare?)
+- [ ] Distribution (What's the spread/frequency of X?)
+- [ ] Relationship (How do X and Y relate?)
+- [ ] Composition (What are the parts of X?)
+- [ ] Geographic (Where is X happening?)
+- [ ] Hierarchical (What's the structure of X?)
+- [ ] Multivariate (How do many variables interact?)
+
+**Audience:**
+- [ ] Executive (wants insights + actions, simple charts)
+- [ ] Analyst (wants details, can handle complexity)
+- [ ] General stakeholder (needs context, moderate detail)
+- [ ] Technical (understands domain, wants precision)
+
+**Context/Constraints:**
+- Time they have: [e.g., 5 minutes to review, 30-minute presentation]
+- Medium: [e.g., email, dashboard, slide deck, printed report]
+- Key concern: [e.g., hitting targets, understanding root cause, making decision]
+
+---
+
+## Section 2: Data Profiling
+
+**Data source:**
+
+[Where is the data from? Database, CSV, API, manual collection?]
+
+**Time period covered:**
+
+[e.g., Jan-Dec 2024, Q1-Q4 2024, last 30 days]
+
+**Granularity:**
+
+[e.g., daily, weekly, monthly, by user, by transaction, aggregated]
+
+**Data types (for each variable):**
+
+| Variable | Type | Example Values | Notes |
+|----------|------|----------------|-------|
+| [e.g., Date] | Temporal | 2024-01-01 to 2024-12-31 | Monthly aggregates |
+| [e.g., Segment] | Categorical | Enterprise, SMB | 2 categories |
+| [e.g., Revenue] | Numerical | $1.5M - $2.6M | Continuous, dollar amounts |
+
+**Dimensions:**
+- [ ] 1D (single metric over time or categories)
+- [ ] 2D (X vs Y, or metric by category)
+- [ ] 3D+ (multiple metrics, multiple categories, time)
+
+**Data size:**
+
+[e.g., 24 rows (2 segments × 12 months), 10K transactions, 150 countries]
+
+**Data quality notes:**
+
+[Any missing data, outliers, anomalies to be aware of?]
+
+---
+
+## Section 3: Chart Selection
+
+**Matched chart family (based on question type from Section 1):**
+
+[From Chart Selection Guide in SKILL.md - e.g., "Trend → Line chart"]
+
+**Specific chart type selected:**
+
+[e.g., Multi-line chart, Horizontal bar chart, Scatter plot with regression]
+
+**Rationale:**
+
+Why this chart?
+- **Question fit:** [How does this chart answer the question type?]
+- **Data fit:** [How does it handle your data dimensions, size, types?]
+- **Audience fit:** [Why is this appropriate for your audience's expertise/time?]
+
+Example rationale:
+> "Multi-line chart selected because:
+> - Question: Trend over time (perfect for line charts)
+> - Data: 2 categorical series × 12 time periods × 1 metric (line handles multiple series well)
+> - Audience: Executives need to see trend at a glance; lines show rate of change clearly; annotations highlight key events"
+
+**Alternatives considered (and why rejected):**
+
+| Alternative Chart | Why Not Selected |
+|-------------------|------------------|
+| [e.g., Stacked area] | Would obscure individual segment trends; focus is on comparison not cumulative total |
+| [e.g., Table] | Doesn't show trend visually; requires more cognitive effort to spot patterns |
+
+---
+
+## Section 4: Visualization Design
+
+**Essential elements:**
+
+- **Title (insight headline):** [Not "Revenue by Month" but "Revenue Up 30% YoY, Driven by Enterprise Segment"]
+
+- **Axes:**
+  - X-axis: [Label with units, e.g., "Month (2024)"]
+  - Y-axis: [Label with units, e.g., "Revenue ($M)"]
+  - Start Y at zero? [ ] Yes (for bar/column) [ ] No (for line, if range is narrow and zero isn't meaningful)
+
+- **Legend/Labels:**
+  - [ ] Direct labels on chart (preferred - easier to read)
+  - [ ] Legend (if direct labels clutter)
+  - Position: [e.g., right of chart, below chart, inline]
+
+- **Annotations:**
+  - [ ] Key event 1: [e.g., Arrow at May 2024: "Product launch"]
+  - [ ] Key event 2: [e.g., Shaded region Oct-Dec: "Enterprise sales push"]
+  - [ ] Threshold line: [e.g., Horizontal line at $2.25M: "2024 target"]
+  - [ ] Callout: [e.g., Label on peak: "Q4 high: $2.6M"]
+
+- **Colors:**
+  - Primary palette: [e.g., Blue (Enterprise), Orange (SMB)]
+  - Colorblind-safe? [ ] Yes [ ] No (if no, add patterns)
+  - Purpose: [e.g., Blue/orange are distinguishable for red-green colorblindness]
+
+- **Data source & timestamp:**
+  - [e.g., "Source: Analytics DB, as of 2024-11-14"]
+
+**Perceptual best practices applied:**
+
+- [ ] Use position (most accurate) over angle/area where possible
+- [ ] Remove chart junk (no 3D, no gradients, no heavy gridlines)
+- [ ] Mute non-data ink (light gray gridlines, thin axes)
+- [ ] Limit colors to 5-7 distinct hues
+- [ ] Use pre-attentive attributes (color, size, position) to highlight signal
+
+**Accessibility:**
+
+- [ ] Alt text provided: [Describe the insight: "Line chart showing revenue grew from $2M to $2.6M (30% increase) Q1-Q4 2024, with Enterprise segment contributing 80% of growth."]
+- [ ] Sufficient contrast (text readable, lines distinguishable)
+- [ ] Patterns in addition to color (if critical - dashed/solid lines, hatched fills)
+
+**Chart specification:**
+
+[Provide detailed spec, code, or embed image]
+
+Example spec:
+- Chart type: Multi-line chart
+- X-axis: Month (Jan, Feb, ..., Dec 2024)
+- Y-axis: Revenue ($M), range $0-$3M, gridlines every $0.5M
+- Series 1 (blue solid line): Enterprise revenue
+- Series 2 (orange solid line): SMB revenue
+- Annotations:
+  - Arrow at May: "Product launch"
+  - Shaded region Oct-Dec (light gray): "Enterprise initiative"
+  - Horizontal dashed line at $2.25M (gray): "2024 target"
+- Direct labels: "Enterprise" at end of blue line, "SMB" at end of orange line
+- Source note: "Source: Analytics DB, as of 2024-11-14" (bottom right, small gray text)
+
+---
+
+## Section 5: Narrative Development
+
+Use the **Headline → Pattern → Context → Meaning → Action** framework:
+
+### 5.1 Headline (Insight-first one-liner)
+
+[Not: "This chart shows monthly revenue." But: "Revenue grew 30% YoY, driven by Enterprise segment."]
+
+**Your headline:**
+
+[Write a single sentence that captures the key insight someone should take away from this visualization]
+
+### 5.2 Pattern (What do you see?)
+
+Describe the visual pattern in the data:
+- Trends: [e.g., "Q1-Q2 flat at $2M/month, then steady climb to $2.6M in Q4"]
+- Comparisons: [e.g., "Enterprise grew 120% while SMB declined 10%"]
+- Outliers: [e.g., "August spike to $2.8M due to one-time deal"]
+- Distributions: [e.g., "Most transactions $50-$200, with long tail to $10K"]
+
+**Your pattern description:**
+
+[2-3 sentences describing what you observe in the chart]
+
+### 5.3 Context (Compared to what?)
+
+Provide benchmarks, targets, historical comparison, or industry standards:
+- vs Target: [e.g., "15% above $X plan"]
+- vs Last period: [e.g., "Q4 2023 was $2.0M, now $2.6M"]
+- vs Industry: [e.g., "Our 30% growth vs 10% industry average"]
+- vs Expectation: [e.g., "Seasonality suggests Q4 boost, but this exceeded typical 15% bump"]
+
+**Your context:**
+
+[What makes this pattern significant? What are you comparing against?]
+
+### 5.4 Meaning (Why does it matter?)
+
+Interpret what the pattern + context implies:
+- Implications: [e.g., "Suggests product-market fit in Enterprise"]
+- Diagnosis: [e.g., "SMB churn indicates pricing mismatch"]
+- Forecast: [e.g., "If sustained, Q1 2025 could hit $3M/month"]
+- Risk/Opportunity: [e.g., "Enterprise now 58% of revenue, reducing diversification"]
+
+**Your interpretation:**
+
+[1-2 sentences explaining what this means for the business/product/team]
+
+### 5.5 Actions (What should we do?)
+
+Recommend specific next steps with:
+- Priority actions: [What to do first, with owners/deadlines if possible]
+- Investigations: [What to dig into to understand better]
+- Monitoring: [What metrics to track going forward]
+
+**Format:**
+1. **Prioritize:** [Action with owner/timeline]
+2. **Fix/Investigate:** [Action with owner/timeline]
+3. **Monitor:** [Metrics to track]
+
+**Your actions:**
+
+1. **Prioritize:**
+
+2. **Fix/Investigate:**
+
+3. **Monitor:**
+
+---
+
+## Section 6: Full Narrative (Assembled)
+
+Combine Sections 5.1-5.5 into a coherent narrative:
+
+**Your complete narrative:**
+
+> **Headline:** [From 5.1]
+>
+> **Pattern:** [From 5.2]
+>
+> **Context:** [From 5.3]
+>
+> **Meaning:** [From 5.4]
+>
+> **Actions:**
+> 1. [From 5.5]
+> 2. [From 5.5]
+> 3. [From 5.5]
+
+---
+
+## Section 7: Validation Checklist
+
+Before delivering, self-check with these criteria:
+
+**Clarity**
+- [ ] Chart type clearly matches question type
+- [ ] Insight headline is clear and specific (not generic)
+- [ ] Axes labeled with units
+- [ ] Legend/labels easy to read
+- [ ] Source and timestamp provided
+
+**Accuracy**
+- [ ] Y-axis scale appropriate (starts at zero for bar/column, appropriate range for line)
+- [ ] No misleading visual distortions (no 3D, no truncated axes that exaggerate)
+- [ ] Data source credible and cited
+- [ ] Numbers in narrative match chart
+- [ ] Caveats noted (if any data quality issues, assumptions, or limitations)
+
+**Insight**
+- [ ] Pattern clearly described (not just "revenue increased" but specifics)
+- [ ] Context provided (vs benchmark, target, or history)
+- [ ] Meaning interpreted (why it matters, what it implies)
+- [ ] Insight is non-obvious (not just reading chart, but adding interpretation)
+
+**Actionability**
+- [ ] Specific next steps recommended (not vague "we should look into this")
+- [ ] Actions have owners/timelines (or at least clear enough to assign)
+- [ ] Actions are feasible given context
+- [ ] Monitoring metrics defined
+
+**Accessibility**
+- [ ] Colorblind-safe palette (or patterns added)
+- [ ] Alt text describes the insight
+- [ ] Sufficient contrast
+- [ ] Chart readable in black & white (test if printing)
+
+**If any critical criteria fail (Clarity, Accuracy, Insight, Actionability < 3/5), revise before delivering.**
+
+---
+
+## Section 8: Delivery Package
+
+Create `visualization-choice-reporting.md` with these sections:
+1. Question (from Section 1)
+2. Data Summary (source, period, granularity, dimensions, size from Section 2)
+3. Visualization (chart type, rationale, design decisions, spec from Sections 3-4)
+4. Narrative (complete narrative from Section 6)
+5. Validation (self-check with rubric from Section 7)
+6. Appendix (optional: raw data, alternatives, tests, caveats)
+
+---
+
+## Examples of Common Scenarios
+
+| Scenario | Question Example | Chart Type | Narrative Focus | Design Notes |
+|----------|------------------|------------|-----------------|--------------|
+| **Executive Dashboard** | How has MRR trended this quarter? | Line chart | % change, context vs target, 1-2 actions | Clean, minimal annotations, insight-first title |
+| **Analyst Deep-Dive** | Does marketing spend correlate with conversions? | Scatter + regression | Correlation strength, outliers, significance | R² annotated, outliers labeled, confidence interval |
+| **Stakeholder Report** | Which product lines growing/declining? | Horizontal bar (ranked) | Top 3 growers/decliners, portfolio implications | Color-coded (green/red), percentages labeled |
+| **Monitoring Dashboard** | How are key SaaS metrics trending? | Small multiples | Traffic light summary, items needing attention | Consistent scales, sparklines, RAG status |
+
+---
+
+## Common Pitfalls & Fixes
+
+**Pitfall:** Chart doesn't answer the question (e.g., table when trend is the question)
+**Fix:** Go back to Section 3, match question type to chart family
+
+**Pitfall:** Title is descriptive not insightful ("Revenue by Month")
+**Fix:** Lead with the insight ("Revenue Up 30% YoY")
+
+**Pitfall:** No context, just absolute numbers ("Revenue is $2.6M")
+**Fix:** Add benchmark ("$2.6M, 15% above $2.25M target")
+
+**Pitfall:** Pattern without meaning ("Revenue increased")
+**Fix:** Interpret ("Revenue up 30% suggests Enterprise PMF")
+
+**Pitfall:** No actions, ends with observation
+**Fix:** Recommend specific next steps (hire, investigate, monitor)
+
+**Pitfall:** Chart is cluttered (too many colors, gridlines, decorations)
+**Fix:** Remove chart junk, mute non-data ink, use white space
+
+**Pitfall:** Misleading scale (truncated Y-axis on bar chart)
+**Fix:** Start Y at zero for bar/column charts
+
+**Pitfall:** Pie chart with 8 slices
+**Fix:** Use horizontal bar chart (position more accurate than angle)