@booklib/skills 1.0.0 → 1.3.0

package/refactoring-ui/examples/after.md

@@ -0,0 +1,85 @@
+# After
+
+A pricing card with clear visual hierarchy achieved through size scale, weight contrast, and strategic color — the price is immediately scannable and the CTA stands out.
+
+```css
+/* Pricing card — clear hierarchy: plan name → price → description → features → CTA */
+.pricing-card {
+  padding: 32px;
+  border-radius: 8px;
+  background: #ffffff;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.07), 0 1px 3px rgba(0, 0, 0, 0.06);
+}
+
+/* Primary: the plan name — bold, medium size, dark */
+.plan-name {
+  font-size: 14px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: hsl(217, 71%, 53%);   /* brand accent — signals plan identity */
+  margin-bottom: 12px;
+}
+
+/* Hero element: price — the largest, heaviest thing on the card */
+.plan-price {
+  font-size: 48px;
+  font-weight: 700;
+  color: hsl(222, 47%, 11%);   /* near-black — maximum contrast */
+  line-height: 1;
+  margin-bottom: 4px;
+}
+
+.plan-billing-cycle {
+  font-size: 13px;
+  font-weight: 400;
+  color: hsl(215, 16%, 57%);   /* light grey — tertiary, supporting */
+  margin-bottom: 20px;
+}
+
+/* Secondary: description — readable but not competing with price */
+.plan-description {
+  font-size: 15px;
+  font-weight: 400;
+  color: hsl(215, 16%, 40%);   /* medium grey */
+  line-height: 1.6;
+  margin-bottom: 24px;
+}
+
+/* Tertiary: feature list — smallest, least emphasis */
+.plan-feature {
+  font-size: 14px;
+  font-weight: 400;
+  color: hsl(215, 16%, 47%);
+  margin-bottom: 8px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+/* CTA: high contrast, full width, inviting */
+.cta-button {
+  width: 100%;
+  padding: 14px;
+  font-size: 15px;
+  font-weight: 600;
+  background-color: hsl(217, 71%, 53%);
+  color: #ffffff;
+  border: none;
+  border-radius: 6px;
+  margin-top: 28px;
+  cursor: pointer;
+}
+
+.cta-button:hover {
+  background-color: hsl(217, 71%, 46%);
+}
+```
+
+Key improvements:
+- Three-tier hierarchy established using size (48px → 15px → 14px → 13px), weight (700 → 600 → 400), and color (near-black → medium grey → light grey) — no element competes with the price (Ch 2: Visual Hierarchy)
+- HSL colors replace raw hex — the system is transparent and the grey scale is predictable (Ch 5: Build a color system with HSL)
+- `box-shadow` with two layered shadows replaces the flat `border: 1px solid #ccc` — the card lifts off the page with realistic depth (Ch 6: Depth and shadow elevation)
+- `.plan-name` uses uppercase + letter-spacing as a tertiary-element technique — it occupies a clear role without competing with the price despite appearing first (Ch 2: De-emphasize labels, emphasize values)
+- Consistent spacing from the scale (12, 20, 24, 28px) replaces arbitrary margins — related elements are visually grouped (Ch 3: Spacing and layout)
+- CTA `padding: 14px` and `font-weight: 600` make the button unmistakably actionable, distinct from all other text on the card (Ch 8: Finishing touches)

package/refactoring-ui/examples/before.md

@@ -0,0 +1,58 @@
+# Before
+
+A CSS card component where every text element is the same size and weight, creating no visual hierarchy and making it impossible to scan at a glance.
+
+```css
+/* Pricing card — everything looks equally important */
+.pricing-card {
+  padding: 20px;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+}
+
+.plan-name {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 8px;
+}
+
+.plan-description {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 8px;
+}
+
+.plan-price {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 8px;
+}
+
+.plan-billing-cycle {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 16px;
+}
+
+.plan-feature {
+  font-size: 16px;
+  font-weight: 400;
+  color: #333;
+  margin-bottom: 4px;
+}
+
+.cta-button {
+  width: 100%;
+  padding: 10px;
+  font-size: 16px;
+  font-weight: 400;
+  background-color: #555;
+  color: white;
+  border: none;
+  border-radius: 4px;
+}
+```

package/refactoring-ui/scripts/audit_css.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""
+audit_css.py — Audit CSS/SCSS/HTML files for Refactoring UI anti-patterns.
+Usage: python audit_css.py <file_or_directory>
+
+Detects:
+  1. One-off hex colors (likely not from a design scale)
+  2. Arbitrary pixel values not on a standard spacing scale
+  3. Flat visual hierarchy (too many elements sharing the same font-size)
+  4. Inline styles in HTML (maintainability anti-pattern)
+"""
+
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+SPACING_SCALE = {4, 8, 10, 12, 14, 16, 18, 20, 24, 28, 32, 36, 40, 48, 56, 64, 80, 96, 112, 128}
+FLAT_HIERARCHY_THRESHOLD = 3   # more than N elements sharing same font-size
+EXTENSIONS = {".css", ".scss", ".html", ".htm"}
+
+# ---------------------------------------------------------------------------
+# Regex patterns
+# ---------------------------------------------------------------------------
+
+RE_HEX_COLOR = re.compile(r"#([0-9a-fA-F]{3,8})\b")
+RE_PX_VALUE = re.compile(r"\b(\d+)px\b")
+RE_FONT_SIZE_PX = re.compile(r"font-size\s*:\s*(\d+)px", re.IGNORECASE)
+RE_INLINE_STYLE = re.compile(r'\bstyle\s*=\s*["\'][^"\']*["\']', re.IGNORECASE)
+RE_CSS_VAR = re.compile(r"var\(--[^)]+\)")
+RE_SCSS_VAR = re.compile(r"\$[a-zA-Z_][\w-]*")
+
+# Pixel properties where arbitrary values matter (spacing/sizing, not borders)
+SPACING_PROPERTIES = re.compile(
+    r"(margin|padding|top|right|bottom|left|width|height|gap|"
+    r"border-radius|letter-spacing|line-height)\s*:",
+    re.IGNORECASE,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+Issue = dict  # {"line": int, "col": int, "code": str, "message": str, "suggestion": str}
+
+
+def read_lines(path: Path) -> list[str]:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError as exc:
+        print(f"Warning: cannot read {path}: {exc}")
+        return []
+
+
+def is_in_comment(line: str, col: int) -> bool:
+    """Rough check: is the match inside a CSS/HTML comment on this line?"""
+    before = line[:col]
+    return "/*" in before or "<!--" in before or "//" in before
+
+
+# ---------------------------------------------------------------------------
+# Detectors
+# ---------------------------------------------------------------------------
+
+def detect_one_off_hex_colors(lines: list[str], filepath: Path) -> list[Issue]:
+    """Flag hex colors that appear only once in the file — likely not from a scale."""
+    color_locations: dict[str, list[tuple[int, int]]] = defaultdict(list)
+    for lineno, line in enumerate(lines, 1):
+        for m in RE_HEX_COLOR.finditer(line):
+            # Skip if preceded by var( or $ (already a token)
+            prefix = line[max(0, m.start() - 10):m.start()]
+            if "var(" in prefix or "$" in prefix[-1:]:
+                continue
+            normalized = m.group(0).upper()
+            color_locations[normalized].append((lineno, m.start()))
+
+    issues = []
+    for color, locations in color_locations.items():
+        if len(locations) == 1:
+            lineno, col = locations[0]
+            issues.append({
+                "line": lineno, "col": col + 1,
+                "code": "RUI-C01",
+                "message": f"One-off color {color} — not reused anywhere in this file",
+                "suggestion": f"Extract to a CSS variable: --color-name: {color}; and reference via var(--color-name)",
+            })
+    return issues
+
+
+def detect_arbitrary_px_values(lines: list[str], filepath: Path) -> list[Issue]:
+    """Flag pixel values on spacing properties that fall outside the spacing scale."""
+    issues = []
+    in_spacing_context = False
+    for lineno, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if SPACING_PROPERTIES.search(stripped):
+            for m in RE_PX_VALUE.finditer(stripped):
+                value = int(m.group(1))
+                if value == 0 or value in SPACING_SCALE:
+                    continue
+                if is_in_comment(line, m.start()):
+                    continue
+                nearest = min(SPACING_SCALE, key=lambda s: abs(s - value))
+                issues.append({
+                    "line": lineno, "col": m.start() + 1,
+                    "code": "RUI-S01",
+                    "message": f"Arbitrary pixel value {value}px not on spacing scale",
+                    "suggestion": f"Nearest scale value: {nearest}px. Consider using a spacing token.",
+                })
+    return issues
+
+
+def detect_flat_hierarchy(lines: list[str], filepath: Path) -> list[Issue]:
+    """Flag when many rules share the same font-size — suggests flat visual hierarchy."""
+    size_locations: dict[int, list[tuple[int, int]]] = defaultdict(list)
+    for lineno, line in enumerate(lines, 1):
+        for m in RE_FONT_SIZE_PX.finditer(line):
+            size = int(m.group(1))
+            size_locations[size].append((lineno, m.start()))
+
+    issues = []
+    for size, locations in size_locations.items():
+        if len(locations) > FLAT_HIERARCHY_THRESHOLD:
+            # Report at the first occurrence
+            lineno, col = locations[0]
+            issues.append({
+                "line": lineno, "col": col + 1,
+                "code": "RUI-H01",
+                "message": (
+                    f"font-size: {size}px used {len(locations)} times — "
+                    f"indicates flat visual hierarchy"
+                ),
+                "suggestion": (
+                    "Refactoring UI: vary font sizes more aggressively to create "
+                    "clear hierarchy. Use a type scale (e.g. 12, 14, 16, 20, 24, 32, 48px)."
+                ),
+            })
+    return issues
+
+
+def detect_inline_styles(lines: list[str], filepath: Path) -> list[Issue]:
+    """Flag inline style= attributes in HTML files."""
+    if filepath.suffix.lower() not in {".html", ".htm"}:
+        return []
+    issues = []
+    for lineno, line in enumerate(lines, 1):
+        for m in RE_INLINE_STYLE.finditer(line):
+            issues.append({
+                "line": lineno, "col": m.start() + 1,
+                "code": "RUI-M01",
+                "message": f"Inline style attribute — hard to maintain and override",
+                "suggestion": "Move styles to a CSS class. Inline styles defeat cascade and make theming impossible.",
+            })
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Scanner
+# ---------------------------------------------------------------------------
+
+def scan_file(path: Path) -> list[Issue]:
+    lines = read_lines(path)
+    if not lines:
+        return []
+    issues = []
+    issues.extend(detect_one_off_hex_colors(lines, path))
+    issues.extend(detect_arbitrary_px_values(lines, path))
+    issues.extend(detect_flat_hierarchy(lines, path))
+    issues.extend(detect_inline_styles(lines, path))
+    return sorted(issues, key=lambda i: (i["line"], i["col"]))
+
+
+def collect_files(target: Path) -> list[Path]:
+    if target.is_file():
+        return [target] if target.suffix.lower() in EXTENSIONS else []
+    return sorted(p for p in target.rglob("*") if p.suffix.lower() in EXTENSIONS)
+
+
+# ---------------------------------------------------------------------------
+# Report
+# ---------------------------------------------------------------------------
+
+def print_report(results: dict[Path, list[Issue]]) -> int:
+    total = sum(len(v) for v in results.values())
+    files_with_issues = sum(1 for v in results.values() if v)
+
+    print("=" * 72)
+    print("REFACTORING UI CSS AUDIT REPORT")
+    print("=" * 72)
+
+    # Group by code across all files for summary
+    by_code: dict[str, list[tuple[Path, Issue]]] = defaultdict(list)
+
+    for path, issues in results.items():
+        if not issues:
+            continue
+        print(f"\n{path}")
+        print("-" * 72)
+        for issue in issues:
+            print(f"  Line {issue['line']:>4}:{issue['col']:<4} [{issue['code']}] {issue['message']}")
+            print(f"           -> {issue['suggestion']}")
+            by_code[issue["code"]].append((path, issue))
+
+    print("\n" + "=" * 72)
+    print("SUMMARY")
+    print("=" * 72)
+    CODE_LABELS = {
+        "RUI-C01": "One-off colors (not from a scale)",
+        "RUI-S01": "Arbitrary pixel values",
+        "RUI-H01": "Flat visual hierarchy",
+        "RUI-M01": "Inline styles in HTML",
+    }
+    for code, label in CODE_LABELS.items():
+        count = len(by_code.get(code, []))
+        marker = "[!]" if count else "[OK]"
+        print(f"  {marker} {label}: {count} issue(s)")
+
+    print(f"\nFiles scanned : {len(results)}")
+    print(f"Files with issues: {files_with_issues}")
+    print(f"Total issues  : {total}")
+    print("=" * 72)
+    return total
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python audit_css.py <file_or_directory>")
+        sys.exit(1)
+
+    target = Path(sys.argv[1])
+    if not target.exists():
+        print(f"Error: path not found: {target}")
+        sys.exit(1)
+
+    files = collect_files(target)
+    if not files:
+        print(f"No CSS/SCSS/HTML files found in: {target}")
+        sys.exit(0)
+
+    results = {f: scan_file(f) for f in files}
+    total = print_report(results)
+    sys.exit(1 if total else 0)
+
+
+if __name__ == "__main__":
+    main()

package/skill-router/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: skill-router
+description: >
+  Select the 1-2 most relevant @booklib/skills for a given file, PR, or task.
+  Use before applying any skill when unsure which book's lens applies, or when
+  multiple skills could apply. Trigger on "which skill", "which book", "route this",
+  "what skill should I use", or whenever a user describes a task without specifying
+  a skill. Returns a ranked recommendation with rationale and anti-triggers.
+---
+
+# Skill Router
+
+You are a skill selector for the `@booklib/skills` library — a collection of 17 book-based AI skills covering code quality, architecture, language best practices, and design. Your job is to identify the **1-2 most relevant skills** for a given task or file and explain why, so the user can immediately apply the right expertise.
+
+## When You're Triggered
+
+- User says "which skill should I use for..."
+- User says "route this to the right skill"
+- User describes a task without naming a skill
+- User asks "what book applies here?"
+- Multiple skills seem to apply and you need to rank them
+
+---
+
+## Routing Process
+
+### Step 1 — Classify the Work Type
+
+Identify what the user is trying to do:
+
+| Work Type | Description | Example |
+|-----------|-------------|---------|
+| **review** | Evaluate existing code for quality, patterns, or correctness | "Review my Python class" |
+| **generate** | Create new code following a book's patterns | "Generate a saga for order processing" |
+| **migrate** | Incrementally improve legacy code toward a better architecture | "Help me ratchet this legacy codebase toward clean code" |
+| **design** | Make architectural or system-level decisions | "How should I decompose this monolith?" |
+| **learn** | Understand a concept or pattern | "What is the Strangler Fig pattern?" |
+| **visualize** | Create or critique data visualizations or UI | "Review my chart / UI component" |
+
+### Step 2 — Identify Language + Domain
+
+From the file extension, imports, description, or code provided:
+
+- **Language signals:** `.py` → Python skills; `.java` → `effective-java` or `clean-code-reviewer`; `.kt` → `effective-kotlin` or `kotlin-in-action`; `.js`/`.ts` → `clean-code-reviewer` or `design-patterns`
+- **Domain signals:** "microservice", "saga" → microservices-patterns; "bounded context", "aggregate" → domain-driven-design; "chart", "visualization" → storytelling-with-data; "UI", "layout", "typography" → refactoring-ui; "web scraping", "BeautifulSoup" → web-scraping-python; "asyncio", "coroutine" → using-asyncio-python; "data pipeline", "ETL" → data-pipelines; "replication", "partitioning", "database internals" → data-intensive-patterns
+- **Architecture signals:** "monolith decomposition", "distributed systems" → microservices-patterns or system-design-interview
+
+Read `references/skill-catalog.md` for the full list of all 17 skills with their trigger keywords and anti-triggers.
+
+### Step 3 — Match to Skill(s)
+
+Apply these primary routing rules:
+
+1. **Code quality review (any language)** → `clean-code-reviewer`
+2. **Java best practices** → `effective-java`
+3. **Kotlin best practices** → `effective-kotlin` or `kotlin-in-action` (see conflict rules)
+4. **Python best practices** → `effective-python`
+5. **Python asyncio/concurrency** → `using-asyncio-python` (overrides effective-python for async topics)
+6. **Python web scraping** → `web-scraping-python`
+7. **OO design patterns (GoF)** → `design-patterns`
+8. **Domain modeling, DDD** → `domain-driven-design`
+9. **Microservices, sagas, decomposition** → `microservices-patterns`
+10. **System scalability, estimation** → `system-design-interview`
+11. **Data storage internals, replication** → `data-intensive-patterns`
+12. **Data pipelines, ETL** → `data-pipelines`
+13. **UI design, visual hierarchy** → `refactoring-ui`
+14. **Charts, data visualization** → `storytelling-with-data`
+15. **Web animation** → `animation-at-work`
+16. **Startup strategy, MVP** → `lean-startup`
+17. **Routing help** → `skill-router` (this skill)
+
+Read `references/routing-heuristics.md` for detailed decision rules and conflict resolution.
+
+### Step 4 — Check for Conflicts
+
+Some skill pairs can conflict. Resolve using these rules:
+
+| Conflict | Resolution |
+|----------|------------|
+| `clean-code-reviewer` vs `effective-java` | Use `effective-java` for Java-specific idioms (generics, enums, builders); use `clean-code-reviewer` for naming/functions/readability which applies cross-language |
+| `effective-kotlin` vs `kotlin-in-action` | `effective-kotlin` for best practices and pitfall avoidance; `kotlin-in-action` for learning Kotlin language features |
+| `domain-driven-design` vs `microservices-patterns` | `domain-driven-design` for domain model design; `microservices-patterns` for service decomposition and inter-service communication. Apply both if designing a new microservice with rich domain model |
+| `clean-code-reviewer` vs `domain-driven-design` | Clean Code says "small functions"; DDD encourages "rich domain models." Clean Code wins for code-level review; DDD wins for model design |
+| `data-intensive-patterns` vs `system-design-interview` | `data-intensive-patterns` for storage engine internals, replication, and consistency; `system-design-interview` for scalability estimates and high-level architecture |
+| `effective-python` vs `using-asyncio-python` | `using-asyncio-python` wins for any async/concurrent Python topic; `effective-python` for everything else |
+
+### Step 5 — Return Recommendation
+
+Format your output as:
+
+```
+**Primary skill:** `skill-name`
+**Why:** [1-2 sentence rationale tying the task to the skill's domain]
+**Secondary (optional):** `skill-name` — [brief rationale] OR none
+**Don't apply:** `skill-name` — [why it would produce irrelevant feedback]
+```
+
+If you're genuinely uncertain between two equally applicable skills, say so and recommend applying both in sequence, primary first.
+
+---
+
+## Anti-Trigger Rules
+
+Do NOT route to a skill if:
+- The task is too simple for that skill's complexity (don't route a 5-line script to `domain-driven-design`)
+- The language doesn't match (don't route Python to `effective-java`)
+- The domain doesn't match (don't route UI code to `microservices-patterns`)
+- The user has already specified a skill (respect their choice; only offer alternatives if asked)
+
+---
+
+## Examples
+
+**Example 1 — Clear single-skill case:**
+```
+User: "Review my Python class for code quality"
+
+Primary skill: clean-code-reviewer
+Why: Language-agnostic code quality review is exactly Clean Code's domain — naming, functions, comments, classes.
+Secondary: none
+Don't apply: effective-python — Python-specific idioms are not the concern here; effective-python would focus on list comprehensions and context managers, not the general code quality issues Clean Code addresses.
+```
+
+**Example 2 — Conflict case:**
+```
+User: "I'm building a new microservice for our e-commerce platform. Review the domain model."
+
+Primary skill: domain-driven-design
+Why: The request is about domain model design — Aggregates, Value Objects, Bounded Contexts. DDD is the authoritative source.
+Secondary: microservices-patterns — apply after DDD review to check service boundaries, database ownership, and communication patterns.
+Don't apply: clean-code-reviewer — code quality review is premature at the design stage; apply later when implementation code exists.
+```
+
+**Example 3 — Already routed (positive case):**
+```
+User: "Use the effective-java skill to review my builder pattern"
+
+Primary skill: effective-java (already specified by user — confirm and proceed)
+Why: User correctly identified the skill. effective-java Item 2 covers the Builder pattern directly.
+Secondary: none
+Don't apply: design-patterns — GoF Builder pattern is covered, but Effective Java's opinionated take on Java-specific Builder is more directly applicable.
+```

package/skill-router/evals/evals.json

@@ -0,0 +1,38 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-clear-single-skill",
+      "prompt": "Which skill should I use? I have this Python function and want to make it more Pythonic:\n\n```python\ndef get_items(items_list, filter_value, sort_by_name):\n    result = []\n    for item in items_list:\n        if item['category'] == filter_value:\n            result.append(item)\n    if sort_by_name:\n        result = sorted(result, key=lambda x: x['name'])\n    return result\n```",
+      "expectations": [
+        "Recommends effective-python as primary skill",
+        "Mentions that Pythonic idioms (list comprehensions, key functions, boolean flags) are effective-python's domain",
+        "Does NOT recommend clean-code-reviewer as primary (it's secondary at most)",
+        "Explains why (language-specific Pythonic advice vs general code quality)",
+        "Optionally mentions clean-code-reviewer as secondary for the flag argument (sort_by_name)"
+      ]
+    },
+    {
+      "id": "eval-02-conflict-case",
+      "prompt": "I'm designing a new service for our e-commerce platform. The service will handle order creation and needs to coordinate with the inventory and payment services. Here's a rough sketch:\n\n```python\nclass OrderService:\n    def create_order(self, customer_id, items):\n        # 1. Check inventory availability\n        # 2. Reserve inventory\n        # 3. Charge payment\n        # If payment fails, how do I release the reservation?\n        pass\n\n    def cancel_order(self, order_id):\n        # Need to reverse payment AND release inventory\n        # What if one fails?\n        pass\n```\n\nWhich skill should I use to design this coordination correctly?",
+      "expectations": [
+        "Identifies this as a design task, not a code review task",
+        "Recommends microservices-patterns as primary (service coordination, saga pattern)",
+        "Recommends domain-driven-design as secondary (order domain modeling)",
+        "Explains the distinction: microservices-patterns for inter-service coordination, DDD for domain model design",
+        "Does NOT recommend clean-code-reviewer (no code to review yet)",
+        "Does NOT recommend system-design-interview unless scale/estimation is mentioned"
+      ]
+    },
+    {
+      "id": "eval-03-already-routed",
+      "prompt": "Use the effective-java skill to review my enum usage:\n\n```java\npublic class OrderStatus {\n    public static final int PENDING = 0;\n    public static final int APPROVED = 1;\n    public static final int REJECTED = 2;\n    public static final int CANCELLED = 3;\n}\n```",
+      "expectations": [
+        "Confirms effective-java is the correct skill (already specified by user)",
+        "Does NOT override the user's skill choice",
+        "Optionally notes which Effective Java item applies (Item 34: Use enums instead of int constants)",
+        "May note clean-code-reviewer would also flag this (J3: Constants vs Enums) but defers to user's choice",
+        "Does not second-guess or add unnecessary routing complexity"
+      ]
+    }
+  ]
+}

package/skill-router/examples/after.md

@@ -0,0 +1,63 @@
+# After: Routed Code Review Request
+
+## User Message (same as before)
+
+> "Can you review my code? I want to make it better."
+>
+> ```java
+> public class OrderProcessor {
+>     private static List<Map<String, Object>> pendingOrders = new ArrayList<>();
+>     
+>     public static int process(Map<String, Object> o, boolean isAdmin, boolean sendEmail) {
+>         if (o == null) return -1;
+>         if (o.get("status").equals("pending")) {
+>             if (isAdmin) {
+>                 o.put("status", "approved");
+>                 pendingOrders.remove(o);
+>                 if (sendEmail) {
+>                     System.out.println("Sending email to: " + o.get("customerEmail"));
+>                 }
+>                 return 0;
+>             }
+>         }
+>         return -2;
+>     }
+> }
+> ```
+
+## Skill Router Output
+
+**Primary skill:** `clean-code-reviewer`
+**Why:** The user wants general code quality improvement for a Java class. The dominant issues are language-agnostic: poor naming (`o`, `isAdmin` flag arg, magic return codes), static mutable state, nested conditionals, and multiple responsibilities — all Clean Code's territory.
+**Secondary (optional):** `effective-java` — after the Clean Code review, apply Effective Java for Java-specific improvements: replace `Map<String, Object>` with a typed class (Item 64: refer to objects by their interfaces), use enums instead of int return codes (Item 34).
+**Don't apply:** `domain-driven-design` — while an Order is a domain concept, applying DDD here would produce advice about Aggregates and Bounded Contexts that is premature. Fix the code quality first.
+
+---
+
+## What the Clean Code Review Produces
+
+With the right skill applied, the review is sharp and specific:
+
+### Issues Found
+
+🔴 **Critical — F3: Flag Arguments**
+`isAdmin` and `sendEmail` are boolean flags — the function does 4 different things depending on their combination. Split into `approveAsAdmin()` and keep email logic separate.
+
+🔴 **Critical — Shared Mutable Static State (Ch. 13)**
+`pendingOrders` is a static mutable list — not thread-safe and makes the class impossible to test in isolation.
+
+🔴 **Critical — Error Codes Instead of Exceptions (Ch. 7)**
+Returning `-1` and `-2` forces callers to check magic numbers. Throw `InvalidOrderException` and `UnauthorizedOperationException` instead.
+
+🟡 **Important — N1: Poor Naming**
+`o`, `process` — names reveal nothing. `o` → `order`, `process` → `approveOrder`.
+
+🟡 **Important — G30: Function Does Multiple Things**
+`process()` validates, approves, removes from list, and sends email. Each is a separate responsibility.
+
+🟢 **Suggestion — G25: Magic Numbers**
+Return codes `-1`, `-2` should be named constants at minimum, or better: exceptions.
+
+### Result
+
+The user gets a **focused, actionable review** from one authoritative source — not a scattered survey of four books.

package/skill-router/examples/before.md

@@ -0,0 +1,39 @@
+# Before: Unrouted Code Review Request
+
+## User Message
+
+> "Can you review my code? I want to make it better."
+>
+> ```java
+> public class OrderProcessor {
+>     private static List<Map<String, Object>> pendingOrders = new ArrayList<>();
+>     
+>     public static int process(Map<String, Object> o, boolean isAdmin, boolean sendEmail) {
+>         if (o == null) return -1;
+>         if (o.get("status").equals("pending")) {
+>             if (isAdmin) {
+>                 o.put("status", "approved");
+>                 pendingOrders.remove(o);
+>                 if (sendEmail) {
+>                     System.out.println("Sending email to: " + o.get("customerEmail"));
+>                 }
+>                 return 0;
+>             }
+>         }
+>         return -2;
+>     }
+> }
+> ```
+
+## What Happens Without Routing
+
+The AI must guess which lens to apply:
+
+- Does the user want **Java-specific** advice (Effective Java)? → Bloch would focus on generics, raw types, and static factory methods
+- Do they want **code quality** advice (Clean Code)? → Martin would focus on naming, flag arguments, static mutable state
+- Do they want **design pattern** advice (Design Patterns)? → Gang of Four would examine whether a Command or Strategy pattern fits
+- Do they want **domain modeling** advice (DDD)? → Evans would ask about Aggregates and Value Objects
+
+**Result:** The AI either picks one arbitrarily, tries to cover all four superficially, or asks a clarifying question that could have been avoided.
+
+The user gets a scattered review that's 40% relevant from four different books instead of a sharp, deep review from the right one.