Initial commit

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)