gh-lyndonkl-claude/skills/visualization-choice-reporting/resources/template.md

# 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)