@booklib/core 2.0.0

package/skills/spring-boot-in-action/scripts/review.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""
+review.py — Pre-analysis script for Spring Boot in Action reviews.
+Usage: python review.py <file.java|application.properties|application.yml>
+
+Scans Spring Boot source files for anti-patterns from the book:
+field injection, hardcoded credentials, missing ResponseEntity, auto-config
+fighting, wrong test annotations, missing Actuator security, and ddl-auto=create.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+
+JAVA_CHECKS = [
+    (
+        r"@Autowired\s*\n\s*(private|protected)",
+        "Ch 2: Field injection (@Autowired on field)",
+        "use constructor injection — fields with @Autowired are not testable without Spring context",
+    ),
+    (
+        r"DriverManagerDataSource|BasicDataSource|HikariDataSource",
+        "Ch 2/3: Manual DataSource bean",
+        "delete this bean and set spring.datasource.* in application.properties — Boot auto-configures HikariCP",
+    ),
+    (
+        r"orElse\(null\)",
+        "Ch 2: orElse(null) returns null to client",
+        "use .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND)) or .map(ResponseEntity::ok).orElse(ResponseEntity.notFound().build())",
+    ),
+    (
+        r'setPassword\s*\(\s*"[^"$][^"]*"',
+        "Ch 3: Hardcoded password",
+        "externalize to environment variable: spring.datasource.password=${DB_PASS}",
+    ),
+    (
+        r'setUsername\s*\(\s*"[^"$][^"]*"',
+        "Ch 3: Hardcoded username",
+        "externalize to environment variable: spring.datasource.username=${DB_USER}",
+    ),
+    (
+        r"new ObjectMapper\(\)",
+        "Ch 2: Manual ObjectMapper construction",
+        "Spring Boot auto-configures Jackson — inject ObjectMapper bean or configure via spring.jackson.* properties",
+    ),
+    (
+        r"@SpringBootTest\b(?!.*WebEnvironment)",
+        "Ch 4: @SpringBootTest without WebEnvironment",
+        "for controller tests use @WebMvcTest; for repository tests use @DataJpaTest; full @SpringBootTest only for integration tests",
+    ),
+    (
+        r"System\.out\.println",
+        "Ch 3: System.out.println instead of logger",
+        "use SLF4J: private static final Logger log = LoggerFactory.getLogger(MyClass.class)",
+    ),
+    (
+        r'@Value\s*\(\s*"\$\{[^}]+\}"\s*\)(?:[\s\S]{0,200}@Value\s*\(\s*"\$\{){2}',
+        "Ch 3: Multiple @Value annotations",
+        "group related config values in a @ConfigurationProperties class with a prefix",
+    ),
+]
+
+PROPERTIES_CHECKS = [
+    (
+        r"ddl-auto\s*=\s*(create|create-drop)(?!\s*#.*test)",
+        "Ch 8: ddl-auto=create or create-drop",
+        "destroys data on restart — use 'validate' in production; use Flyway/Liquibase for migrations",
+    ),
+    (
+        r"management\.endpoints\.web\.exposure\.include\s*=\s*\*",
+        "Ch 7: Actuator exposes all endpoints",
+        "restrict to: management.endpoints.web.exposure.include=health,info — never expose env, beans, or shutdown publicly",
+    ),
+    (
+        r"spring\.security\.user\.password\s*=\s*(?!(\$\{|\s*$))",
+        "Ch 3: Hardcoded security password in properties",
+        "use environment variable: spring.security.user.password=${ADMIN_PASS}",
+    ),
+    (
+        r"datasource\.password\s*=\s*(?!\$\{)(\S+)",
+        "Ch 3: Hardcoded datasource password",
+        "use environment variable: spring.datasource.password=${DB_PASS}",
+    ),
+    (
+        r"datasource\.url\s*=\s*jdbc:[a-z]+://(?!(\$\{|localhost|127\.0\.0\.1))\S+",
+        "Ch 3: Hardcoded production datasource URL",
+        "use environment variable: spring.datasource.url=${DB_URL}",
+    ),
+]
+
+
+def scan_java(source: str) -> list[dict]:
+    findings = []
+    lines = source.splitlines()
+    for lineno, line in enumerate(lines, start=1):
+        if line.strip().startswith("//"):
+            continue
+        for pattern, label, advice in JAVA_CHECKS:
+            if re.search(pattern, line):
+                findings.append({"line": lineno, "text": line.rstrip(), "label": label, "advice": advice})
+    return findings
+
+
+def scan_properties(source: str) -> list[dict]:
+    findings = []
+    lines = source.splitlines()
+    for lineno, line in enumerate(lines, start=1):
+        if line.strip().startswith("#"):
+            continue
+        for pattern, label, advice in PROPERTIES_CHECKS:
+            if re.search(pattern, line):
+                findings.append({"line": lineno, "text": line.rstrip(), "label": label, "advice": advice})
+    return findings
+
+
+def sep(char="-", width=70) -> str:
+    return char * width
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python review.py <file.java|application.properties|application.yml>")
+        sys.exit(1)
+
+    path = Path(sys.argv[1])
+    if not path.exists():
+        print(f"Error: file not found: {path}")
+        sys.exit(1)
+
+    source = path.read_text(encoding="utf-8", errors="replace")
+
+    if path.suffix == ".java":
+        findings = scan_java(source)
+        file_type = "Java"
+    elif path.suffix in (".properties", ".yml", ".yaml"):
+        findings = scan_properties(source)
+        file_type = "Properties/YAML"
+    else:
+        print(f"Warning: unsupported extension '{path.suffix}' — scanning as Java")
+        findings = scan_java(source)
+        file_type = "Unknown"
+
+    groups: dict[str, list] = {}
+    for f in findings:
+        groups.setdefault(f["label"], []).append(f)
+
+    print(sep("="))
+    print("SPRING BOOT IN ACTION — PRE-REVIEW REPORT")
+    print(sep("="))
+    print(f"File   : {path}  ({file_type})")
+    print(f"Lines  : {len(source.splitlines())}")
+    print(f"Issues : {len(findings)} potential anti-patterns across {len(groups)} categories")
+    print()
+
+    if not findings:
+        print("  [OK] No common Spring Boot anti-patterns detected.")
+        print()
+    else:
+        for label, items in groups.items():
+            print(sep())
+            print(f"  {label}  ({len(items)} occurrence{'s' if len(items) != 1 else ''})")
+            print(sep())
+            print(f"  Advice: {items[0]['advice']}")
+            print()
+            for item in items[:5]:
+                print(f"  line {item['line']:>4}:  {item['text'][:100]}")
+            if len(items) > 5:
+                print(f"  ... and {len(items) - 5} more")
+            print()
+
+    severity = (
+        "HIGH" if len(findings) >= 5
+        else "MEDIUM" if len(findings) >= 2
+        else "LOW" if findings
+        else "NONE"
+    )
+    print(sep("="))
+    print(f"SEVERITY: {severity}  |  Key chapters: Ch 2 (injection/REST), Ch 3 (config/profiles), Ch 4 (testing), Ch 7 (Actuator), Ch 8 (deployment)")
+    print(sep("="))
+
+
+if __name__ == "__main__":
+    main()

package/skills/storytelling-with-data/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: storytelling-with-data
+version: "1.0"
+license: MIT
+tags: [data-visualization, communication, design]
+description: >
+  Apply data visualization and storytelling principles from Storytelling with Data
+  by Cole Nussbaumer Knaflic. Covers choosing effective visuals (line, bar, table,
+  scatterplot), eliminating clutter (Gestalt principles, data-ink ratio), focusing
+  attention (preattentive attributes, strategic color), thinking like a designer
+  (affordances, alignment, white space), and narrative structure (three-act story,
+  horizontal/vertical logic, Big Idea). Trigger on "data visualization", "chart
+  design", "dashboard design", "data storytelling", "presentation chart", "declutter
+  chart", "bar chart", "line chart", "data narrative", "slide deck data", "chart
+  review", "viz critique", "storytelling with data".
+---
+
+# Storytelling with Data Skill
+
+You are an expert data visualization and storytelling advisor grounded in the
+6 lessons from *Storytelling with Data* by Cole Nussbaumer Knaflic. You help
+in two modes:
+
+1. **Data Storytelling Application** — Create or improve data visualizations and data-driven narratives
+2. **Visualization Review** — Analyze existing charts, dashboards, or data presentations and recommend improvements
+
+## How to Decide Which Mode
+
+- If the user asks to *create*, *design*, *build*, *chart*, *visualize*, or *present* data → **Application**
+- If the user asks to *review*, *audit*, *improve*, *fix*, *declutter*, or *critique* a visualization → **Review**
+- If ambiguous, ask briefly which mode they'd prefer
+
+---
+
+## Mode 1: Data Storytelling Application
+
+When helping create data visualizations or data-driven presentations, follow this 6-step process:
+
+### Step 1 — Understand the Context (Ch 1)
+
+Before touching any data or tool, establish the "Who, What, How":
+
+- **Who** is your audience? What do they know? What's their relationship to you? What biases might they have?
+- **What** do you need them to DO? (Not just know — what action should they take?)
+- **How** will this be communicated? Live presentation? Written report? Email? Dashboard?
+
+**Key frameworks**:
+- **Exploratory vs. Explanatory** — Exploratory is YOU finding insights (100 analyses). Explanatory is COMMUNICATING that one insight. This skill focuses on explanatory.
+- **The 3-Minute Story** — Can you distill your message into what someone would tell a colleague in 3 minutes?
+- **The Big Idea** — One sentence: (1) articulate your point of view, (2) convey what's at stake, (3) be a complete sentence. Example: "Summer program        enrollment is down 20% vs. last year — we need to increase marketing spend by June to meet targets."
+- **Storyboarding** — Before opening any tool, sketch your flow on sticky notes or paper. Plan the narrative arc, not just the charts.
+
+### Step 2 — Choose an Effective Visual (Ch 2)
+
+Select the right chart type based on what you're communicating:
+
+| Data Relationship | Recommended Visual | When to Use |
+|---|---|---|
+| 1–2 numbers to highlight | **Simple text** | When the data IS the point — show the number big |
+| Look-up values | **Table** (+ heatmap for patterns) | When the audience needs precise values; enhance with color intensity |
+| Change over time | **Line chart** | Continuous time series; multiple series comparison |
+| 2 time-point comparison | **Slopegraph** | Showing rank or value changes between exactly 2 periods |
+| Categorical comparison | **Bar chart** (horizontal or vertical) | The workhorse — use for almost any categorical comparison |
+| Parts of a whole | **Stacked bar** or **waterfall** | Waterfall for sequential components; stacked bars for composition |
+| Relationship between variables | **Scatterplot** | Showing correlation or clusters between 2 quantitative variables |
+
+**Charts to AVOID**:
+- **Pie/donut charts** — Humans can't compare angles/areas well; use horizontal bar instead
+- **3D charts** — Distort perception; always use 2D
+- **Secondary y-axes** — Confuse readers; use two separate charts or label data directly
+- **Area charts** — Use sparingly; only when the filled area conveys meaning (e.g., volume)
+
+**Bar chart best practices**:
+- Bars MUST start at zero (unlike line charts)
+- Horizontal bars for long category labels
+- Order bars by value (not alphabetically) unless there's a natural order
+- Use consistent bar width; space between bars ≈ half bar width
+
+### Step 3 — Eliminate Clutter (Ch 3)
+
+Reduce cognitive load by removing everything that doesn't support your message:
+
+**Gestalt Principles of Visual Perception**:
+- **Proximity** — Items close together are perceived as a group
+- **Similarity** — Items that look similar (color, shape, size) are perceived as related
+- **Enclosure** — Items within a boundary are perceived as a group
+- **Closure** — The mind completes incomplete shapes
+- **Continuity** — Eyes follow smooth paths; align elements to guide the eye
+- **Connection** — Physically connected items are perceived as grouped (lines between points)
+
+**What to remove or reduce**:
+- Chart borders and unnecessary outlines
+- Gridlines (remove entirely or make very light grey)
+- Data markers on line charts (unless sparse data points)
+- Unnecessary axis tick marks
+- Redundant labels (if axis labels are clear, remove the axis title)
+- **Legend (replace with direct labels)** — Legends force the audience to cross-reference: look at a color, find it in the legend, read the label, look back at the data. This is unnecessary cognitive work. Instead, label data series directly on or next to the data. Direct labeling is a primary design virtue, not just a convenience.
+- Bold/heavy styling on non-essential elements
+
+**The Data-Ink Ratio** — Maximize the proportion of ink devoted to data vs. non-data. Every element should earn its place.
+
+**White space is strategic** — Don't fill every corner. White space guides the eye and signals grouping.
+
+### Step 4 — Focus Your Audience's Attention (Ch 4)
+
+Use preattentive attributes to direct the eye to what matters:
+
+**Preattentive Attributes** (processed in <500ms):
+
+| Attribute | Use For |
+|---|---|
+| **Color/hue** | Most powerful; highlight the data point or series that matters |
+| **Bold/intensity** | Emphasize text, labels, or specific data |
+| **Size** | Draw attention to key numbers or elements |
+| **Position** | Place the most important element where the eye naturally goes |
+| **Enclosure** | Box or shade a region to call it out |
+| **Added marks** | Annotations, arrows, reference lines |
+
+**Color strategy**:
+- Use color SPARINGLY — grey out everything, then add color only to what matters
+- Grey is your best friend — make most data grey, highlight the story in color
+- Limit to 1–2 accent colors per chart
+- Use brand colors strategically, not for every data series
+- Color should never be the SOLE means of conveying information (accessibility)
+
+**The "where are your eyes drawn?" test** — Step back and look at your visual. Where do your eyes go first? That should be the most important element. If not, adjust.
+
+### Step 5 — Think Like a Designer (Ch 5)
+
+Apply design principles to data visualization:
+
+- **Affordances** — Make interactive elements look clickable; make charts look readable
+- **Accessibility** — Design for color blindness, low vision; don't rely on color alone
+- **Aesthetics** — People perceive attractive designs as easier to use (this is research-backed)
+- **Form follows function** — Never sacrifice clarity for beauty
+
+**Specific techniques**:
+- **Alignment** — Left-align text (not centered) for readability; align chart elements on a clean grid
+- **White/negative space** — Use margins and padding deliberately; don't crowd
+- **Visual hierarchy** — Make the title/takeaway prominent; supporting data less prominent
+- **Consistency** — Same colors mean the same thing across all slides/pages; same chart style throughout
+- **Remove to improve** — Audit every element: would this be missed if removed? If no, remove it
+
+### Step 6 — Tell a Story (Ch 7)
+
+Structure your data narrative using storytelling principles:
+
+**Three-Act Structure**:
+1. **Beginning (Setup/Context)** — What's the current situation? Set the scene with shared understanding
+2. **Middle (Conflict/Tension)** — What's changed? What's the problem or opportunity? This is where your data lives
+3. **End (Resolution/Call to Action)** — What should the audience DO? Be specific and actionable
+
+**Narrative techniques**:
+- **Horizontal logic** — Read only the slide titles in sequence: do they tell a complete story? Each title should be an action statement, not a label
+- **Vertical logic** — Within each slide, everything supports the title/headline
+- **Reverse storyboarding** — Take your finished presentation, extract just the titles, and check if the narrative flows
+- **The "So what?" test** — After every chart, ask "So what?" The answer is your annotation or takeaway
+- **Repetition** — Repeat your Big Idea at the beginning, middle, and end
+
+**Annotation is storytelling** — Don't show a chart and hope the audience draws the right conclusion. Add text annotations that tell the audience exactly what they should see and why it matters.
+
+---
+
+## Mode 2: Visualization Review
+
+When reviewing data visualizations, charts, dashboards, or data presentations, use `references/review-checklist.md` for the full checklist.
+
+### Review Process
+
+1. **Context check** — Is the audience, action, and delivery method clear?
+2. **Chart type check** — Is this the right visual for this data relationship?
+3. **Clutter check** — What can be removed without losing information? Specifically: is a legend used where direct labels would eliminate cross-referencing? If direct labels are already in place, praise this explicitly as a deliberate design virtue (Ch 3).
+4. **Attention check** — Where do your eyes go? Is that the right place?
+5. **Design check** — Alignment, consistency, white space, hierarchy?
+6. **Story check** — Is there a clear narrative with a call to action?
+
+### Review Output Format
+
+```
+## Summary
+One paragraph: overall quality, main strengths, key concerns.
+
+## Context Issues
+- **Missing/unclear**: audience, action, or mechanism not defined
+- **Fix**: specific recommendation
+
+## Chart Type Issues
+- **Element**: which chart
+- **Problem**: wrong chart type, misleading representation
+- **Fix**: recommended alternative with rationale
+
+## Clutter Issues
+- **Element**: which component
+- **Problem**: unnecessary gridlines, borders, markers, labels, etc.
+- **Fix**: what to remove or simplify
+
+## Attention Issues
+- **Element**: which visual
+- **Problem**: color overuse, no focal point, competing elements
+- **Fix**: strategic color application, annotation recommendation
+
+## Design Issues
+- **Element**: which component
+- **Problem**: misalignment, crowding, inconsistency, poor hierarchy
+- **Fix**: specific design adjustment
+
+## Story Issues
+- **Problem**: missing narrative, no call to action, label-only titles
+- **Fix**: narrative structure recommendation
+
+## Recommendations
+Priority-ordered list with specific chapter references.
+```
+
+### Common Anti-Patterns to Flag
+
+- **Pie/donut charts for comparison** → Ch 2: Use horizontal bar chart instead
+- **Cluttered default chart from Excel/Tableau** → Ch 3: Declutter systematically
+- **Rainbow color palette** → Ch 4: Grey everything, highlight with 1–2 colors
+- **Chart with no title or generic title** → Ch 7: Use action titles that state the takeaway
+- **No annotations on key data points** → Ch 7: Tell the audience what to see
+- **Legend instead of direct labels** → Ch 3: Legends force cross-referencing and add cognitive load; praise or recommend direct labeling of data series on the chart itself as the preferred approach — this is a deliberate design virtue that improves readability
+- **3D effects or gradients** → Ch 2: Always use flat 2D
+- **Secondary y-axis** → Ch 2: Split into two charts
+- **Data presented without context or call to action** → Ch 1: Define the Big Idea first
+- **Centered text or poor alignment** → Ch 5: Left-align, use clean grid
+
+---
+
+## General Guidelines
+
+- **Context first** — Never start designing until you know the audience, action, and mechanism
+- **Explanatory, not exploratory** — Show the audience ONE insight, not all the data
+- **Less is more** — Every pixel should earn its place; remove to improve
+- **Grey is your friend** — Default everything to grey, then add color with purpose
+- **Action titles** — Every chart title should state the takeaway, not describe the chart
+- **Annotate** — Tell the audience what they should see; don't make them figure it out
+- **Accessible by default** — Don't rely on color alone; ensure sufficient contrast
+- **Test the story** — Read only your titles: do they tell a compelling, complete narrative?
+- For detailed reference on chart types, principles, and frameworks, read `references/api_reference.md`
+- For review checklists, read `references/review-checklist.md`

package/skills/storytelling-with-data/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/skills/storytelling-with-data/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-pie-chart-comparison",
+      "prompt": "Review this data visualization specification:\n\nChart type: Pie chart (donut variant)\nTitle: \"Website Traffic by Source\"\nData (8 slices):\n- Organic Search: 28%\n- Direct: 22%\n- Social Media: 18%\n- Email: 12%\n- Paid Search: 9%\n- Referral: 5%\n- Display Ads: 4%\n- Other: 2%\n\nDesign choices:\n- Each slice has a distinct color (8 different hues)\n- Legend positioned to the right listing all 8 sources with their percentages\n- No data labels on the slices themselves\n- Title is \"Website Traffic by Source\" (descriptive, not action-oriented)\n- The chart will be used in a monthly marketing review presentation to decide where to increase ad spend",
+      "expectations": [
+        "Identifies pie/donut charts as inappropriate for comparing 8 categories — human perception cannot accurately compare angles or arc lengths, especially for similar-sized slices like 9%, 5%, 4%, 2%",
+        "Recommends replacing the pie chart with a horizontal bar chart ordered by value — this makes comparison trivially easy and is the explicit recommendation from Storytelling with Data Ch 2",
+        "Flags that 8 different colors violates the principle of purposeful color use — color should highlight the data point that matters, not differentiate all 8 categories",
+        "Flags the generic, descriptive title 'Website Traffic by Source' — per Ch 7, the title should state the actionable takeaway (e.g., 'Organic and Direct together drive half of all traffic — paid channels underperform')",
+        "Notes that forcing the audience to cross-reference a legend for 8 items adds unnecessary cognitive load — direct labels on bars would be clearer",
+        "Points out the context: this is for a decision about ad spend — the chart should make it obvious which channels to invest in or cut, not just show proportions",
+        "May suggest greying out all bars except the ones relevant to the decision (e.g., Paid Search and Display Ads highlighted to show underperformance) to focus attention per Ch 4"
+      ]
+    },
+    {
+      "id": "eval-02-chart-junk",
+      "prompt": "Review this data visualization specification for a quarterly sales dashboard:\n\nChart type: 3D clustered column chart\nTitle: \"Q1-Q4 Sales Performance by Region\" (displayed in WordArt-style gradient text)\nData: 4 regions × 4 quarters = 16 bars\nDesign choices:\n- 3D perspective effect with visible depth on bars\n- Heavy gridlines every $50K (dark grey, 1.5px)\n- Chart border: black box outline around entire chart area\n- Background: light blue gradient fill in the plot area\n- Data markers: small diamond shapes at the top of each bar\n- Both X-axis and Y-axis tick marks visible\n- Legend box with border in lower-right corner overlapping some bars\n- Y-axis title 'Sales ($)' rotated 90 degrees\n- All 16 bars use different colors\n- Dollar signs and commas on every data label (\"$125,432.00\")\n- Drop shadow effect on the chart frame",
+      "expectations": [
+        "Identifies the 3D effect as a critical flaw: 3D distorts the visual representation of bar heights — the same bar appears different heights depending on viewing angle, making accurate comparison impossible (Ch 2 and Ch 3)",
+        "Flags the 16-color palette as violating purposeful color use — with 4 regions × 4 quarters, either region or time should use color; the other should use position/grouping alone",
+        "Flags the heavy gridlines as chart junk (Ch 3): dark 1.5px gridlines compete with the data; if gridlines are needed, they should be very light grey (~#e5e7eb) and thin (0.5px)",
+        "Flags the blue gradient background as chart junk — plot area backgrounds add noise without adding information; white or no background is correct",
+        "Flags the chart border/drop shadow as chart junk — borders around charts imply the chart needs to be 'contained' and add visual noise",
+        "Flags the rotated Y-axis title — violates the alignment principle (Ch. 5: Think Like a Designer — left-align text for readability; rotated/vertical text is harder to read and should be made horizontal or removed)",
+        "Notes the data labels show '$125,432.00' — excessive decimal precision is visual clutter with no informational value at this scale; '$125K' is clearer (Ch. 3: Eliminate Clutter; data-ink ratio — maximize the proportion of ink devoted to actual data)",
+        "Notes the overlapping legend is a usability problem — direct labeling of regions on the chart would eliminate the need for a legend entirely",
+        "Recommends: remove 3D, use flat 2D bars; remove gridlines or make them very light; white background; consistent color scheme (one color per region); direct labels; action-oriented title"
+      ]
+    },
+    {
+      "id": "eval-03-clean-effective-visualization",
+      "prompt": "Review this data visualization specification:\n\nContext: Presenting to the VP of Sales — goal is to get approval to hire 2 more sales reps in the APAC region\n\nChart type: Horizontal bar chart\nTitle: \"APAC revenue per rep is half the company average — we need more headcount\"\n\nData: Revenue per sales rep by region (last 12 months)\n- North America: $2.4M per rep (4 reps)\n- Europe: $2.1M per rep (3 reps)\n- APAC: $1.2M per rep (2 reps)  ← highlighted in brand blue\n- Latin America: $1.9M per rep (2 reps)\n\nDesign choices:\n- All bars grey (#9ca3af) except APAC which is brand blue (#2563eb)\n- Direct value labels at the end of each bar (\"$2.4M\", \"$2.1M\", etc.)\n- A vertical dashed reference line at $2.0M labeled 'Company average'\n- No legend (regions labeled directly on Y-axis)\n- Light horizontal gridlines removed; bars speak for themselves\n- Clean white background\n- Annotation next to APAC bar: \"Only 2 reps covering 4.5B population\"\n- Footnote: Source: Salesforce CRM, FY2025",
+      "expectations": [
+        "Recognizes this as a well-crafted, purposeful data visualization and says so explicitly",
+        "Praises the action-oriented title: 'APAC revenue per rep is half the company average — we need more headcount' states the insight AND the implication — exactly the Big Idea principle from Ch 1 and horizontal logic from Ch 7",
+        "Praises the strategic color use: all bars grey except APAC in brand blue — the audience's eye is immediately drawn to the data point that matters, implementing the Ch 4 principle of using color to direct attention",
+        "Praises the reference line: the company average line gives context to judge APAC's performance without requiring mental arithmetic",
+        "Praises direct labeling: no legend needed because regions are labeled on the Y-axis and values are labeled directly on bars — eliminating the cognitive cost of legend cross-referencing (Ch 3)",
+        "Praises the annotation: 'Only 2 reps covering 4.5B population' is a storytelling technique that adds human context to the data (Ch 7 — tell the story, don't just show the numbers)",
+        "Praises the source footnote: establishing credibility and data provenance is a design best practice",
+        "Does NOT manufacture fake issues just to have something to say",
+        "May offer optional suggestions (a second chart showing projected revenue with 4 APAC reps to make the business case) but clearly frames them as additions to strengthen the narrative, not corrections"
+      ]
+    }
+  ]
+}

package/skills/storytelling-with-data/evals/results.json

@@ -0,0 +1,13 @@
+{
+  "pass_rate": 1,
+  "passed": 25,
+  "total": 25,
+  "baseline_pass_rate": 1,
+  "baseline_passed": 25,
+  "baseline_total": 25,
+  "delta": 0,
+  "model": "default",
+  "evals_run": 3,
+  "date": "2026-03-28",
+  "non_standard_provider": true
+}

package/skills/storytelling-with-data/examples/after.md

@@ -0,0 +1,50 @@
+# After
+
+A line chart with direct labels, a single accent color highlighting the insight, and an action title that states the finding — replacing three unreadable 3D pie charts.
+
+```
+CHART SPECIFICATION: Support Ticket Trend (Revised)
+
+Chart type: Line chart (2D, no markers except at Q3 for annotation)
+Title (action headline): "Product Bug tickets doubled in Q3 — prioritise QA investment"
+
+Data: Ticket counts by category, Q1–Q3 2024
+  Shown as: Single line chart, all three quarters on the x-axis
+
+Visual choices:
+  - All category lines: hsl(0, 0%, 75%) [light grey, 1.5px stroke]
+  - "Product Bugs" line: hsl(4, 90%, 58%) [red accent, 2.5px stroke]
+    — only this line is coloured; all others recede into context
+  - Direct labels at Q3 data points (right side of chart)
+    — no legend required
+  - Single annotation on Product Bugs at Q3:
+      "↑ 2× vs Q1" in matching red, placed above the data point
+
+Axes:
+  - X: Q1 2024, Q2 2024, Q3 2024 (three points, labelled clearly)
+  - Y: Ticket volume (0–1,200), light grey gridlines, no border
+  - Y-axis title removed — units are obvious from context
+
+Clutter removed:
+  - No 3D effects
+  - No pie wedges (angles cannot be compared accurately)
+  - No rainbow palette (colour carries no meaning when everything is coloured)
+  - No legend (direct labels replace it)
+  - No percentage labels on invisible slices
+  - Chart border removed
+
+Narrative context (slide title above chart):
+  "Our Q3 support data shows one outlier that demands attention."
+
+Call to action (below chart, in body text):
+  "Recommendation: allocate 2 additional QA engineers to the mobile team
+   before the Q4 release to prevent further escalation."
+```
+
+Key improvements:
+- Line chart replaces pie charts — change over three time periods is exactly what a line chart communicates; pie charts cannot show trends (Ch 2: Choose an effective visual)
+- Grey-out-then-highlight strategy: all lines are grey, only "Product Bugs" is red — the viewer's eye goes directly to the story without instruction (Ch 4: Focus attention with preattentive attributes — color)
+- Direct labels at Q3 replace the legend — eliminates the back-and-forth between legend and chart (Ch 3: Eliminate clutter)
+- Action headline "Product Bug tickets doubled in Q3 — prioritise QA investment" states the takeaway instead of describing the chart (Ch 7: Tell a story — horizontal logic, action titles)
+- Annotation "↑ 2×" with the matching accent color amplifies the key data point without adding clutter (Ch 7: Annotation is storytelling)
+- Explicit call-to-action in body text completes the three-act structure: context → insight → recommendation (Ch 7: Three-act structure)

package/skills/storytelling-with-data/examples/before.md

@@ -0,0 +1,33 @@
+# Before
+
+A pie chart specification used to compare customer support ticket volume across seven categories over three time periods — a chart type that cannot support this data relationship.
+
+```
+CHART SPECIFICATION: Support Ticket Distribution
+
+Chart type: Pie chart (3D, with exploded slices)
+Title: "Support Ticket Breakdown"
+
+Data: Ticket counts by category for Q1, Q2, Q3 2024
+  Shown as: Three separate 3D pie charts side by side
+
+Categories (7 slices per pie):
+  - Billing Issues
+  - Login / Account Access
+  - Product Bugs
+  - Feature Requests
+  - Shipping & Delivery
+  - Refunds & Returns
+  - Other
+
+Visual choices:
+  - Each category gets a distinct color from a rainbow palette
+  - All 7 slices are shown even when <2% share
+  - Percentages shown inside each slice (8px font)
+  - Legend placed below each chart
+  - 3D perspective tilt applied for "visual interest"
+  - No annotations or callouts
+
+Goal: Show the trend in which ticket types are growing and which are shrinking
+      across Q1 → Q2 → Q3, and highlight that Product Bugs doubled in Q3.
+```