@booklib/core 2.0.0

package/skills/clean-code-reviewer/scripts/pre-review.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""
+pre-review.py — Pre-analysis script for Clean Code reviews.
+Usage: python pre-review.py <file>
+
+Produces a structured report covering file stats, long functions, deep nesting,
+argument count violations, and linter output — ready to feed an agent as context.
+"""
+
+import ast
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def detect_language(path: Path) -> str:
+    return {
+        ".py": "python",
+        ".js": "javascript",
+        ".ts": "typescript",
+        ".java": "java",
+        ".go": "go",
+        ".rb": "ruby",
+        ".rs": "rust",
+    }.get(path.suffix.lower(), "unknown")
+
+
+def count_lines(source: str) -> int:
+    return len(source.splitlines())
+
+
+def measure_nesting_depth(node: ast.AST, depth: int = 0) -> int:
+    nesting_nodes = (
+        ast.If, ast.For, ast.While, ast.With, ast.Try,
+        ast.ExceptHandler, ast.AsyncFor, ast.AsyncWith,
+    )
+    max_depth = depth
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, nesting_nodes):
+            max_depth = max(max_depth, measure_nesting_depth(child, depth + 1))
+        else:
+            max_depth = max(max_depth, measure_nesting_depth(child, depth))
+    return max_depth
+
+
+def analyze_python_ast(source: str):
+    """Return function/class stats using AST. Returns list of dicts."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as exc:
+        return None, f"AST parse failed: {exc}"
+
+    lines = source.splitlines()
+    results = []
+
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+
+        kind = "class" if isinstance(node, ast.ClassDef) else "function"
+        start = node.lineno
+        end = node.end_lineno if hasattr(node, "end_lineno") else start
+        length = end - start + 1
+
+        arg_count = 0
+        nesting = 0
+        if kind == "function":
+            args = node.args
+            arg_count = (
+                len(args.args)
+                + len(args.posonlyargs)
+                + len(args.kwonlyargs)
+                + (1 if args.vararg else 0)
+                + (1 if args.kwarg else 0)
+            )
+            # Don't count 'self' / 'cls'
+            first = args.posonlyargs[0].arg if args.posonlyargs else (args.args[0].arg if args.args else None)
+            if first in ("self", "cls"):
+                arg_count = max(0, arg_count - 1)
+            nesting = measure_nesting_depth(node)
+
+        results.append({
+            "kind": kind,
+            "name": node.name,
+            "start": start,
+            "end": end,
+            "length": length,
+            "arg_count": arg_count,
+            "nesting": nesting,
+        })
+
+    return results, None
+
+
+def run_ruff(filepath: Path):
+    """Run ruff on the file; return (output_lines, error_message)."""
+    try:
+        result = subprocess.run(
+            ["ruff", "check", "--output-format", "concise", str(filepath)],
+            capture_output=True, text=True, timeout=30,
+        )
+        output = (result.stdout + result.stderr).strip()
+        return output.splitlines() if output else [], None
+    except FileNotFoundError:
+        return [], "ruff not installed (pip install ruff)"
+    except subprocess.TimeoutExpired:
+        return [], "ruff timed out"
+
+
+def separator(char="-", width=70):
+    return char * width
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python pre-review.py <file>")
+        sys.exit(1)
+
+    filepath = Path(sys.argv[1])
+    if not filepath.exists():
+        print(f"Error: file not found: {filepath}")
+        sys.exit(1)
+
+    source = filepath.read_text(encoding="utf-8", errors="replace")
+    language = detect_language(filepath)
+    total_lines = count_lines(source)
+    file_size = filepath.stat().st_size
+
+    print(separator("="))
+    print(f"CLEAN CODE PRE-REVIEW REPORT")
+    print(separator("="))
+    print(f"File     : {filepath}")
+    print(f"Language : {language}")
+    print(f"Size     : {file_size:,} bytes  |  {total_lines} lines")
+    print()
+
+    # --- AST analysis (Python only) ---
+    if language == "python":
+        print(separator())
+        print("FUNCTION / CLASS ANALYSIS (AST)")
+        print(separator())
+        items, err = analyze_python_ast(source)
+        if err:
+            print(f"  Warning: {err}")
+        elif items:
+            long_fns = [i for i in items if i["kind"] == "function" and i["length"] > 20]
+            deep_fns = [i for i in items if i["kind"] == "function" and i["nesting"] >= 3]
+            many_args = [i for i in items if i["kind"] == "function" and i["arg_count"] > 3]
+
+            print(f"  Total functions : {sum(1 for i in items if i['kind'] == 'function')}")
+            print(f"  Total classes   : {sum(1 for i in items if i['kind'] == 'class')}")
+            print()
+
+            if long_fns:
+                print(f"  [!] LONG FUNCTIONS (>20 lines) — Clean Code: functions should do one thing")
+                for fn in long_fns:
+                    print(f"      {fn['name']}()  lines {fn['start']}-{fn['end']}  ({fn['length']} lines)")
+            else:
+                print("  [OK] No functions exceed 20 lines.")
+
+            print()
+            if deep_fns:
+                print(f"  [!] DEEP NESTING (>=3 levels) — consider early returns or extraction")
+                for fn in deep_fns:
+                    print(f"      {fn['name']}()  line {fn['start']}  (max nesting: {fn['nesting']})")
+            else:
+                print("  [OK] No functions have excessive nesting depth.")
+
+            print()
+            if many_args:
+                print(f"  [!] TOO MANY ARGUMENTS (>3) — Clean Code: prefer parameter objects")
+                for fn in many_args:
+                    print(f"      {fn['name']}()  line {fn['start']}  ({fn['arg_count']} args)")
+            else:
+                print("  [OK] All functions have 3 or fewer arguments.")
+        else:
+            print("  No functions or classes found.")
+        print()
+
+    # --- Linter output ---
+    print(separator())
+    if language == "python":
+        print("RUFF LINTER OUTPUT")
+        print(separator())
+        ruff_lines, ruff_err = run_ruff(filepath)
+        if ruff_err:
+            print(f"  Note: {ruff_err}")
+        elif ruff_lines:
+            for line in ruff_lines:
+                print(f"  {line}")
+        else:
+            print("  [OK] ruff found no issues.")
+    else:
+        print(f"LINTER")
+        print(separator())
+        print(f"  Automated linting not configured for '{language}'. Run language-specific tools manually.")
+
+    print()
+    print(separator("="))
+    print("END OF PRE-REVIEW REPORT")
+    print(separator("="))
+
+
+if __name__ == "__main__":
+    main()

package/skills/data-intensive-patterns/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: data-intensive-patterns
+version: "1.0"
+license: MIT
+tags: [architecture, databases, distributed-systems]
+description: >
+  Generate and review data-intensive application code using patterns from Martin Kleppmann's
+  "Designing Data-Intensive Applications." Use this skill whenever the user asks about data
+  storage engines, replication, partitioning, transactions, distributed systems, batch or stream
+  processing, encoding/serialization, consistency models, consensus, event sourcing, CQRS,
+  change data capture, or anything related to building reliable, scalable, and maintainable
+  data systems. Trigger on phrases like "data-intensive", "replication", "partitioning",
+  "sharding", "LSM-tree", "B-tree", "transaction isolation", "distributed consensus",
+  "stream processing", "batch processing", "event sourcing", "CQRS", "CDC",
+  "change data capture", "serialization format", "schema evolution", "consensus algorithm",
+  "leader election", "total order broadcast", or "data pipeline."
+---
+
+# Data-Intensive Patterns Skill
+
+You are an expert data systems architect grounded in the patterns and principles from
+Martin Kleppmann's *Designing Data-Intensive Applications*. You help developers in two modes:
+
+1. **Code Generation** — Produce well-structured code for data-intensive components
+2. **Code Review** — Analyze existing data system code and recommend improvements
+
+## How to Decide Which Mode
+
+- If the user asks you to *build*, *create*, *generate*, *implement*, or *scaffold* something → **Code Generation**
+- If the user asks you to *review*, *check*, *improve*, *audit*, or *critique* code → **Code Review**
+- If ambiguous, ask briefly which mode they'd prefer
+
+---
+
+## Mode 1: Code Generation
+
+When generating data-intensive application code, follow this decision flow:
+
+### Step 1 — Understand the Data Requirements
+
+Ask (or infer from context) what the system's data characteristics are:
+
+- **Read/write ratio** — Is it read-heavy (analytics, caching) or write-heavy (logging, IoT)?
+- **Consistency requirements** — Does it need strong consistency or is eventual consistency acceptable?
+- **Scale expectations** — Single node sufficient, or does it need horizontal scaling?
+- **Latency requirements** — Real-time (milliseconds), near-real-time (seconds), or batch (minutes/hours)?
+- **Data model** — Relational, document, graph, time-series, or event log?
+
+### Step 2 — Select the Right Patterns
+
+Read `references/patterns-catalog.md` for full pattern details. Quick decision guide:
+
+| Problem | Pattern to Apply |
+|---------|-----------------|
+| How to model data? | Relational, Document, or Graph model (Chapter 2) |
+| How to store data on disk? | LSM-Tree (write-optimized) or B-Tree (read-optimized) (Chapter 3) |
+| How to encode data for storage/network? | Avro, Protobuf, Thrift with schema registry (Chapter 4) |
+| How to replicate for high availability? | Single-leader, Multi-leader, or Leaderless replication (Chapter 5) |
+| How to scale beyond one node? | Partitioning by key range or hash (Chapter 6) |
+| How to handle concurrent writes? | Transaction isolation level selection (Chapter 7) |
+| How to handle partial failures? | Timeouts, retries with idempotency, fencing tokens (Chapter 8) |
+| How to achieve consensus? | Raft/Paxos via ZooKeeper/etcd, or total order broadcast (Chapter 9) |
+| How to process large datasets? | MapReduce or dataflow engines (Spark, Flink) (Chapter 10) |
+| How to process real-time events? | Stream processing with Kafka + Flink/Spark Streaming (Chapter 11) |
+| How to keep derived data in sync? | CDC, event sourcing, or transactional outbox (Chapters 11-12) |
+| How to query across data sources? | CQRS with denormalized read models (Chapters 11-12) |
+
+### Step 3 — Generate the Code
+
+Follow these principles when writing code:
+
+<core_principles>
+- **Choose the right storage engine** — LSM-trees (LevelDB, RocksDB, Cassandra) for write-heavy workloads; B-trees (PostgreSQL, MySQL InnoDB) for read-heavy workloads with point lookups
+- **Schema evolution from day one** — Use encoding formats that support forward and backward compatibility (Avro with schema registry, Protobuf with field tags)
+- **Replication topology matches the use case** — Single-leader for strong consistency needs; multi-leader for multi-datacenter writes; leaderless for high availability with tunable consistency
+- **Partition for scale, not prematurely** — Key-range partitioning for range scans; hash partitioning for uniform distribution; compound keys for related-data locality
+- **Pick the weakest isolation level that's correct** — Read Committed for most cases; Snapshot Isolation for read-heavy analytics; Serializable only when write skew is a real risk
+- **Idempotent operations everywhere** — Every retry, every message consumer, every saga step must be safe to re-execute
+- **Derive, don't share** — Derived data (caches, search indexes, materialized views) should be rebuilt from the log of record, not maintained by shared writes
+- **End-to-end correctness** — Don't rely on a single component for exactly-once; use idempotency keys and deduplication at application boundaries
+</core_principles>
+
+When generating code, produce:
+
+1. **Data model definition** (schema, encoding format, evolution strategy)
+2. **Storage layer** (engine choice, indexing strategy, partitioning scheme)
+3. **Replication configuration** (topology, consistency guarantees, failover)
+4. **Processing pipeline** (batch or stream, with fault tolerance approach)
+5. **Integration layer** (CDC, event publishing, derived view maintenance)
+
+Use the user's preferred language/framework. If unspecified, adapt to the most natural fit:
+Java/Scala for Kafka/Spark/Flink pipelines, Python for data processing scripts, Go for
+infrastructure components, SQL for schema definitions.
+
+### Code Generation Examples
+
+<examples>
+<example id="1" title="Event-Sourced Order System with CDC">
+```
+User: "Build an order tracking system that keeps a search index and analytics dashboard in sync"
+
+You should generate:
+- Order aggregate with event log (OrderPlaced, OrderShipped, OrderDelivered, OrderCancelled)
+- Event store schema with append-only writes
+- CDC connector configuration (Debezium) to capture changes
+- Kafka topic setup with partitioning by order ID
+- Stream processor that maintains:
+  - Elasticsearch index for order search (denormalized view)
+  - Analytics materialized view for dashboard queries
+- Idempotent consumers with deduplication by event ID
+- Schema registry configuration for event evolution
+```
+</example>
+
+<example id="2" title="Partitioned Time-Series Ingestion">
+```
+User: "I need to ingest millions of sensor readings per second with range queries by time"
+
+You should generate:
+- LSM-tree based storage (e.g., Cassandra or TimescaleDB schema)
+- Partitioning strategy: compound key (sensor_id, time_bucket)
+- Write path: batch writes with write-ahead log
+- Read path: range scan by time window within a partition
+- Replication: factor of 3 with tunable consistency (ONE for writes, QUORUM for reads)
+- Compaction strategy: time-window compaction for efficient cleanup
+- Retention policy configuration
+```
+</example>
+
+<example id="3" title="Distributed Transaction with Saga">
+```
+User: "Coordinate a payment and inventory reservation across two services"
+
+You should generate:
+- Saga orchestrator with steps and compensating actions
+- Transactional outbox pattern for reliable event publishing
+- Idempotency keys for each saga step
+- Timeout and retry configuration with exponential backoff
+- Dead letter queue for failed messages
+- Monitoring: saga state machine with observable transitions
+```
+</example>
+</examples>
+
+---
+
+## Mode 2: Code Review
+
+When reviewing data-intensive application code, read `references/review-checklist.md` for
+the full checklist. Apply these categories systematically:
+
+### Review Process
+
+1. **Identify the data model** — relational, document, graph, event log? Does the model fit the access patterns?
+2. **Check storage choices** — is the storage engine appropriate for the workload (read-heavy vs write-heavy)?
+3. **Check encoding** — are serialization formats evolvable? Forward/backward compatibility maintained?
+4. **Check replication** — is the replication topology appropriate? Are failover and lag handled?
+5. **Check partitioning** — are hot spots avoided? Is the partition key well-chosen?
+6. **Check transactions** — is the isolation level appropriate? Are write skew and phantoms addressed?
+7. **Check distributed systems concerns** — timeouts, retries, idempotency, fencing tokens present?
+8. **Check processing pipelines** — are batch/stream jobs fault-tolerant? Exactly-once or at-least-once with idempotency?
+9. **Check derived data** — are caches/indexes/views maintained via events? Is consistency model acceptable?
+10. **Check operational readiness** — monitoring, alerting, backpressure handling, graceful degradation?
+
+### Review Output Format
+
+Structure your review as:
+
+```
+## Summary
+One paragraph: what the system does, which patterns it uses, overall assessment.
+
+## Strengths
+What the code does well, which patterns are correctly applied. Be specific and generous:
+name each well-applied pattern explicitly (e.g., "the `from_events` classmethod correctly
+implements event sourcing — the event log is the source of truth"; "CQRS is correctly
+applied: the Order aggregate is the write model, SearchIndexProjection is the read model";
+"optimistic concurrency control via expected_version prevents lost updates").
+
+## Issues Found
+For each genuine issue:
+- **What**: describe the problem
+- **Why it matters**: explain the reliability/scalability/maintainability risk
+- **Pattern to apply**: which data-intensive pattern addresses this
+- **Suggested fix**: concrete code change or restructuring
+
+Only include genuine anti-patterns actually present in the code. Do NOT manufacture issues.
+
+## Recommendations (optional)
+For well-designed code, any suggestions are optional future considerations, not required
+fixes. Frame them explicitly: "Future consideration (not a current issue): …". For example,
+snapshotting for long-lived event streams is a performance optimization for the future, not
+a current violation of any pattern.
+```
+
+### Reviewing Well-Designed Code
+
+When you encounter well-designed code that correctly applies data-intensive patterns,
+**your primary job is to recognize and praise the good design**, not to find problems.
+
+Key patterns to recognize and praise explicitly when present:
+
+<strengths_to_praise>
+- **Event sourcing with `from_events`** — aggregate state rebuilt from the event log means the log is the source of truth (Ch 11)
+- **Optimistic concurrency via `expected_version`** — prevents lost updates without pessimistic locking (Ch 7)
+- **Immutable event objects** — frozen dataclasses/records for events enforce append-only semantics (Ch 11)
+- **Idempotent consumers with deduplication by event ID** — makes projections safe to replay (Ch 11)
+- **CQRS — write model (aggregate) separate from read model (projection)** — enables independent scaling (Ch 11)
+- **Transactional outbox** — atomically writes event and publishes it (Ch 11)
+- **Snapshotting** — when suggested, frame it as a future optimization for performance, not a current deficiency
+</strengths_to_praise>
+
+For well-designed systems: if you have no genuine concerns, state that clearly. Any
+suggestions for well-designed code must go in the **Recommendations** section and must be
+framed as optional future optimizations — never as "Issues Found", never described as
+"worth addressing before production."
+
+**Specific false positives to reject when the code correctly uses event sourcing with idempotent consumers:**
+
+<false_positives>
+- **Schema evolution** — In-process Python/Java dataclasses with no Avro/Protobuf/JSON
+  serialization layer do NOT need a schema registry. Absence of a serialization format is
+  NOT a defect. Only flag schema evolution when there is an explicit encoding format present.
+- **Atomicity gap** — If projections implement `_already_processed(event_id)` or similar
+  deduplication, the atomicity gap is handled. This is the correct pattern; do NOT flag it
+  as a production-blocking issue.
+- **Snapshotting** — Always a future performance optimization, never a current deficiency.
+</false_positives>
+
+### Common Anti-Patterns to Flag
+
+<anti_patterns>
+- **Wrong storage engine for the workload** — Using B-tree for append-heavy logging; using LSM-tree where point reads dominate
+- **Missing schema evolution strategy** — Encoding formats (Avro/Protobuf/JSON) without backward/forward compatibility; only applicable when there is an explicit serialization layer
+- **Inappropriate isolation level for check-then-act patterns** — Using READ COMMITTED or Snapshot Isolation (REPEATABLE READ) for check-then-act patterns (read a value, decide to write based on it) allows write skew: two concurrent transactions both pass the check and both write, violating the invariant; READ COMMITTED is insufficient because it only prevents dirty reads, not this race; Snapshot Isolation is also insufficient because both transactions read the same pre-write snapshot; only SERIALIZABLE isolation or SELECT FOR UPDATE (which materializes the conflict as a row lock) prevents write skew (Ch 7: write skew, phantoms, serializable snapshot isolation)
+- **Shared mutable state across services** — Multiple services writing to the same database table
+- **Synchronous replication where async suffices** — Unnecessary latency from waiting for all replicas
+- **Hot partition** — All writes landing on the same partition (e.g., monotonically increasing key with hash partitioning, or celebrity user in social feed)
+- **No idempotency on retries** — Retry logic without deduplication keys, causing duplicate side effects
+- **Distributed transactions via 2PC** — Two-phase commit across heterogeneous systems (fragile, blocks on coordinator failure)
+- **Missing backpressure** — Producer overwhelms consumer with no flow control
+- **Derived data maintained by dual writes** — Updating both primary store and derived view in application code instead of via CDC/events
+- **Clock-dependent ordering** — Using wall-clock timestamps for event ordering across nodes instead of logical clocks or sequence numbers
+- **Synchronous chain without idempotency** — Chained service calls where any downstream failure leaves the system inconsistent; non-idempotent endpoints get called multiple times on retry, causing duplicate side effects (e.g., double reservation, double charge); the recommended fix is to replace the full chain with event-driven processing: publish a domain event (`OrderPlaced`, `PaymentInitiated`) and have each downstream service consume it asynchronously — this is not the same as wrapping the chain in a saga, which is still synchronous orchestration
+- **Non-transactional services in synchronous chain** — Side-effect-only services (notifications, emails, analytics) should never be in a synchronous chain; their failure must not roll back business-critical operations
+- **No event log in stateful services** — Services that mutate state without an append-only event log have no replayable source of truth; flag this as a concrete reliability issue, not a vague "future consideration" — crash recovery, audit trails, and derived view rebuilding all require a durable event log or WAL (Ch 11)
+- **Event-driven transition without transactional outbox** — When recommending replacement of a synchronous chain with event-driven processing, always specify the transactional outbox pattern: write the domain state change and the outbox event in the same local database transaction, then have a separate relay process publish events to the message broker; this is the only way to guarantee events are not lost on crash between the write and the publish (Ch 11)
+- **DELETE/cancel without idempotency tracking** — While a bare SQL DELETE is accidentally idempotent (deleting a non-existent row is a no-op), cancel operations in distributed contexts (sagas, at-least-once message delivery, API retries) need idempotency keys or logged outcomes to ensure exactly-once semantics; flag cancel handlers that lack deduplication
+- **OLTP and analytics sharing the same tables** — Analytics queries (aggregations, range scans, multi-table JOINs) running against the same tables as transactional workloads cause lock contention and slow both; separate the OLTP write path from the OLAP read path via CDC, batch export, or a dedicated analytics store (Ch 10: OLTP vs OLAP separation)
+</anti_patterns>
+
+---
+
+## General Guidelines
+
+<guidelines>
+- Be practical, not dogmatic. A single-node PostgreSQL database handles most workloads.
+  Recommend distributed patterns only when the problem actually demands them.
+- The three pillars are **reliability** (fault-tolerant), **scalability** (handles growth),
+  and **maintainability** (easy to evolve). Every recommendation should advance at least one.
+- Distributed systems add complexity. If the system can run on a single node, say so.
+  Kleppmann himself emphasizes understanding trade-offs before reaching for distribution.
+- When the user's data fits in memory on one machine, a simple in-process data structure
+  often beats a distributed system.
+- For deeper pattern details, read `references/patterns-catalog.md` before generating code.
+- For review checklists, read `references/review-checklist.md` before reviewing code.
+</guidelines>

package/skills/data-intensive-patterns/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/skills/data-intensive-patterns/evals/evals.json

@@ -0,0 +1,54 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-synchronous-rest-no-event-log",
+      "prompt": "Review this microservices architecture description and pseudo-code:\n\n```\nSystem: E-commerce order processing\nServices: OrderService, InventoryService, PaymentService, NotificationService\n\nFlow (all synchronous REST over HTTP):\n\n# OrderService.place_order()\nPOST /orders  →  validates cart\n               →  GET /inventory/{sku}  (blocks on InventoryService response)\n               →  POST /inventory/reserve  (blocks, decrements stock)\n               →  POST /payments/charge  (blocks on PaymentService)\n               →  POST /notifications/send  (blocks on NotificationService)\n               →  INSERT orders (status='CONFIRMED') into orders_db\n               →  return 201\n\n# If PaymentService times out:\n#   - inventory already reserved, order not yet written\n#   - caller gets 504, retries POST /orders\n#   - inventory reserved again (double reservation)\n\n# InventoryService\nGET /inventory/{sku}  →  SELECT stock FROM inventory WHERE sku=?\nPOST /inventory/reserve  →  UPDATE inventory SET stock=stock-qty WHERE sku=?\n\n# Shared database: orders_db is directly accessed by both OrderService\n# and InventoryService for reporting queries\n```",
+      "expectations": [
+        "Flags the fully synchronous REST chain as a distributed systems anti-pattern: a failure or timeout in any downstream service leaves the system in an inconsistent state (Ch 8: partial failures, timeouts, retries)",
+        "Identifies the double-reservation bug as a direct consequence of no idempotency on POST /inventory/reserve; recommends idempotency keys on all mutating endpoints (Ch 8: idempotent operations everywhere)",
+        "Flags the absence of an event log or write-ahead log: there is no source of truth to replay from if a service crashes mid-flow (Ch 11: event sourcing, log as source of truth)",
+        "Flags shared database access between OrderService and InventoryService as shared mutable state across services, violating service autonomy (Ch 12: shared mutable state across services anti-pattern)",
+        "Recommends replacing the synchronous chain with an event-driven approach: publish an OrderPlaced event, have downstream services react asynchronously (Ch 11: stream processing, event-driven)",
+        "Recommends the transactional outbox pattern to atomically write the order and publish the event in one local transaction (Ch 11: CDC, transactional outbox)",
+        "Notes that NotificationService is particularly ill-suited for the synchronous chain since a notification failure should not roll back a payment"
+      ]
+    },
+    {
+      "id": "eval-02-schema-without-access-patterns",
+      "prompt": "Review this database schema design:\n\n```sql\n-- Proposed schema for a social media analytics platform\n-- Requirements: show user activity feeds, compute engagement scores,\n-- support time-range queries on posts, and generate daily digest emails\n\nCREATE TABLE users (\n    id          BIGINT PRIMARY KEY,\n    username    VARCHAR(50),\n    email       VARCHAR(255),\n    created_at  TIMESTAMP\n);\n\nCREATE TABLE posts (\n    id          BIGINT PRIMARY KEY,\n    user_id     BIGINT REFERENCES users(id),\n    content     TEXT,\n    created_at  TIMESTAMP\n);\n\nCREATE TABLE events (\n    id          BIGINT PRIMARY KEY,\n    post_id     BIGINT REFERENCES posts(id),\n    user_id     BIGINT REFERENCES users(id),\n    event_type  VARCHAR(20),  -- 'like', 'comment', 'share', 'view'\n    occurred_at TIMESTAMP\n);\n\n-- All analytics queries will be run against these three tables via JOINs\n-- Indexes: only the primary keys above\n```",
+      "expectations": [
+        "Flags the absence of secondary indexes for the primary access patterns: time-range queries on posts (created_at) and per-user activity (user_id + created_at) will require full table scans (Ch 3: indexing strategies, B-tree vs LSM-tree, DDIA Chapter 3)",
+        "Identifies the schema is designed around normalization, not around read patterns; for analytics (read-heavy) workloads, this forces expensive multi-table JOINs on every query (Ch 2: document model vs relational model, denormalization for read-heavy workloads)",
+        "Flags that the `events` table mixing four different event types in one table with no partitioning will become a hot write target and a slow scan table as it grows (Ch 6: partitioning to spread load)",
+        "Notes there is no derived/materialized view for engagement scores, meaning every score computation re-scans all events; recommends pre-computed aggregates or a materialized view updated via CDC (Ch 11: derived data, CQRS)",
+        "Flags that the schema has no time-based partitioning on the `events` table despite time-range queries being a stated requirement (Ch 6: partitioning by key range for range scan efficiency)",
+        "Recommends separating the OLTP write path from the OLAP analytics read path, using CDC or batch export to feed an analytics store (Ch 10: batch processing, OLTP vs OLAP separation)"
+      ]
+    },
+    {
+      "id": "eval-04-write-skew-transaction-isolation",
+      "prompt": "Review this room booking service:\n\n```python\nclass RoomBookingService:\n    def book_room(\n        self,\n        room_id: int,\n        user_id: int,\n        start_date: date,\n        end_date: date,\n    ) -> bool:\n        with self.db.transaction():  # READ COMMITTED isolation (default)\n            # Check availability\n            count = self.db.query(\n                \"SELECT COUNT(*) FROM bookings \"\n                \"WHERE room_id = %s AND start_date < %s AND end_date > %s\",\n                (room_id, end_date, start_date)\n            ).fetchone()[0]\n\n            if count > 0:\n                return False  # already booked\n\n            # Reserve the room\n            self.db.execute(\n                \"INSERT INTO bookings (room_id, user_id, start_date, end_date) \"\n                \"VALUES (%s, %s, %s, %s)\",\n                (room_id, user_id, start_date, end_date)\n            )\n            return True\n\n    def cancel_booking(self, booking_id: int, user_id: int) -> None:\n        self.db.execute(\n            \"DELETE FROM bookings WHERE id = %s AND user_id = %s\",\n            (booking_id, user_id)\n        )\n```",
+      "expectations": [
+        "Identifies the write skew bug: two concurrent transactions both read count=0 under READ COMMITTED, both pass the check, and both insert — resulting in a double booking for the same room and dates (Ch 7: write skew, check-then-act pattern)",
+        "Explains that READ COMMITTED prevents dirty reads but does NOT prevent write skew — each transaction sees a consistent snapshot at statement time, but the check-and-insert is not atomic (Ch 7: isolation levels)",
+        "Recommends a concrete fix: either upgrade to SERIALIZABLE isolation, or use SELECT FOR UPDATE on the availability check to acquire a pessimistic lock (Ch 7: preventing write skew, materializing conflicts)",
+        "Notes that Snapshot Isolation (REPEATABLE READ) also does NOT prevent this write skew pattern — both transactions still read the pre-insert snapshot (Ch 7: snapshot isolation limitations)",
+        "Flags that cancel_booking has no idempotency protection — retrying a DELETE is safe by coincidence, but a retry after partial failure in a larger saga could cause correctness issues; recommends idempotency keys or at-minimum logging the delete outcome (Ch 8: idempotent operations)"
+      ]
+    },
+    {
+      "id": "eval-03-well-designed-event-sourced-system",
+      "prompt": "Review this event-sourced order system design:\n\n```python\n# Event definitions\n@dataclass(frozen=True)\nclass OrderPlaced:\n    order_id: str\n    customer_id: str\n    items: tuple  # immutable list of (sku, qty, price)\n    occurred_at: datetime\n    event_id: str = field(default_factory=lambda: str(uuid4()))\n\n@dataclass(frozen=True)\nclass OrderShipped:\n    order_id: str\n    tracking_number: str\n    occurred_at: datetime\n    event_id: str = field(default_factory=lambda: str(uuid4()))\n\n@dataclass(frozen=True)\nclass OrderCancelled:\n    order_id: str\n    reason: str\n    occurred_at: datetime\n    event_id: str = field(default_factory=lambda: str(uuid4()))\n\n# Append-only event store\nclass EventStore:\n    def append(self, stream_id: str, events: list, expected_version: int) -> None:\n        \"\"\"Append events with optimistic concurrency check.\"\"\"\n        ...\n\n    def load(self, stream_id: str) -> list:\n        \"\"\"Load all events for a stream in order.\"\"\"\n        ...\n\n# Aggregate rebuilt from events\nclass Order:\n    def __init__(self):\n        self.status = None\n        self.items = []\n        self._version = 0\n\n    @classmethod\n    def from_events(cls, events: list) -> 'Order':\n        order = cls()\n        for event in events:\n            order._apply(event)\n        return order\n\n    def _apply(self, event):\n        match event:\n            case OrderPlaced(items=items):\n                self.status = 'placed'\n                self.items = list(items)\n            case OrderShipped():\n                self.status = 'shipped'\n            case OrderCancelled():\n                self.status = 'cancelled'\n        self._version += 1\n\n# Idempotent consumer for search index projection\nclass SearchIndexProjection:\n    def handle(self, event, event_id: str) -> None:\n        if self._already_processed(event_id):\n            return\n        # update search index\n        self._mark_processed(event_id)\n```",
+      "expectations": [
+        "Recognizes this is a well-designed event-sourced system and says so explicitly",
+        "Praises the append-only event store with optimistic concurrency control via `expected_version` preventing lost updates (Ch 7: transaction isolation, write conflicts)",
+        "Praises rebuilding aggregate state from events via `from_events` — the event log is the source of truth (Ch 11: event sourcing, log-centric architecture)",
+        "Praises frozen dataclasses for events ensuring immutability, which is correct for an append-only log (Ch 11: immutable events)",
+        "Praises the idempotent consumer with deduplication by `event_id` in `SearchIndexProjection` making the projection safe to replay (Ch 11: idempotent consumers, exactly-once semantics)",
+        "Praises the separation of the write model (Order aggregate) from the read model (SearchIndexProjection) as CQRS (Ch 11: CQRS, derived data)",
+        "Does NOT manufacture issues to appear thorough; any suggestions are explicitly framed as minor optional improvements",
+        "May suggest snapshotting for long-lived streams as a performance optimization, but frames it as a future concern, not a current violation"
+      ]
+    }
+  ]
+}

package/skills/data-intensive-patterns/evals/results.json

@@ -0,0 +1,13 @@
+{
+  "pass_rate": 1,
+  "passed": 26,
+  "total": 26,
+  "baseline_pass_rate": 0.769,
+  "baseline_passed": 20,
+  "baseline_total": 26,
+  "delta": 0.231,
+  "model": "default",
+  "evals_run": 4,
+  "date": "2026-03-29",
+  "non_standard_provider": true
+}

package/skills/data-intensive-patterns/examples/after.md

@@ -0,0 +1,61 @@
+# After
+
+An event-driven architecture where writes go through a message log, read models are derived via CDC, read replicas serve analytics, and the command/query paths are separated.
+
+```
+ARCHITECTURE: E-Commerce Platform (Event-Driven + CQRS)
+
+WRITE PATH
+──────────
+[Mobile App / Web Browser]
+        │ REST (commands only: place order, update product)
+        v
+[API Gateway]  ──>  [Order Command Service]  ──>  [Orders DB - Postgres]
+                                                          │
+                                        [Debezium CDC connector]
+                                                          │
+                                                          v
+                                              [Kafka: order.events topic]
+                                              (append-only event log,
+                                               partitioned by order_id)
+
+READ PATH (derived models — rebuilt from event log, no dual-writes)
+──────────────────────────────────────────────────────────────────
+[Kafka: order.events]
+        │
+        ├──> [Inventory Consumer]  ──>  [Inventory Read DB - Postgres replica]
+        │                               (product weekly sales view)
+        │
+        ├──> [Search Consumer]     ──>  [Elasticsearch Index]
+        │                               (product search, updated async)
+        │
+        └──> [Analytics Consumer]  ──>  [BigQuery Streaming Insert]
+                                        (append-only fact table,
+                                         no load on production DB)
+
+QUERY ENDPOINTS (served from read models, not production write DB)
+──────────────────────────────────────────────────────────────────
+GET /inventory/reorder-candidates  → Inventory Read DB
+GET /search/products?q=...         → Elasticsearch
+GET /reports/revenue?period=...    → BigQuery
+
+ASYNC COORDINATION (replaces synchronous call chain)
+────────────────────────────────────────────────────
+Place order  → write Orders DB → CDC → Kafka
+             → Payment Service consumes event → publishes PaymentAuthorized
+             → Notification Service consumes PaymentAuthorized → sends email
+             (no synchronous chain; each step is independently retried)
+
+CONSISTENCY MODEL
+─────────────────
+Orders DB       → strongly consistent (single Postgres primary)
+Read models     → eventually consistent (seconds of lag, acceptable for reads)
+Analytics       → eventually consistent (minutes of lag, acceptable for reports)
+```
+
+Key improvements:
+- Append-only event log (Kafka) is the single source of truth — derived views are rebuilt from it, never maintained by dual-writes (Ch 11: derived data vs. system of record)
+- CDC via Debezium captures changes from the Orders DB atomically — no risk of writing to DB and failing to publish the event (Ch 11: Change Data Capture)
+- Analytics consumers write to BigQuery directly from Kafka — no SELECT queries on the production Orders DB (Ch 10: separation of OLTP and OLAP)
+- CQRS separates command endpoints (write path) from query endpoints (read path) — each can scale independently
+- The synchronous call chain (place order → payment → notification) is replaced by event-driven coordination — failure of one consumer does not block the order write

package/skills/data-intensive-patterns/examples/before.md

@@ -0,0 +1,38 @@
+# Before
+
+A text architecture diagram showing an e-commerce platform where every component communicates synchronously via REST with no event log, no read replicas, and no separation of read/write paths.
+
+```
+ARCHITECTURE: E-Commerce Platform (Synchronous REST Only)
+
+[Mobile App] ──REST──> [API Server]
+[Web Browser] ──REST──> [API Server]
+                              │
+              ┌───────────────┼──────────────────┐
+              │               │                  │
+              v               v                  v
+        [Order DB]     [Product DB]       [User DB]
+         (Postgres)     (Postgres)        (Postgres)
+              │               │
+              v               v
+     [Analytics REST]  [Search REST]    (both query
+      calls Order DB    calls Product    production
+      directly via      DB directly      DBs live)
+      SQL over HTTP
+
+FLOWS:
+  Place order   → API → write Order DB → REST call to
+                  Inventory Service → REST call to
+                  Payment Service → REST call to
+                  Notification Service
+                  (all synchronous, chain fails if any step fails)
+
+  Dashboard     → API → query Order DB, Product DB, User DB
+                  in sequence (3 serial DB queries on write path)
+
+  Search        → API → query Product DB directly
+                  (full table scans, no index service)
+
+  Reports       → Analytics service polls Order DB every 5 min
+                  via REST (puts load on production DB)
+```