@booklib/core 2.0.0

package/skills/storytelling-with-data/scripts/chart_review.py

@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+"""
+chart_review.py - Review a chart specification against Storytelling with Data principles.
+
+Usage:
+    python chart_review.py <spec-file.json>
+
+Spec file format (JSON):
+    {
+      "title": "Sales by Region Q4",
+      "chart_type": "pie",
+      "data_points": 8,
+      "colors": ["#ff0000", "#00ff00"],
+      "has_gridlines": true,
+      "has_legend": true,
+      "has_direct_labels": false,
+      "is_3d": false,
+      "y_axis_starts_at_zero": true
+    }
+
+All fields are optional. Unrecognised fields are ignored.
+
+Based on "Storytelling with Data" by Cole Nussbaumer Knaflic.
+Each finding references the relevant chapter.
+"""
+
+import argparse
+import json
+import pathlib
+import sys
+from typing import Any
+
+# Severity ordering for output
+PRIORITY_ORDER = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
+
+CHART_TYPE_ALIASES: dict[str, str] = {
+    "pie": "pie",
+    "donut": "pie",
+    "doughnut": "pie",
+    "bar": "bar",
+    "column": "bar",
+    "horizontal bar": "bar",
+    "stacked bar": "bar",
+    "line": "line",
+    "area": "line",
+    "scatter": "scatter",
+    "bubble": "scatter",
+    "table": "table",
+    "heatmap": "table",
+}
+
+# Action verbs that indicate a title states a finding rather than just labelling axes.
+INSIGHT_VERBS = {
+    "grew", "declined", "increased", "decreased", "outperformed", "underperformed",
+    "surpassed", "dropped", "rose", "fell", "exceeded", "missed", "reached",
+    "shows", "reveals", "demonstrates", "highlights", "indicates", "confirms",
+    "beats", "lags", "leads", "trails", "spikes", "dips",
+}
+
+
+def load_spec(path: pathlib.Path) -> dict[str, Any]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        print(f"ERROR: Cannot read file: {exc}")
+        sys.exit(1)
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        print(f"ERROR: Invalid JSON in {path}: {exc}")
+        sys.exit(1)
+
+
+def normalize_chart_type(raw: str) -> str:
+    return CHART_TYPE_ALIASES.get(raw.lower().strip(), raw.lower().strip())
+
+
+def title_is_action_oriented(title: str) -> bool:
+    """Return True if the title starts with or contains an insight verb."""
+    first_word = title.strip().split()[0].lower().rstrip(".,;:") if title.strip() else ""
+    if first_word in INSIGHT_VERBS:
+        return True
+    # Also accept titles where an insight verb appears early (within first 4 words)
+    words = [w.lower().rstrip(".,;:") for w in title.strip().split()[:4]]
+    return any(w in INSIGHT_VERBS for w in words)
+
+
+def check_spec(spec: dict[str, Any]) -> list[dict[str, str]]:
+    findings: list[dict[str, str]] = []
+
+    def add(priority: str, chapter: str, principle: str, detail: str, recommendation: str) -> None:
+        findings.append({
+            "priority": priority,
+            "chapter": chapter,
+            "principle": principle,
+            "detail": detail,
+            "recommendation": recommendation,
+        })
+
+    chart_type_raw = spec.get("chart_type", "")
+    chart_type = normalize_chart_type(chart_type_raw) if chart_type_raw else ""
+    data_points = spec.get("data_points")
+    colors = spec.get("colors", [])
+    has_gridlines = spec.get("has_gridlines", False)
+    has_legend = spec.get("has_legend", False)
+    has_direct_labels = spec.get("has_direct_labels", False)
+    is_3d = spec.get("is_3d", False)
+    y_axis_zero = spec.get("y_axis_starts_at_zero", True)
+    title = spec.get("title", "")
+
+    # Check 1: Pie charts with more than 4 slices
+    if chart_type == "pie" and data_points is not None and data_points > 4:
+        add(
+            priority="HIGH",
+            chapter="Chapter 2 - Choosing an Effective Visual",
+            principle="Avoid pie charts with many slices",
+            detail=f"Pie chart has {data_points} slices. Humans cannot accurately compare non-adjacent arc lengths.",
+            recommendation=(
+                "Use a horizontal bar chart sorted by value. "
+                "Bars make magnitude comparison trivial and scale to many categories."
+            ),
+        )
+
+    # Check 2: More than 5 colors
+    if len(colors) > 5:
+        add(
+            priority="HIGH",
+            chapter="Chapter 4 - Focus Your Audience's Attention",
+            principle="Use color strategically, not decoratively",
+            detail=f"{len(colors)} colors used. More than 5 colors overwhelm the eye and dilute emphasis.",
+            recommendation=(
+                "Grey out all categories except the one(s) you want to highlight. "
+                "Use a single accent color to draw the eye to the key insight."
+            ),
+        )
+
+    # Check 3: Gridlines present
+    if has_gridlines:
+        add(
+            priority="MEDIUM",
+            chapter="Chapter 3 - Clutter Is Your Enemy",
+            principle="Remove chart junk and non-data ink",
+            detail="Gridlines are present. They add visual noise without adding information.",
+            recommendation=(
+                "Remove gridlines entirely, or replace with light grey (#e0e0e0) hairlines. "
+                "If reference values matter, use direct annotations on the data instead."
+            ),
+        )
+
+    # Check 4: Legend without direct labels
+    if has_legend and not has_direct_labels:
+        add(
+            priority="MEDIUM",
+            chapter="Chapter 5 - Think Like a Designer",
+            principle="Label data directly to reduce cognitive load",
+            detail=(
+                "A legend forces the reader to look away from the data to decode colors. "
+                "This interrupts the reading flow."
+            ),
+            recommendation=(
+                "Place labels directly next to each data series or bar. "
+                "Remove the legend. Direct labelling reduces eye travel and speeds comprehension."
+            ),
+        )
+
+    # Check 5: 3D charts
+    if is_3d:
+        add(
+            priority="HIGH",
+            chapter="Chapter 2 - Choosing an Effective Visual",
+            principle="Never use 3D visualisations",
+            detail=(
+                "3D perspective distorts relative bar/slice sizes due to foreshortening. "
+                "Viewers cannot accurately read values from a 3D chart."
+            ),
+            recommendation=(
+                "Switch to a flat 2D version of the same chart type. "
+                "If depth is meant to encode a third variable, use facets or bubble size instead."
+            ),
+        )
+
+    # Check 6: Title not action-oriented
+    if title:
+        if not title_is_action_oriented(title):
+            add(
+                priority="LOW",
+                chapter="Chapter 6 - Dissecting Model Visuals",
+                principle="Title should state the insight, not label the axes",
+                detail=(
+                    f"Title '{title}' describes what the chart shows but does not communicate "
+                    "the key takeaway. Readers must infer the insight themselves."
+                ),
+                recommendation=(
+                    "Rewrite the title as a one-sentence finding: e.g., "
+                    "'APAC revenue grew 34% year-over-year, outpacing all other regions.' "
+                    "This tells readers what to think before they look at the data."
+                ),
+            )
+    else:
+        add(
+            priority="MEDIUM",
+            chapter="Chapter 6 - Dissecting Model Visuals",
+            principle="Every chart needs a title",
+            detail="No title field found in the spec. Untitled charts require readers to form their own interpretation.",
+            recommendation=(
+                "Add a descriptive, insight-oriented title that states the key finding directly."
+            ),
+        )
+
+    # Check 7: Bar chart not starting at zero
+    if chart_type == "bar" and y_axis_zero is False:
+        add(
+            priority="HIGH",
+            chapter="Chapter 2 - Choosing an Effective Visual",
+            principle="Bar charts must start at zero",
+            detail=(
+                "The y-axis does not start at zero. Because bar length encodes value, "
+                "a truncated axis makes small differences appear dramatically large."
+            ),
+            recommendation=(
+                "Set the y-axis baseline to zero. "
+                "If the differences are genuinely small, switch to a line chart, "
+                "which does not rely on bar length to encode magnitude."
+            ),
+        )
+
+    # Check 8: Pie chart for proportional data — general advisory
+    if chart_type == "pie":
+        add(
+            priority="LOW",
+            chapter="Chapter 2 - Choosing an Effective Visual",
+            principle="Pie charts are rarely the best choice",
+            detail=(
+                "Even well-formed pie charts are harder to read than bar charts "
+                "because humans are poor at judging angles and arc lengths."
+            ),
+            recommendation=(
+                "Consider a single stacked bar (for part-to-whole) or a simple bar chart. "
+                "Use a pie only when: (a) there are 2-3 slices and (b) the exact proportions matter less than the part-to-whole story."
+            ),
+        )
+
+    return findings
+
+
+def print_findings(findings: list[dict[str, str]]) -> None:
+    sorted_findings = sorted(findings, key=lambda f: PRIORITY_ORDER.get(f["priority"], 99))
+
+    if not sorted_findings:
+        print("No issues found. The chart spec looks good against Storytelling with Data principles.")
+        return
+
+    print(f"Found {len(sorted_findings)} issue(s):\n")
+    for i, finding in enumerate(sorted_findings, start=1):
+        priority = finding["priority"]
+        priority_display = f"[{priority}]"
+        print(f"{i}. {priority_display} {finding['principle']}")
+        print(f"   Chapter      : {finding['chapter']}")
+        print(f"   Detail       : {finding['detail']}")
+        print(f"   Recommended  : {finding['recommendation']}")
+        print()
+
+    counts = {"HIGH": 0, "MEDIUM": 0, "LOW": 0}
+    for f in findings:
+        counts[f["priority"]] = counts.get(f["priority"], 0) + 1
+
+    print("=" * 60)
+    print("PRIORITY SUMMARY")
+    print("=" * 60)
+    for level in ("HIGH", "MEDIUM", "LOW"):
+        if counts[level]:
+            print(f"  {counts[level]:2d}  {level}")
+    print(f"  --")
+    print(f"  {sum(counts.values()):2d}  Total")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Review a chart specification against Storytelling with Data principles."
+    )
+    parser.add_argument(
+        "spec_file",
+        help="Path to a JSON chart specification file.",
+    )
+    args = parser.parse_args()
+
+    spec_path = pathlib.Path(args.spec_file)
+    if not spec_path.exists():
+        print(f"ERROR: File not found: {spec_path}")
+        sys.exit(1)
+
+    spec = load_spec(spec_path)
+    findings = check_spec(spec)
+    print_findings(findings)
+
+    has_high = any(f["priority"] == "HIGH" for f in findings)
+    sys.exit(2 if has_high else (1 if findings else 0))
+
+
+if __name__ == "__main__":
+    main()

package/skills/storytelling-with-data/scripts/example.py

@@ -0,0 +1 @@
+

package/skills/system-design-interview/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: system-design-interview
+version: "1.0"
+license: MIT
+tags: [architecture, distributed-systems, scalability]
+description: >
+  Apply system design principles from System Design Interview by Alex Xu.
+  Covers scaling (load balancing, DB replication, sharding, caching, CDN),
+  estimation (QPS, storage, bandwidth), the 4-step framework, and 12 real
+  designs: rate limiter, consistent hashing, key-value store, unique ID
+  generator, URL shortener, web crawler, notification system, news feed,
+  chat system, search autocomplete, YouTube, Google Drive. Trigger on
+  "system design", "scale", "high-level design", "distributed system",
+  "rate limiter", "consistent hashing", "back-of-envelope", "QPS",
+  "sharding", "load balancer", "CDN", "cache", "message queue",
+  "web crawler", "news feed", "chat system", "autocomplete", "URL shortener".
+---
+
+# System Design Interview Skill
+
+You are an expert system design advisor grounded in the 16 chapters from
+*System Design Interview* by Alex Xu. You help in two modes:
+
+1. **Design Application** — Apply system design principles to architect solutions for real problems
+2. **Design Review** — Analyze existing system architectures and recommend improvements
+
+## How to Decide Which Mode
+
+- If the user asks to *design*, *architect*, *build*, *scale*, or *plan* a system → **Design Application**
+- If the user asks to *review*, *evaluate*, *audit*, *assess*, or *improve* an existing design → **Design Review**
+- If ambiguous, ask briefly which mode they'd prefer
+
+---
+
+## Mode 1: Design Application
+
+When helping design systems, follow this decision flow:
+
+### Step 1 — Understand the Context
+
+Ask (or infer from context):
+
+- **What system?** — What type of system are we designing?
+- **What scale?** — Expected users, QPS, storage, bandwidth?
+- **What constraints?** — Latency requirements, availability target, cost budget?
+- **What scope?** — Full system or specific component?
+
+### Step 2 — Apply the 4-Step Framework (Ch 3)
+
+Every design should follow:
+
+1. **Understand the problem and establish design scope** (3–10 min) — Clarify requirements, define functional and non-functional requirements, make back-of-envelope estimates
+2. **Propose high-level design and get buy-in** (10–15 min) — Draw initial blueprint, identify main components, propose APIs
+3. **Design deep dive** (10–25 min) — Dive into 2–3 critical components, discuss trade-offs
+4. **Wrap up** (3–5 min) — Summarize, discuss error handling, operational concerns, scaling
+
+### Step 3 — Apply the Right Practices
+
+Read `references/api_reference.md` for the full chapter-by-chapter catalog. Quick decision guide:
+
+| Concern | Chapters to Apply |
+|---------|-------------------|
+| Scaling from zero to millions | Ch 1: Load balancer, DB replication, cache, CDN, sharding, message queue, stateless tier |
+| Estimating capacity | Ch 2: Powers of 2, latency numbers, QPS/storage/bandwidth estimation |
+| Structuring the interview | Ch 3: 4-step framework (scope → high-level → deep dive → wrap up) |
+| Controlling request rates | Ch 4: Token bucket, leaking bucket, fixed/sliding window, Redis-based distributed rate limiting |
+| Distributing data evenly | Ch 5: Consistent hashing, hash ring, virtual nodes |
+| Building distributed storage | Ch 6: CAP theorem, quorum consensus (N/W/R), vector clocks, gossip protocol, Merkle trees |
+| Generating unique IDs | Ch 7: Multi-master, UUID, ticket server, Twitter snowflake approach |
+| Shortening URLs | Ch 8: Hash + collision resolution, base-62 conversion, 301 vs 302 redirects |
+| Crawling the web | Ch 9: BFS traversal, URL frontier (politeness/priority queues), robots.txt, content dedup |
+| Sending notifications | Ch 10: APNs/FCM push, SMS, email; notification log, retry, dedup, rate limiting, templates |
+| Building news feeds | Ch 11: Fanout on write vs read, hybrid for celebrities, cache layers (content, social graph, counters) |
+| Real-time messaging | Ch 12: WebSocket, long polling, stateful chat services, key-value store, presence, service discovery |
+| Search autocomplete | Ch 13: Trie data structure, data gathering service, query service, browser caching, sharding |
+| Video streaming | Ch 14: Upload flow, DAG-based transcoding, streaming protocols, CDN cost optimization, pre-signed URLs |
+| Cloud file storage | Ch 15: Block servers, delta sync, resumable upload, metadata DB, long-polling notifications, conflict resolution |
+
+### Step 4 — Design the System
+
+Follow these principles:
+
+- **Start simple, then scale** — Begin with single-server, identify bottlenecks, scale incrementally
+- **Estimate first** — Use back-of-envelope estimation to validate feasibility
+- **Identify bottlenecks** — Find the single points of failure and address them
+- **Trade-offs explicit** — Every design decision has trade-offs; state them clearly
+- **Consider failures** — Design for failure: replication, retry, graceful degradation
+
+When applying design, produce:
+
+1. **Requirements** — Functional and non-functional requirements, constraints
+2. **Back-of-envelope estimation** — QPS, storage, bandwidth, memory estimates
+3. **High-level design** — Main components and how they interact
+4. **Deep dive** — 2–3 most critical components with detailed design
+5. **Operational concerns** — Error handling, monitoring, scaling plan
+
+### Design Application Examples
+
+**Example 1 — Rate Limiter:**
+```
+User: "Design a rate limiter for our API"
+
+Apply: Ch 4 (rate limiting algorithms), Ch 1 (scaling concepts)
+
+Generate:
+- Clarify: per-user or per-IP? HTTP API? Distributed?
+- Evaluate algorithms: token bucket (API rate limiting), sliding window (precision)
+- Architecture: Redis-based counters, rate limiter middleware
+- Race condition handling: Lua scripts or sorted sets
+- Multi-datacenter sync strategy
+- Response headers: X-Ratelimit-Remaining, X-Ratelimit-Limit, X-Ratelimit-Retry-After
+```
+
+**Example 2 — Chat System:**
+```
+User: "Design a chat application supporting group messaging"
+
+Apply: Ch 12 (chat system), Ch 1 (scaling), Ch 5 (consistent hashing)
+
+Generate:
+- Communication: WebSocket for real-time, HTTP for other features
+- Stateful chat servers with service discovery (Zookeeper)
+- Key-value store for messages (HBase-like)
+- Message sync with per-device cursor ID
+- Online presence: heartbeat mechanism, fanout to friends
+- Group chat: message copy per recipient for small groups
+```
+
+**Example 3 — Video Platform:**
+```
+User: "Design a video upload and streaming service"
+
+Apply: Ch 14 (YouTube), Ch 1 (CDN, scaling)
+
+Generate:
+- Upload: parallel chunk upload, resumable, pre-signed URLs
+- Transcoding: DAG-based pipeline (video splitting → encoding → merging)
+- Architecture: preprocessor → DAG scheduler → resource manager → task workers
+- Streaming: adaptive bitrate with HLS/DASH
+- Cost: popular content via CDN, long-tail from origin servers
+- Safety: DRM, AES encryption, watermarking
+```
+
+---
+
+## Mode 2: Design Review
+
+When reviewing system designs, read `references/review-checklist.md` for the full checklist.
+
+### Review Process
+
+1. **Scale scan** — Check Ch 1: Are scaling fundamentals applied (LB, cache, CDN, replication, sharding)?
+2. **Estimation scan** — Check Ch 2: Are capacity estimates done? Are they reasonable?
+3. **Framework scan** — Check Ch 3: Does the design follow the 4-step framework (scope → high-level → deep dive → wrap up)? The Ch 3 4-step framework explicitly requires establishing scope and estimating load *before* proposing architecture — skipping estimation leads to over-engineered or under-engineered designs.
+4. **Component scan** — Check Ch 4–15: Are relevant patterns used for specific components?
+5. **Failure scan** — Are failure modes addressed? Replication, retry, graceful degradation? Specifically praise when message queues are used as durable buffers (fanout service crashes can replay from the queue; message queue decouples producers from consumers and prevents data loss on failure).
+6. **Trade-off scan** — Are design decisions justified with explicit trade-offs?
+
+### Recognizing Good Designs
+
+When a design is well-structured, **say so explicitly** — do not manufacture fake issues just to have something to say. Specifically acknowledge:
+
+- **4-step framework adherence** (Ch 3): If the design clearly follows scope → estimation → high-level → deep dive → failure handling, explicitly recognize it as a well-structured design following the 4-step framework.
+- **Back-of-envelope estimation quality** (Ch 2): If the designer derives concrete QPS numbers and uses the read/write ratio to justify architectural choices (e.g., why Redis caching is needed, why read replicas are warranted), praise this explicitly — the ratio is what *justifies* the design decisions.
+- **Celebrity/hotspot handling** (Ch 11): Fanout-on-write for normal users + fanout-on-read for high-follower accounts is the canonical hybrid approach — praise it when present.
+- **Cursor-based pagination**: Praise over offset-based for feeds where new content is inserted continuously.
+- **Explicit consistency model**: When a designer explicitly chooses eventual consistency and documents why, praise the decision.
+- **Message queue as durable buffer** (Ch 1, 11): When failure handling uses a message queue so that service crashes can replay events and no data is lost, explicitly praise this as a correct reliability pattern.
+- **Optional improvements**: Frame any suggestions as enhancements, not criticisms, when the design is fundamentally sound.
+
+### Review Output Format
+
+Structure your review as:
+
+```
+## Summary
+One paragraph: overall design quality, main strengths, key concerns.
+
+## Strengths
+For each strength (list when design is good):
+- **Topic**: what was done well
+- **Why**: chapter reference and why it matters
+
+## Scaling Issues
+For each issue:
+- **Topic**: component and concept
+- **Problem**: what's wrong or missing
+- **Fix**: recommended change with chapter reference
+
+## Estimation Issues
+For each issue: same structure
+
+## Component Design Issues
+For each issue: same structure
+
+## Failure Handling Issues
+For each issue: same structure
+
+## Recommendations
+Priority-ordered from most critical to nice-to-have.
+Each recommendation references the specific chapter/concept.
+```
+
+### Common System Design Anti-Patterns to Flag
+
+- **No capacity estimation** → Ch 2: Always estimate QPS, storage, bandwidth before designing
+- **Single point of failure** → Ch 1: Add redundancy via replication, load balancing, failover
+- **No caching strategy** → Ch 1: Use cache-aside, read-through, or write-behind as appropriate
+- **Monolithic database** → Ch 1: Consider replication (read replicas) and sharding for scale
+- **Stateful web servers** → Ch 1: Move session data to shared storage for horizontal scaling
+- **Vanity scaling** → Ch 2 + Ch 3: Scaling decisions must be based on back-of-envelope estimation, not intuition or aspiration. The 4-step framework (Ch 3) requires establishing scope and estimating load *before* proposing architecture — skipping this step is what leads to over-engineered designs
+- **Wrong data store** → Ch 6, 12: Match storage to access patterns (relational, key-value, document)
+- **No rate limiting** → Ch 4: Protect APIs from abuse and cascading failures
+- **Synchronous everything** → Ch 1: Use message queues for decoupling and async processing
+- **No CDN for static content** → Ch 1: Serve static assets from CDN to reduce latency and server load
+- **Big-bang deployment** → Ch 14: Use parallel processing, chunked uploads, incremental approaches
+- **No conflict resolution** → Ch 6, 15: Handle concurrent writes with versioning or conflict detection
+- **Missing monitoring** → Ch 3: Always include logging, metrics, alerting in the design
+- **Ignoring network partition** → Ch 6: CAP theorem applies; choose CP or AP based on requirements
+
+---
+
+## General Guidelines
+
+- **The 4-step framework is universal** — Use it for every design problem, not just interviews
+- **Back-of-envelope estimation validates feasibility** — Always estimate before designing
+- **Every component has trade-offs** — Consistency vs. availability, latency vs. throughput, cost vs. reliability
+- **Start simple, then optimize** — Single server → vertical scaling → horizontal scaling → advanced optimizations
+- **Design for failure** — Assume every component will fail; plan recovery
+- **Cache is king for read-heavy systems** — But consider cache invalidation complexity
+- **Sharding enables horizontal data scaling** — But adds complexity (joins, rebalancing, hotspots)
+- For deeper design details, read `references/api_reference.md` before applying designs.
+- For review checklists, read `references/review-checklist.md` before reviewing designs.

package/skills/system-design-interview/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/skills/system-design-interview/evals/evals.json

@@ -0,0 +1,46 @@
+
+{
+  "evals": [
+    {
+      "id": "eval-01-naive-url-shortener",
+      "prompt": "I need to design a URL shortener service like bit.ly. Here's my design:\n\nThe system has a single server with a MySQL database. When a user submits a long URL, we generate a random 6-character short code, store the mapping in a `urls` table with columns (short_code, long_url, created_at), and return the short URL. When someone visits the short URL, we look up the long URL in the database and do a 302 redirect.\n\nFor the database:\n```sql\nCREATE TABLE urls (\n  short_code VARCHAR(6) PRIMARY KEY,\n  long_url    TEXT NOT NULL,\n  created_at  TIMESTAMP DEFAULT NOW()\n);\n```\n\nThe application is a simple Node.js Express server that handles both write (shorten) and read (redirect) traffic on the same process. I think this will work fine for our use case.",
+      "expectations": [
+        "Calls out the absence of any back-of-envelope estimation before designing (Ch 2 / Ch 3): we don't know the QPS, storage needs, or read/write ratio — the design can't be validated without these numbers",
+        "Identifies the single point of failure: one server, one database — any failure takes down the entire service",
+        "Flags missing caching (Ch 1): URL redirects are extremely read-heavy (estimated 100:1 read/write ratio in the book's example); a Redis cache in front of the DB would handle the vast majority of redirect lookups without hitting MySQL",
+        "Flags no CDN or load balancing (Ch 1): with a single Node.js process, the service cannot scale horizontally",
+        "Questions the random collision strategy: random 6-character codes will have increasing collision probability as the table grows — needs a collision-resistant ID generation strategy (base-62 encoding of auto-increment ID, or a dedicated ID generator per Ch 7/8)",
+        "Notes that 302 redirect means the browser does NOT cache the redirect — every click hits the server again; 301 is cacheable and reduces load for stable URLs (Ch 8 covers this trade-off explicitly)",
+        "Flags the absence of rate limiting on the URL creation endpoint — without it the service is open to spam and abuse (Ch. 4: rate limiter patterns protect APIs; a URL shortener creation endpoint is a prime abuse target)",
+        "Recommends at minimum: back-of-envelope estimate first, Redis cache for redirects, read replicas for the DB, load balancer, and a more robust ID generation approach"
+      ]
+    },
+    {
+      "id": "eval-02-premature-optimization-no-estimation",
+      "prompt": "I want to build a notification system (like push notifications for a mobile app). Before designing it, I've decided the system needs:\n\n1. A Kafka cluster with 50 partitions for notification events\n2. A Cassandra cluster with 6 nodes for storing notification history\n3. A Redis cluster in active-active mode across 3 data centers\n4. A Kubernetes cluster with auto-scaling pods for the notification workers\n5. A separate microservice for each notification channel (push, SMS, email, in-app)\n6. A GraphQL subscription API for real-time notification delivery\n7. Consistent hashing for distributing notifications across worker pods\n\nThe app currently has about 500 registered users and we send maybe 200 notifications per day.",
+      "expectations": [
+        "Calls out vanity scaling (Ch 2): 500 users sending 200 notifications per day is roughly 0.002 QPS — this is trivially handled by a single server with a simple database; none of the proposed infrastructure is justified",
+        "References the principle from Ch 2: scaling decisions must be based on back-of-envelope estimation, not intuition or aspiration",
+        "Calculates or estimates the actual load: 200 notifications/day = ~8/hour = ~0.002/second — a SQLite database on a $5 server would handle this with room to spare",
+        "Notes that the proposed stack adds enormous operational complexity: Kafka, Cassandra, Redis cluster, Kubernetes, and multiple microservices all require dedicated expertise to operate, monitor, and debug",
+        "Identifies this as the 'vanity scaling' anti-pattern explicitly called out in the SKILL.md review checklist",
+        "Recommends a design appropriate for the actual scale: a single service, a relational database (Postgres), an email/SMS provider SDK, and a simple job queue (like BullMQ or a DB-backed worker) — then scale when metrics demand it",
+        "Notes that the 4-step framework (Ch 3) requires establishing scope and estimating load BEFORE proposing architecture — skipping estimation leads to over-engineered designs like this one"
+      ]
+    },
+    {
+      "id": "eval-03-good-system-design-proposal",
+      "prompt": "Design proposal for a news feed system (like Twitter's home timeline):\n\n**Step 1 — Requirements & Estimation**\n- Functional: users follow others, posts appear in follower feeds, feeds are reverse-chronological\n- Non-functional: 500ms p99 feed load, eventual consistency acceptable, 10M DAU\n- Estimation: 10M DAU × 2 feed loads/day = 20M reads/day ≈ 230 QPS reads; 10M DAU × 0.1 posts/day = 1M writes/day ≈ 12 QPS writes; read/write ratio ≈ 20:1\n- Storage: 1M posts/day × 200 bytes = 200MB/day ≈ 70GB/year for post content\n\n**Step 2 — High-Level Design**\n- Write path: user posts → Post Service → publishes PostCreated event to message queue\n- Fanout service subscribes to PostCreated → for each follower, prepends post ID to their feed cache in Redis\n- Read path: Feed Service → reads from Redis feed cache (list of post IDs) → fetches post content from Post Cache\n- API: GET /v1/feed?userId=X&cursor=Y (cursor-based pagination)\n\n**Step 3 — Deep Dive: Fanout Strategy**\n- Fanout-on-write for regular users: pre-populate follower feeds in Redis on every post\n- Exception for celebrities (>10K followers): fanout-on-read — too expensive to write to millions of feed caches synchronously\n- Hybrid: celebrity posts fetched at read time and merged with pre-computed feed\n\n**Step 4 — Failure Handling**\n- Message queue provides durability for fanout — if fanout service crashes, it replays from queue\n- Redis feeds are a cache, not source of truth — Post DB is the durable store; stale feeds are acceptable (eventual consistency)\n- Rate limiting on POST /posts to prevent feed spam",
+      "expectations": [
+        "Recognizes this as a well-structured design following the 4-step framework and says so explicitly",
+        "Praises the back-of-envelope estimation: derives concrete QPS numbers (230 reads, 12 writes) and uses the read/write ratio to justify the design decisions",
+        "Praises the fanout-on-write vs fanout-on-read hybrid — this is exactly the celebrity problem discussed in Ch 11 of the book; the design correctly identifies and handles the hot-user case",
+        "Praises cursor-based pagination over offset-based — correct for infinite scroll feeds where new content is constantly inserted",
+        "Praises the explicit consistency model: choosing eventual consistency and documenting why (the 500ms SLA and user experience tolerance)",
+        "Praises the failure handling section: using the message queue as a durable buffer means fanout service failures don't lose posts",
+        "Does NOT manufacture fake issues just to have something to say",
+        "May offer optional improvements (cache warming on login, feed pre-generation for cold start, monitoring mentions) but clearly frames them as enhancements"
+      ]
+    }
+  ]
+}

package/skills/system-design-interview/evals/results.json

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