@booklib/skills 1.0.0 → 1.3.0

package/skill-router/references/api_reference.md

@@ -0,0 +1,24 @@
+# API Reference: Skill Quick-Lookup
+
+Quick-lookup table for all 17 skills.
+
+| Skill | Domain | Works Well With | Conflicts With |
+|-------|--------|-----------------|----------------|
+| `animation-at-work` | Web animation, motion | `refactoring-ui` | None |
+| `clean-code-reviewer` | Code quality (any language) | `effective-java`, `effective-python`, `effective-kotlin` | `domain-driven-design` (model design context) |
+| `data-intensive-patterns` | Storage internals, distributed data | `system-design-interview` | `system-design-interview` (different altitude) |
+| `data-pipelines` | ETL, data ingestion, orchestration | `data-intensive-patterns`, `effective-python` | `microservices-patterns` |
+| `design-patterns` | GoF OO patterns | `clean-code-reviewer`, `effective-java` | `domain-driven-design` |
+| `domain-driven-design` | Domain modeling, DDD patterns | `microservices-patterns`, `clean-code-reviewer` | `clean-code-reviewer` (code review context) |
+| `effective-java` | Java idioms and best practices | `clean-code-reviewer`, `design-patterns` | `clean-code-reviewer` (Java-specific vs general) |
+| `effective-kotlin` | Kotlin best practices | `kotlin-in-action`, `clean-code-reviewer` | `kotlin-in-action` |
+| `effective-python` | Python idioms and best practices | `clean-code-reviewer`, `using-asyncio-python` | `using-asyncio-python` (async topics) |
+| `kotlin-in-action` | Kotlin language features | `effective-kotlin` | `effective-kotlin` |
+| `lean-startup` | Startup strategy, MVP, pivots | None (strategy only) | All technical skills |
+| `microservices-patterns` | Service decomposition, sagas, CQRS | `domain-driven-design`, `system-design-interview` | `domain-driven-design` (service vs model) |
+| `refactoring-ui` | UI design, visual hierarchy | `animation-at-work` | None |
+| `skill-router` | Skill selection and routing | All skills | None |
+| `storytelling-with-data` | Data visualization, charts | `data-pipelines` | None |
+| `system-design-interview` | System scalability, high-level design | `microservices-patterns`, `data-intensive-patterns` | `data-intensive-patterns` (altitude) |
+| `using-asyncio-python` | Python asyncio, concurrency | `effective-python` | `effective-python` (async topics) |
+| `web-scraping-python` | Web scraping, crawling | `effective-python`, `data-pipelines` | None |

package/skill-router/references/routing-heuristics.md

@@ -0,0 +1,89 @@
+# Routing Heuristics
+
+Decision rules for the skill-router. Apply these in order.
+
+## Primary Rules (apply first)
+
+### By Language
+
+| Language | Primary Skill | Override Condition |
+|----------|-------------|-------------------|
+| Python (general) | `effective-python` | If async → `using-asyncio-python`; if scraping → `web-scraping-python` |
+| Python (async/concurrent) | `using-asyncio-python` | Always wins over effective-python for async topics |
+| Python (web scraping) | `web-scraping-python` | Always wins for scraping topics |
+| Java | `effective-java` | If code quality focus → `clean-code-reviewer` |
+| Kotlin | `effective-kotlin` | If learning Kotlin → `kotlin-in-action` |
+| Any language (code quality) | `clean-code-reviewer` | Language-agnostic; always applicable for readability |
+| CSS/HTML/Frontend | `refactoring-ui` | If animation → `animation-at-work` |
+| Any (visualization) | `storytelling-with-data` | Must have a visual component |
+
+### By Domain
+
+| Domain | Primary Skill |
+|--------|-------------|
+| Domain modeling, DDD | `domain-driven-design` |
+| Service decomposition, distributed systems | `microservices-patterns` |
+| GoF design patterns | `design-patterns` |
+| System scalability, estimation | `system-design-interview` |
+| Storage internals, distributed data | `data-intensive-patterns` |
+| Data pipelines, ETL | `data-pipelines` |
+| Startup strategy, product | `lean-startup` |
+
+## Conflict Resolution Rules
+
+### clean-code-reviewer vs effective-java
+- **Code-level review with naming/readability focus** → `clean-code-reviewer`
+- **Java-specific items (generics, enums, serialization, lambdas)** → `effective-java`
+- **Both applicable** → primary: `clean-code-reviewer`, secondary: `effective-java`
+
+### effective-kotlin vs kotlin-in-action
+- **User knows Kotlin, wants best practice advice** → `effective-kotlin`
+- **User is learning Kotlin or asking about language features** → `kotlin-in-action`
+- **Ambiguous** → ask whether they want best practices or feature explanation
+
+### domain-driven-design vs microservices-patterns
+- **Designing or reviewing a domain model** → `domain-driven-design`
+- **Designing service decomposition, sagas, inter-service communication** → `microservices-patterns`
+- **Designing a new microservice with rich domain** → apply both: DDD first (model), microservices-patterns second (service design)
+
+### domain-driven-design vs clean-code-reviewer
+- **Model design** → `domain-driven-design` (ignore clean code's "small functions" rule when modeling)
+- **Code review** → `clean-code-reviewer` (DDD model concerns are separate from code readability)
+
+### data-intensive-patterns vs system-design-interview
+- **Internals: storage engines, replication, consistency models** → `data-intensive-patterns`
+- **High-level: system components, scale, estimation** → `system-design-interview`
+- **Full system design** → primary: `system-design-interview`, secondary: `data-intensive-patterns`
+
+### effective-python vs using-asyncio-python
+- **Any async/concurrent Python** → `using-asyncio-python` (always wins)
+- **Non-async Python** → `effective-python`
+
+## Work Type Rules
+
+| Work Type | Routing Preference |
+|-----------|-------------------|
+| Code review | Language-specific skill OR `clean-code-reviewer` |
+| Code generation | Domain-specific skill (DDD, microservices, design-patterns) |
+| Migration planning | Skill with Mode 3 (clean-code-reviewer, domain-driven-design, microservices-patterns) |
+| System design | `system-design-interview` + optional `microservices-patterns` |
+| Learning | Language-specific learning skill (kotlin-in-action) or domain skill |
+
+## Anti-Trigger Rules
+
+Never route to these skills if:
+
+| Skill | Don't route if... |
+|-------|------------------|
+| `domain-driven-design` | Simple CRUD, no complex domain, < 3 entity types |
+| `microservices-patterns` | Single service, no decomposition intent |
+| `lean-startup` | Pure technical code — this is a strategy skill only |
+| `effective-java` | Code is not Java |
+| `effective-kotlin` | Code is not Kotlin |
+| `effective-python` | Code is not Python |
+| `using-asyncio-python` | Code is not async Python |
+| `web-scraping-python` | Not web scraping |
+| `refactoring-ui` | No UI component |
+| `storytelling-with-data` | No visualization |
+| `animation-at-work` | No animation/motion concern |
+| `system-design-interview` | Code-level concern, not system-level |

package/skill-router/references/skill-catalog.md

@@ -0,0 +1,156 @@
+# Skill Catalog
+
+All 17 skills in the `@booklib/skills` library with routing metadata.
+
+## animation-at-work
+- **Source:** *Animation at Work* by Rachel Nabors
+- **Domain:** Web animation, UI motion design
+- **Language:** CSS, JavaScript, any frontend
+- **Trigger keywords:** "animation", "motion", "transition", "keyframe", "easing", "12 principles of animation", "web animation", "CSS animation", "performance of animation"
+- **Anti-triggers:** Backend code, data processing, non-visual concerns
+- **Works well with:** refactoring-ui (visual design context)
+- **Conflicts with:** None (niche domain)
+
+## clean-code-reviewer
+- **Source:** *Clean Code* by Robert C. Martin
+- **Domain:** Code quality, readability, maintainability
+- **Language:** Language-agnostic (Java, Python, Kotlin, JavaScript examples used)
+- **Trigger keywords:** "review my code", "code quality", "readable", "clean up", "refactor", "naming", "functions", "comments", "smells"
+- **Anti-triggers:** Architecture design (too high-level), language-specific idioms (use language-specific skill instead)
+- **Works well with:** effective-java, effective-python, effective-kotlin (clean code first, then language idioms)
+- **Conflicts with:** domain-driven-design (Clean Code's "small functions" vs DDD's "rich models" — clean code wins for code review, DDD wins for model design)
+
+## data-intensive-patterns
+- **Source:** *Designing Data-Intensive Applications* by Martin Kleppmann
+- **Domain:** Storage engines, replication, partitioning, distributed systems, transactions, consistency
+- **Language:** Language-agnostic (systems-level)
+- **Trigger keywords:** "replication", "partitioning", "consistency", "CAP theorem", "event sourcing internals", "storage engine", "LSM tree", "B-tree", "distributed transactions", "ACID", "BASE", "linearizability"
+- **Anti-triggers:** Application-level code quality, UI, domain modeling
+- **Works well with:** system-design-interview (data layer + high-level architecture)
+- **Conflicts with:** system-design-interview (data-intensive-patterns is deeper/lower-level; use it for internals, system-design-interview for high-level)
+
+## data-pipelines
+- **Source:** *Data Pipelines Pocket Reference* by James Densmore
+- **Domain:** Data ingestion, ETL, streaming, pipeline orchestration
+- **Language:** Python, SQL, any data engineering stack
+- **Trigger keywords:** "data pipeline", "ETL", "ELT", "ingestion", "Airflow", "dbt", "Spark", "streaming pipeline", "batch processing", "data warehouse", "orchestration"
+- **Anti-triggers:** Application code unrelated to data movement, real-time microservices
+- **Works well with:** data-intensive-patterns (pipeline + storage), effective-python (Python data code)
+- **Conflicts with:** microservices-patterns (pipeline orchestration ≠ service decomposition)
+
+## design-patterns
+- **Source:** *Head First Design Patterns* by Freeman & Robson (GoF patterns)
+- **Domain:** Object-oriented design patterns (creational, structural, behavioral)
+- **Language:** Java primarily, but pattern-agnostic
+- **Trigger keywords:** "design pattern", "factory", "singleton", "observer", "strategy", "decorator", "facade", "command", "template method", "composite", "adapter", "proxy", "iterator", "state"
+- **Anti-triggers:** Functional programming (patterns don't apply the same way), microservices decomposition
+- **Works well with:** clean-code-reviewer (patterns + readability), effective-java (Java idioms + patterns)
+- **Conflicts with:** domain-driven-design (GoF patterns are structural; DDD patterns are domain-driven — use DDD for domain modeling, GoF for implementation structure)
+
+## domain-driven-design
+- **Source:** *Domain-Driven Design* by Eric Evans
+- **Domain:** Domain modeling, tactical patterns (Entities, Value Objects, Aggregates, Repositories), strategic patterns (Bounded Contexts, Context Maps, ACL)
+- **Language:** Language-agnostic (OO languages)
+- **Trigger keywords:** "DDD", "domain model", "aggregate", "value object", "bounded context", "ubiquitous language", "repository pattern", "domain service", "anticorruption layer", "entity", "anemic domain model", "primitive obsession"
+- **Anti-triggers:** Simple CRUD without domain complexity, microservices infrastructure concerns, code quality review
+- **Works well with:** microservices-patterns (domain model + service boundaries), clean-code-reviewer (model + code quality)
+- **Conflicts with:** clean-code-reviewer (rich models vs small functions — DDD wins for model design; clean code wins for code review)
+
+## effective-java
+- **Source:** *Effective Java* (3rd Edition) by Joshua Bloch
+- **Domain:** Java best practices and idioms
+- **Language:** Java only
+- **Trigger keywords:** "effective java", "java best practices", "generics", "enums", "lambdas", "streams", "builders", "serialization", "java concurrency", "checked exceptions", "java item"
+- **Anti-triggers:** Non-Java code, architecture concerns, domain modeling
+- **Works well with:** clean-code-reviewer (Java idioms + code quality), design-patterns (Java implementation of patterns)
+- **Conflicts with:** clean-code-reviewer (both review Java but from different angles — use effective-java for Java-specific items, clean-code-reviewer for general readability)
+
+## effective-kotlin
+- **Source:** *Effective Kotlin* (2nd Edition) by Marcin Moskała
+- **Domain:** Kotlin best practices, safety, readability
+- **Language:** Kotlin only
+- **Trigger keywords:** "effective kotlin", "kotlin best practices", "kotlin safety", "null safety", "extension functions best practices", "kotlin idioms", "kotlin item"
+- **Anti-triggers:** Non-Kotlin code, architecture concerns
+- **Works well with:** kotlin-in-action (best practices + language features), clean-code-reviewer (Kotlin idioms + readability)
+- **Conflicts with:** kotlin-in-action (effective-kotlin for best practices; kotlin-in-action for language learning — if user knows Kotlin and wants advice, use effective-kotlin)
+
+## effective-python
+- **Source:** *Effective Python* (2nd Edition) by Brett Slatkin
+- **Domain:** Python best practices, Pythonic idioms
+- **Language:** Python only
+- **Trigger keywords:** "effective python", "pythonic", "python best practices", "python idioms", "comprehensions", "generators", "decorators", "metaclasses", "python item"
+- **Anti-triggers:** Non-Python code, async Python (use using-asyncio-python instead)
+- **Works well with:** clean-code-reviewer (Pythonic + readable), using-asyncio-python (general Python + async)
+- **Conflicts with:** using-asyncio-python (using-asyncio-python wins for async topics)
+
+## kotlin-in-action
+- **Source:** *Kotlin in Action* (2nd Edition)
+- **Domain:** Kotlin language features, learning Kotlin
+- **Language:** Kotlin only
+- **Trigger keywords:** "kotlin in action", "learn kotlin", "kotlin coroutines", "kotlin lambdas", "kotlin classes", "kotlin functions", "kotlin nullability", "how does kotlin"
+- **Anti-triggers:** Best practices advice (use effective-kotlin), non-Kotlin code
+- **Works well with:** effective-kotlin (learning + best practices)
+- **Conflicts with:** effective-kotlin (kotlin-in-action for learning features; effective-kotlin for best practice advice)
+
+## lean-startup
+- **Source:** *The Lean Startup* by Eric Ries
+- **Domain:** Startup strategy, MVP, validated learning, Build-Measure-Learn
+- **Language:** Not applicable (strategy skill)
+- **Trigger keywords:** "lean startup", "MVP", "validated learning", "pivot", "build-measure-learn", "product market fit", "hypothesis", "experiment", "runway"
+- **Anti-triggers:** Technical code review, architecture, any pure engineering concern
+- **Works well with:** None (strategy domain, not engineering)
+- **Conflicts with:** All technical skills (don't apply to code)
+
+## microservices-patterns
+- **Source:** *Microservices Patterns* by Chris Richardson
+- **Domain:** Microservices architecture, sagas, CQRS, API gateways, event sourcing
+- **Language:** Language-agnostic (Java Spring Boot examples)
+- **Trigger keywords:** "microservice", "saga", "CQRS", "event sourcing", "API gateway", "service mesh", "decompose monolith", "circuit breaker", "distributed transaction", "choreography", "orchestration"
+- **Anti-triggers:** Monolith-only code with no decomposition intent, pure domain modeling without service concerns
+- **Works well with:** domain-driven-design (service boundaries + domain model), system-design-interview (microservices + scale)
+- **Conflicts with:** domain-driven-design (microservices-patterns for service decomposition; DDD for domain model — apply both for new services)
+
+## refactoring-ui
+- **Source:** *Refactoring UI* by Adam Wathan & Steve Schoger
+- **Domain:** UI design, visual hierarchy, typography, color, layout, spacing
+- **Language:** CSS, HTML, any frontend
+- **Trigger keywords:** "UI design", "visual hierarchy", "typography", "color palette", "spacing", "layout", "design system", "refactor UI", "looks bad", "UI review"
+- **Anti-triggers:** Backend code, APIs, data processing, animation (use animation-at-work)
+- **Works well with:** animation-at-work (UI design + motion)
+- **Conflicts with:** animation-at-work (refactoring-ui for static design; animation-at-work for motion — they complement each other)
+
+## storytelling-with-data
+- **Source:** *Storytelling with Data* by Cole Nussbaumer Knaflic
+- **Domain:** Data visualization, charts, narrative structure
+- **Language:** Not applicable (visualization skill)
+- **Trigger keywords:** "data visualization", "chart", "graph", "dashboard", "storytelling", "declutter", "visual", "bar chart", "line chart", "scatter plot", "pie chart"
+- **Anti-triggers:** Code quality, backend processing, no visual component
+- **Works well with:** data-pipelines (pipeline data + visualization)
+- **Conflicts with:** None (niche visual domain)
+
+## system-design-interview
+- **Source:** *System Design Interview* by Alex Xu
+- **Domain:** High-level system architecture, scalability, estimation, real-world system designs
+- **Language:** Language-agnostic
+- **Trigger keywords:** "system design", "scale", "scalability", "back of envelope", "rate limiting", "CDN", "load balancer", "cache", "sharding", "high availability", "design YouTube", "design Twitter", "design a URL shortener"
+- **Anti-triggers:** Code-level review, domain modeling, specific language idioms
+- **Works well with:** data-intensive-patterns (high-level + storage internals), microservices-patterns (system design + service architecture)
+- **Conflicts with:** data-intensive-patterns (system-design-interview for high-level; data-intensive-patterns for storage internals)
+
+## using-asyncio-python
+- **Source:** *Using Asyncio in Python* by Caleb Hattingh
+- **Domain:** Python asyncio, coroutines, event loop, async patterns
+- **Language:** Python only
+- **Trigger keywords:** "asyncio", "async def", "await", "coroutine", "event loop", "aiohttp", "async Python", "concurrent Python", "Python concurrency"
+- **Anti-triggers:** Non-async Python, non-Python code
+- **Works well with:** effective-python (async + general Python best practices)
+- **Conflicts with:** effective-python (using-asyncio-python wins for any async topic)
+
+## web-scraping-python
+- **Source:** *Web Scraping with Python* by Ryan Mitchell
+- **Domain:** Web scraping, BeautifulSoup, Scrapy, data extraction
+- **Language:** Python only
+- **Trigger keywords:** "web scraping", "BeautifulSoup", "Scrapy", "requests", "crawl", "parse HTML", "selenium scraping", "extract data from website"
+- **Anti-triggers:** Non-scraping Python, general Python best practices
+- **Works well with:** effective-python (scraping + Python best practices), data-pipelines (scraping + ingestion)
+- **Conflicts with:** None (niche domain)

package/skill-router/scripts/route.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""
+route.py — CLI for skill-router
+
+Usage:
+    python route.py --task "review my Python class for code quality"
+    python route.py --file path/to/file.py --task "review for correctness"
+    python route.py --task "design a saga for order processing"
+    python route.py --task "decompose my monolith into microservices"
+
+Prints the recommended skill(s) with rationale.
+"""
+
+import argparse
+import os
+
+# Skill routing rules
+SKILL_CATALOG = {
+    "animation-at-work": {
+        "domain": "Web animation, UI motion",
+        "languages": [],  # language-agnostic but frontend
+        "keywords": ["animation", "motion", "transition", "keyframe", "easing", "css animation", "web animation"],
+        "anti_keywords": ["backend", "data processing", "api"],
+    },
+    "clean-code-reviewer": {
+        "domain": "Code quality, readability (any language)",
+        "languages": ["py", "java", "kt", "js", "ts", "go", "rs", "cpp", "cs"],
+        "keywords": ["review", "code quality", "readable", "clean", "refactor", "naming", "smell", "heuristic"],
+        "anti_keywords": ["architecture", "system design"],
+    },
+    "data-intensive-patterns": {
+        "domain": "Storage internals, distributed data",
+        "languages": [],
+        "keywords": ["replication", "partitioning", "consistency", "cap theorem", "storage engine", "lsm", "b-tree", "acid", "base", "linearizability"],
+        "anti_keywords": ["ui", "frontend", "domain model"],
+    },
+    "data-pipelines": {
+        "domain": "ETL, data ingestion, orchestration",
+        "languages": ["py", "sql"],
+        "keywords": ["data pipeline", "etl", "elt", "ingestion", "airflow", "dbt", "spark", "streaming", "batch", "warehouse"],
+        "anti_keywords": ["microservice", "ui"],
+    },
+    "design-patterns": {
+        "domain": "GoF OO design patterns",
+        "languages": ["java", "py", "kt", "cs"],
+        "keywords": ["design pattern", "factory", "singleton", "observer", "strategy", "decorator", "facade", "command", "template method", "composite"],
+        "anti_keywords": ["functional", "microservice decomposition"],
+    },
+    "domain-driven-design": {
+        "domain": "Domain modeling, DDD tactical and strategic patterns",
+        "languages": [],
+        "keywords": ["ddd", "domain model", "aggregate", "value object", "bounded context", "ubiquitous language", "repository", "domain service", "anticorruption", "entity", "anemic"],
+        "anti_keywords": ["simple crud", "ui", "code quality"],
+    },
+    "effective-java": {
+        "domain": "Java best practices",
+        "languages": ["java"],
+        "keywords": ["java", "generics", "enum", "lambda", "stream", "builder pattern", "serialization", "checked exception"],
+        "anti_keywords": [],
+    },
+    "effective-kotlin": {
+        "domain": "Kotlin best practices",
+        "languages": ["kt"],
+        "keywords": ["kotlin", "kotlin best practices", "kotlin safety", "null safety", "kotlin idioms", "effective kotlin", "best practices"],
+        "anti_keywords": ["learning kotlin"],
+    },
+    "effective-python": {
+        "domain": "Python idioms and best practices",
+        "languages": ["py"],
+        "keywords": ["pythonic", "python best practices", "comprehension", "generator", "decorator", "metaclass"],
+        "anti_keywords": ["async", "asyncio", "web scraping"],
+    },
+    "kotlin-in-action": {
+        "domain": "Kotlin language features",
+        "languages": ["kt"],
+        "keywords": ["learn kotlin", "kotlin coroutines", "kotlin lambdas", "kotlin classes", "how does kotlin"],
+        "anti_keywords": ["best practices"],
+    },
+    "lean-startup": {
+        "domain": "Startup strategy, MVP, validated learning",
+        "languages": [],
+        "keywords": ["mvp", "validated learning", "pivot", "build-measure-learn", "lean startup", "hypothesis", "product market fit"],
+        "anti_keywords": ["code", "review", "architecture", "api"],
+    },
+    "microservices-patterns": {
+        "domain": "Service decomposition, sagas, CQRS, event sourcing",
+        "languages": [],
+        "keywords": ["microservice", "services", "saga", "cqrs", "event sourcing", "api gateway", "decompose monolith", "circuit breaker", "distributed transaction", "choreography", "service coordination", "inter-service", "strangle", "strangler"],
+        "anti_keywords": ["monolith only", "simple crud"],
+    },
+    "refactoring-ui": {
+        "domain": "UI design, visual hierarchy, typography",
+        "languages": ["css", "html", "jsx", "tsx", "svelte"],
+        "keywords": ["ui design", "visual hierarchy", "typography", "color", "spacing", "layout", "design system"],
+        "anti_keywords": ["backend", "api", "animation"],
+    },
+    "storytelling-with-data": {
+        "domain": "Data visualization, charts, narrative",
+        "languages": [],
+        "keywords": ["data visualization", "chart", "graph", "dashboard", "storytelling", "declutter", "bar chart", "scatter plot"],
+        "anti_keywords": ["backend", "api", "code quality"],
+    },
+    "system-design-interview": {
+        "domain": "System scalability, high-level architecture",
+        "languages": [],
+        "keywords": ["system design", "scale", "scalability", "rate limiting", "cdn", "load balancer", "cache", "sharding", "high availability"],
+        "anti_keywords": ["code review", "domain model"],
+    },
+    "using-asyncio-python": {
+        "domain": "Python asyncio, concurrency",
+        "languages": ["py"],
+        "keywords": ["asyncio", "async def", "await", "coroutine", "event loop", "aiohttp", "async python", "concurrent python"],
+        "anti_keywords": [],
+    },
+    "web-scraping-python": {
+        "domain": "Web scraping, crawling",
+        "languages": ["py"],
+        "keywords": ["web scraping", "beautifulsoup", "scrapy", "crawl", "parse html", "selenium scraping"],
+        "anti_keywords": [],
+    },
+}
+
+CONFLICT_RULES = [
+    ("effective-python", "using-asyncio-python", "using-asyncio-python wins for async topics"),
+    ("kotlin-in-action", "effective-kotlin", "effective-kotlin wins for best practice advice"),
+    ("clean-code-reviewer", "effective-java", "effective-java wins for Java-specific items; use both for comprehensive review"),
+]
+
+
+def detect_language(file_path: str | None) -> str | None:
+    """Detect language from file extension."""
+    if not file_path:
+        return None
+    ext = os.path.splitext(file_path)[1].lstrip(".")
+    return ext.lower() if ext else None
+
+
+def score_skill(skill_name: str, skill_info: dict, task: str, language: str | None) -> float:
+    """Score a skill's relevance for a task. Higher = more relevant."""
+    task_lower = task.lower()
+    score = 0.0
+
+    # Keyword matching
+    for keyword in skill_info["keywords"]:
+        if keyword in task_lower:
+            score += 2.0
+
+    # Anti-keyword penalty
+    for anti_keyword in skill_info["anti_keywords"]:
+        if anti_keyword in task_lower:
+            score -= 3.0
+
+    # Language match bonus
+    if language and language in skill_info["languages"]:
+        score += 3.0
+    elif skill_info["languages"] and language and language not in skill_info["languages"]:
+        score -= 5.0  # Strong penalty for language mismatch
+
+    return score
+
+
+def route(task: str, file_path: str | None = None) -> dict:
+    """Route a task to the best skill(s)."""
+    language = detect_language(file_path)
+    task_lower = task.lower()
+
+    scores = {}
+    keyword_hits = {}
+    for skill_name, skill_info in SKILL_CATALOG.items():
+        scores[skill_name] = score_skill(skill_name, skill_info, task, language)
+        keyword_hits[skill_name] = any(kw in task_lower for kw in skill_info["keywords"])
+
+    # Sort by score, descending
+    ranked = sorted(scores.items(), key=lambda x: x[1], reverse=True)
+
+    # Require positive score AND at least one keyword hit to prevent
+    # language-match-only false positives (e.g. data-pipelines for any .py file)
+    candidates = [(name, score) for name, score in ranked if score > 0 and keyword_hits[name]]
+
+    if not candidates:
+        return {
+            "primary": None,
+            "secondary": None,
+            "dont_apply": None,
+            "conflict_note": None,
+            "language_detected": language,
+            "rationale": "No skill matched. Try describing the task with more domain keywords, or browse the skill catalog.",
+        }
+
+    primary_name, _ = candidates[0]
+    secondary = candidates[1] if len(candidates) > 1 else None
+    dont_apply = candidates[2] if len(candidates) > 2 else None
+
+    # Apply conflict resolution
+    conflict_note = None
+    if secondary:
+        for skill_a, skill_b, note in CONFLICT_RULES:
+            if (primary_name == skill_a and secondary[0] == skill_b) or \
+               (primary_name == skill_b and secondary[0] == skill_a):
+                conflict_note = note
+                break
+
+    return {
+        "primary": primary_name,
+        "primary_domain": SKILL_CATALOG[primary_name]["domain"],
+        "secondary": secondary[0] if secondary else None,
+        "secondary_domain": SKILL_CATALOG[secondary[0]]["domain"] if secondary else None,
+        "dont_apply": dont_apply[0] if dont_apply else None,
+        "dont_apply_domain": SKILL_CATALOG[dont_apply[0]]["domain"] if dont_apply else None,
+        "conflict_note": conflict_note,
+        "language_detected": language,
+    }
+
+
+def format_output(result: dict) -> str:
+    """Format routing result for CLI output."""
+    lines = []
+
+    if result.get("language_detected"):
+        lines.append(f"Detected language: .{result['language_detected']}")
+        lines.append("")
+
+    if not result["primary"]:
+        lines.append("No matching skill found.")
+        lines.append(result.get("rationale", ""))
+        return "\n".join(lines)
+
+    lines.append(f"**Primary skill:** `{result['primary']}`")
+    lines.append(f"**Why:** {result['primary_domain']}")
+
+    if result["secondary"]:
+        lines.append(f"**Secondary (optional):** `{result['secondary']}` — {result['secondary_domain']}")
+    else:
+        lines.append("**Secondary (optional):** none")
+
+    if result.get("dont_apply"):
+        lines.append(f"**Don't apply:** `{result['dont_apply']}` — {result['dont_apply_domain']} (lower relevance for this task)")
+
+    if result.get("conflict_note"):
+        lines.append(f"**Conflict resolution:** {result['conflict_note']}")
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Route a task to the best @booklib/skills skill",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""examples:
+  python route.py --task "review my Python class for code quality"
+  python route.py --file app/orders.py --task "review for correctness"
+  python route.py --task "design a saga for order processing"
+  python route.py --task "decompose my monolith into microservices"
+  python route.py --task "my bar chart is too cluttered"
+        """,
+    )
+    parser.add_argument("--file", help="Path to the file being reviewed (used for language detection)")
+    parser.add_argument("--task", required=True, help="Description of the task or question")
+    args = parser.parse_args()
+
+    result = route(task=args.task, file_path=args.file)
+    print(format_output(result))
+
+
+if __name__ == "__main__":
+    main()

package/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/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)