@booklib/skills 1.2.0 → 1.3.0

package/lean-startup/examples/after.md

@@ -0,0 +1,80 @@
+# After
+
+An MVP experiment document that identifies the riskiest assumption, defines the smallest test, specifies actionable metrics, and sets explicit pivot/persevere criteria before any code is written.
+
+```markdown
+## MVP Experiment: AI Expense Management — Concierge Test
+
+### The Big Idea
+SMB finance managers spend 3+ hours per week manually reconciling receipts.
+We believe they will pay for a tool that eliminates that work — but we have
+not yet validated that they will change their workflow to use it.
+
+### Leap-of-Faith Assumptions to Test
+
+**Value hypothesis (riskiest):**
+> "Finance managers at 10–50 person companies will submit receipts through
+> a new tool at least 3× per week if the categorisation is accurate."
+
+**Growth hypothesis (secondary):**
+> "Satisfied users will refer at least one colleague within 30 days."
+
+### Why NOT build the full product yet
+Building OCR + AI categorisation + ERP integrations takes 6 months and $400K.
+If users don't form the habit of submitting receipts, none of those features
+matter. We must validate the value hypothesis first.
+
+### MVP Design: Concierge (Manual Behind the Scenes)
+
+**What users experience:**
+- Sign up form → they receive a dedicated WhatsApp number
+- They photograph receipts and send to WhatsApp
+- We manually categorise and respond with a structured summary within 2 hours
+- Weekly: we email a formatted expense report (manually compiled in Google Sheets)
+
+**What we actually build:**
+- Landing page with sign-up form (1 day)
+- WhatsApp Business number (1 hour)
+- Google Sheets report template (2 hours)
+- Total build time: ~2 days
+
+**Participants:** 15 finance managers recruited from our network
+
+**Duration:** 6 weeks
+
+### Innovation Accounting — Metrics
+
+| Metric | Baseline | Target (persevere) | Source |
+|--------|----------|--------------------|--------|
+| Weekly receipt submission rate | 0 | ≥ 3 receipts/user/week by week 4 | WhatsApp logs |
+| Categorisation acceptance rate | — | ≥ 85% accepted without correction | User replies |
+| User retention (still active week 6) | — | ≥ 70% of participants | WhatsApp logs |
+| Referral rate | 0 | ≥ 1 referral per 5 users | Sign-up source field |
+| Willingness to pay | 0 | ≥ 60% say "yes" at $29/mo | End-of-pilot survey |
+
+**Vanity metrics we will NOT track:** total sign-ups, page views, social shares.
+
+### Pivot/Persevere Decision — Week 6 Review
+
+**Persevere** (move to automated MVP) if ALL of:
+- Submission rate ≥ 3/week by week 4
+- Retention ≥ 70% at week 6
+- Willingness to pay ≥ 60%
+
+**Pivot** (reconsider problem or segment) if ANY of:
+- Submission rate < 1/week by week 3 (habit not forming)
+- Retention < 40% at week 4 (users not finding value)
+
+**Pivot options to consider:**
+- Zoom-in: focus only on one vertical (e.g., restaurant industry) where receipt volume is higher
+- Customer segment: target bookkeepers who file for multiple clients, not the SMB themselves
+- Problem: pivot to approval workflows if users engage more with that step than receipt capture
+```
+
+Key improvements:
+- Leap-of-faith assumptions are named explicitly before any engineering begins — value hypothesis and growth hypothesis are the riskiest bets, not product features (Ch 5: Leap-of-faith assumptions)
+- Concierge MVP — two days of manual work — tests the core habit loop without six months of engineering (Ch 6: MVP is for learning, not launching)
+- Innovation accounting table defines baseline, target, and data source for each metric before the experiment runs (Ch 7: Innovation accounting)
+- All metrics are cohort-based and behavioural ("submission rate", "retention") — vanity metrics like total sign-ups are explicitly excluded (Ch 7: Actionable vs. vanity metrics)
+- Explicit pivot/persevere decision criteria with a named decision date eliminate gut-feel delays (Ch 8: Pivot or persevere)
+- Pivot catalog is pre-populated — the team has thought through options in advance rather than scrambling at the decision point (Ch 8: Pivot types)

package/lean-startup/examples/before.md

@@ -0,0 +1,34 @@
+# Before
+
+A product specification for a 6-month build with no validated learning step, no hypothesis to test, and no criteria for deciding whether to continue.
+
+```markdown
+## Product Spec: AI-Powered Expense Management Platform
+
+### Overview
+We will build a comprehensive AI-powered expense management platform for SMBs.
+The platform will replace manual receipt tracking with automatic categorization,
+OCR scanning, policy enforcement, and CFO-level reporting.
+
+### Features (all required for launch)
+- Mobile app (iOS + Android) with camera OCR for receipt scanning
+- AI categorization engine trained on 50k expense categories
+- Multi-currency support with live FX rates
+- Approval workflow engine with configurable multi-level sign-off
+- Integration with QuickBooks, Xero, NetSuite, SAP
+- Admin dashboard with 25 pre-built CFO reports
+- SSO/SAML integration
+- Audit log and compliance export (SOC 2 ready)
+
+### Timeline
+- Month 1-2: Backend API + database schema
+- Month 3-4: Mobile app development
+- Month 5: Integrations + admin dashboard
+- Month 6: QA, security review, launch
+
+### Success metric
+5,000 paying customers within 3 months of launch.
+
+### Next step
+Kick off engineering sprint planning on Monday.
+```

package/lean-startup/scripts/new_experiment.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""
+Lean Startup — MVP Experiment Document Generator.
+
+Usage (interactive):  python new_experiment.py
+Usage (one-shot):     python new_experiment.py --name "X" --hypothesis "Y" \
+                        --mvp-type landing-page --metric "signups" \
+                        --threshold "100 signups" --duration "2 weeks" \
+                        --output experiment.md
+"""
+
+import argparse
+import sys
+from datetime import date, timedelta
+from pathlib import Path
+
+MVP_TYPES = ["concierge", "wizard-of-oz", "landing-page", "smoke-test"]
+
+MVP_DESCRIPTIONS = {
+    "concierge": (
+        "Manually deliver the service to early customers without automation. "
+        "You act as the 'product' to learn what customers actually want before building."
+    ),
+    "wizard-of-oz": (
+        "Present a working product interface to customers, but fulfil requests manually "
+        "behind the scenes. Validates demand without engineering the full solution."
+    ),
+    "landing-page": (
+        "Publish a description and sign-up form for a product that does not yet exist. "
+        "Measures intent-to-use at near-zero cost."
+    ),
+    "smoke-test": (
+        "Run a small paid-acquisition experiment (e.g., Google Ads) to a landing page. "
+        "Measures real purchase intent before building anything."
+    ),
+}
+
+WHY_NOT_BUILD = {
+    "concierge": (
+        "Building the full automated product before understanding the exact workflow "
+        "customers need risks expensive re-work. Manual delivery surfaces the real "
+        "job-to-be-done faster and cheaper."
+    ),
+    "wizard-of-oz": (
+        "Engineering the back-end automation is costly and time-consuming. "
+        "Validating that customers use and value the front-end experience first "
+        "eliminates the biggest unknown before we invest in automation."
+    ),
+    "landing-page": (
+        "Writing code for a product nobody wants is pure waste. "
+        "A landing page lets us measure whether the value proposition resonates "
+        "with the target segment in days, not months."
+    ),
+    "smoke-test": (
+        "Acquiring real paying customers validates both the value hypothesis and "
+        "the growth hypothesis simultaneously. Building first would delay this "
+        "signal by weeks and obscure whether demand is organic or forced."
+    ),
+}
+
+PIVOT_OPTIONS = [
+    "Zoom-in pivot: narrow scope to the single highest-value feature",
+    "Customer-segment pivot: target a different customer segment with the same product",
+    "Value-capture pivot: change the monetisation model (subscription vs. one-time)",
+    "Channel pivot: switch acquisition channel (e.g., outbound sales → content marketing)",
+    "Technology pivot: solve the same problem with a different underlying technology",
+    "Platform pivot: move from application to platform or vice versa",
+]
+
+
+def prompt(label: str, default: str = "") -> str:
+    suffix = f" [{default}]" if default else ""
+    while True:
+        value = input(f"{label}{suffix}: ").strip()
+        if value:
+            return value
+        if default:
+            return default
+        print("  (required — please enter a value)")
+
+
+def prompt_choice(label: str, choices: list[str]) -> str:
+    print(f"\n{label}")
+    for i, c in enumerate(choices, 1):
+        print(f"  {i}. {c}")
+    while True:
+        raw = input("Enter number: ").strip()
+        if raw.isdigit() and 1 <= int(raw) <= len(choices):
+            return choices[int(raw) - 1]
+        print(f"  Please enter a number between 1 and {len(choices)}.")
+
+
+def gather_interactive() -> dict:
+    print("\n=== Lean Startup — New MVP Experiment ===\n")
+    print("Answer each prompt. Press Enter to accept the default.\n")
+    data: dict = {}
+    data["name"] = prompt("Product / feature name")
+    data["value_hypothesis"] = prompt(
+        "Value hypothesis (customers will value X because Y)"
+    )
+    data["growth_hypothesis"] = prompt(
+        "Growth hypothesis (new customers will find us via ...)"
+    )
+    data["mvp_type"] = prompt_choice("MVP type", MVP_TYPES)
+    data["metric"] = prompt("Primary metric to track (e.g., 'weekly active users')")
+    data["baseline"] = prompt("Current baseline for this metric (e.g., '0', 'unknown')", "0")
+    data["threshold"] = prompt("Success threshold (e.g., '50 sign-ups in 2 weeks')")
+    data["duration"] = prompt("Experiment duration (e.g., '2 weeks')", "2 weeks")
+    data["team"] = prompt("Team / owner", "Product team")
+    return data
+
+
+def parse_duration_weeks(duration_str: str) -> int:
+    """Very simple heuristic: look for a number before 'week'."""
+    import re
+    m = re.search(r"(\d+)\s*week", duration_str, re.IGNORECASE)
+    if m:
+        return int(m.group(1))
+    m = re.search(r"(\d+)\s*day", duration_str, re.IGNORECASE)
+    if m:
+        return max(1, int(m.group(1)) // 7)
+    return 2  # default
+
+
+def render_document(data: dict) -> str:
+    today = date.today()
+    weeks = parse_duration_weeks(data["duration"])
+    decision_date = today + timedelta(weeks=weeks)
+    mvp_type = data["mvp_type"]
+
+    lines = [
+        f"# MVP Experiment: {data['name']}",
+        "",
+        f"**Date created:** {today}  ",
+        f"**Owner:** {data['team']}  ",
+        f"**Pivot/Persevere decision by:** {decision_date}  ",
+        f"**Duration:** {data['duration']}  ",
+        "",
+        "---",
+        "",
+        "## 1. Leap-of-Faith Assumptions",
+        "",
+        "### Value Hypothesis",
+        f"> {data['value_hypothesis']}",
+        "",
+        "This is the core belief we are testing. If customers do not behave as",
+        "predicted, we learn this assumption is false and must pivot.",
+        "",
+        "### Growth Hypothesis",
+        f"> {data['growth_hypothesis']}",
+        "",
+        "---",
+        "",
+        "## 2. Why NOT Build the Full Product Yet",
+        "",
+        WHY_NOT_BUILD[mvp_type],
+        "",
+        "Building the full solution before validating these assumptions would be",
+        "**premature scaling** — one of the most common causes of startup failure",
+        "according to the Lean Startup framework.",
+        "",
+        "---",
+        "",
+        f"## 3. MVP Design — {mvp_type.replace('-', ' ').title()}",
+        "",
+        f"**Type:** {mvp_type}",
+        "",
+        MVP_DESCRIPTIONS[mvp_type],
+        "",
+        "### What we will build / do",
+        "",
+        "- [ ] Define the exact customer action we want to observe",
+        "- [ ] Set up measurement (analytics, tracking, manual log)",
+        "- [ ] Recruit initial participants / drive initial traffic",
+        "- [ ] Execute the experiment and collect data",
+        "- [ ] Analyse results against the success threshold below",
+        "",
+        "### What we will NOT build",
+        "",
+        "- Full back-end automation",
+        "- Production-quality UI beyond what is needed to trigger the measured action",
+        "- Scalability infrastructure",
+        "",
+        "---",
+        "",
+        "## 4. Innovation Accounting",
+        "",
+        "| Metric | Baseline | Target | How We Measure |",
+        "|--------|----------|--------|----------------|",
+        f"| {data['metric']} | {data['baseline']} | {data['threshold']} | [instrument] |",
+        "| Retention (week 2) | — | >30% | Cohort analysis |",
+        "| NPS / qualitative | — | Positive themes | Customer interviews |",
+        "",
+        "Measurements should be **actionable, accessible, auditable** (Three A's).",
+        "Avoid vanity metrics (total page views, total registered users).",
+        "",
+        "---",
+        "",
+        "## 5. Pivot / Persevere Criteria",
+        "",
+        f"**Decision date:** {decision_date}  ",
+        f"**Decision owner:** {data['team']}",
+        "",
+        "### Persevere if",
+        f"- The primary metric reaches or exceeds **{data['threshold']}** by {decision_date}.",
+        "- Customer interviews reveal consistent, strong pull — not polite feedback.",
+        "- At least one customer takes an unexpected high-engagement action.",
+        "",
+        "### Pivot if",
+        f"- The primary metric is below **{data['threshold']}** with no strong upward trend.",
+        "- Qualitative feedback reveals the problem is not painful enough to act on.",
+        "- A significantly different customer segment shows stronger signal.",
+        "",
+        "### Pre-populated Pivot Options",
+        "",
+    ]
+    for opt in PIVOT_OPTIONS:
+        lines.append(f"- {opt}")
+
+    lines += [
+        "",
+        "---",
+        "",
+        "## 6. References",
+        "",
+        "- Ries, E. (2011). *The Lean Startup*. Crown Business.",
+        "- Build-Measure-Learn loop: build the smallest thing that generates the",
+        "  most learning, not the smallest shippable product.",
+        "",
+        "---",
+        "",
+        "*Generated by `new_experiment.py` — Lean Startup skill.*",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate a Lean Startup MVP experiment doc.")
+    parser.add_argument("--name", help="Product or feature name")
+    parser.add_argument("--hypothesis", help="Value hypothesis")
+    parser.add_argument("--mvp-type", choices=MVP_TYPES, dest="mvp_type")
+    parser.add_argument("--metric", help="Primary metric")
+    parser.add_argument("--threshold", help="Success threshold")
+    parser.add_argument("--duration", default="2 weeks", help="Experiment duration")
+    parser.add_argument("--output", type=Path, help="Output file (default: stdout)")
+    args = parser.parse_args()
+
+    # Determine mode: fully specified vs interactive
+    required = ["name", "hypothesis", "mvp_type", "metric", "threshold"]
+    if all(getattr(args, f.replace("-", "_"), None) for f in required):
+        data = {
+            "name": args.name,
+            "value_hypothesis": args.hypothesis,
+            "growth_hypothesis": "To be determined after initial validation.",
+            "mvp_type": args.mvp_type,
+            "metric": args.metric,
+            "baseline": "0",
+            "threshold": args.threshold,
+            "duration": args.duration,
+            "team": "Product team",
+        }
+    else:
+        if any(getattr(args, f.replace("-", "_"), None) for f in required):
+            print(
+                "WARNING: Some flags provided but not all required flags are set. "
+                "Falling back to interactive mode.",
+                file=sys.stderr,
+            )
+        try:
+            data = gather_interactive()
+        except (KeyboardInterrupt, EOFError):
+            print("\nAborted.", file=sys.stderr)
+            sys.exit(1)
+
+    document = render_document(data)
+
+    if args.output:
+        args.output.write_text(document)
+        print(f"\nExperiment document written to: {args.output}")
+        print(f"Next: schedule the pivot/persevere meeting for the decision date shown in the doc.")
+    else:
+        sys.stdout.write(document)
+
+
+if __name__ == "__main__":
+    main()

package/microservices-patterns/SKILL.md

@@ -177,3 +177,143 @@ Priority-ordered list of improvements, from most critical to nice-to-have.
   (independent deployment, team autonomy, technology diversity) outweigh the costs.
 - For deeper pattern details, read `references/patterns-catalog.md` before generating code.
 - For review checklists, read `references/review-checklist.md` before reviewing code.
+
+---
+
+## Mode 3: Service Migration Planning
+
+**Trigger phrases:** "decompose my monolith", "migrate to microservices", "strangle the monolith", "extract a service from"
+
+You are helping a developer plan an incremental migration from a monolith (or distributed monolith) to a microservices architecture. The goal is a **phased migration** using the Strangler Fig pattern — the monolith keeps running while services are extracted one at a time.
+
+### Step 1 — Assess Current State
+
+Classify the system as one of:
+- **Monolith** — Single deployable unit, single database. Starting point for decomposition.
+- **Distributed Monolith** — Multiple services but tightly coupled (shared database, synchronous chains, must deploy together). Often worse than a monolith.
+- **Partly Decomposed** — Some services extracted but shared databases or tight coupling remain.
+
+Flag the critical problems:
+- Shared databases (which tables are shared by which modules?)
+- Synchronous call chains (A → B → C → D, fragile under failure)
+- Missing circuit breakers
+- No compensating transactions for cross-boundary operations
+
+### Step 2 — Phase 1: Identify Boundaries (No Code Change)
+
+**Goal:** Map business capabilities and propose service boundaries before touching code.
+**Risk:** Zero — analysis only.
+
+Actions:
+- Map business capabilities (Order Management, Inventory, Billing, Notifications, etc.)
+- Identify which capabilities are most independent (least shared database tables)
+- Propose decomposition using **Decompose by Business Capability**
+- Draw a capability map: which capabilities share data? Which are truly isolated?
+
+Output: A capability map table showing each candidate service, its data ownership, and coupling level.
+
+**Definition of Done:** Agreement on which service to extract first (least-coupled capability).
+
+### Step 3 — Phase 2: Strangle the Monolith (Low-Risk)
+
+**Goal:** Extract one service at a time using the Strangler Fig pattern.
+**Risk:** Low if done incrementally — monolith keeps running.
+
+Strategy:
+- Start with the **least-coupled** capability (fewest shared tables, fewest synchronous callers)
+- Build the new service alongside the monolith
+- Route new traffic to the new service; keep the monolith handling old traffic
+- Once the new service is stable, cut over the monolith's callers
+
+Order of extraction (typical):
+1. Leaf services (no downstream dependencies) — e.g., Notifications
+2. Read-heavy services (can duplicate read models first)
+3. Write-heavy services (require database decoupling first)
+
+**Definition of Done:** First service deployed independently. Monolith no longer owns that capability.
+
+### Step 4 — Phase 3: Database Decoupling (Medium-Risk)
+
+**Goal:** Give each service its own private database.
+**Risk:** Medium — requires data migration and API contracts between services.
+
+Actions:
+- Identify shared tables; assign ownership to one service
+- Replace shared table reads with API calls or event subscriptions
+- Use the **Database per Service** pattern: each service's schema is off-limits to other services
+- For data that must stay consistent, plan eventual consistency via domain events
+
+Patterns to apply:
+- **Shared Database → separate schemas**: One service owns the table; others read via API
+- **API Composition** for cross-service queries (replaces direct joins)
+- **Domain events** to propagate state changes asynchronously
+
+**Definition of Done:** No service reads from another service's database directly. All cross-service data flows through APIs or events.
+
+### Step 5 — Phase 4: Async Communication (Medium-Risk)
+
+**Goal:** Replace synchronous call chains with messaging; add resilience.
+**Risk:** Medium — changes communication model across services.
+
+Actions:
+- Replace synchronous A → B → C chains with publish/subscribe messaging
+- Add **Circuit Breakers** for remaining synchronous calls (fail fast, fallback)
+- Make message handlers **idempotent** (handle duplicate messages safely)
+- Use **Transactional Outbox** to ensure events are published atomically with database writes
+
+**Definition of Done:** No synchronous chains longer than 2 hops. All event handlers are idempotent.
+
+### Step 6 — Phase 5: Distributed Transactions (High-Risk, As Needed)
+
+**Goal:** Handle multi-service operations that require consistency.
+**Risk:** High — Saga implementation requires careful design of compensating transactions.
+
+Apply when: a single user action must atomically update data owned by 2+ services (e.g., creating an order must both charge payment and reserve inventory).
+
+Actions:
+- Identify cross-service operations requiring consistency
+- Design **Sagas** (choreography or orchestration) with compensating transactions for each step
+- For orchestration: implement a Saga orchestrator state machine
+- For choreography: design event sequences and compensation events
+- Test failure scenarios explicitly
+
+**Definition of Done:** Every multi-service operation has a defined happy path and compensation path. No distributed transactions use 2PC.
+
+### Migration Output Format
+
+```
+## Service Migration Plan: [System Name]
+
+### Current State Assessment
+**Classification:** Monolith
+**Shared databases:** Orders table shared by OrderModule and BillingModule
+**Synchronous chains:** API Gateway → OrderService → InventoryService → NotificationService (3-hop chain)
+
+### Capability Map
+| Capability | Candidate Service | Shared Tables | Coupling Level |
+|------------|------------------|---------------|----------------|
+| Notifications | NotificationService | None | Low — extract first |
+| Inventory | InventoryService | inventory, products | Medium |
+| Orders | OrderService | orders, line_items, payments | High — extract last |
+
+### Phase 1 — Boundaries (start now, no code change)
+- [ ] Agree on service boundaries based on capability map above
+- [ ] Identify NotificationService as first extraction target
+
+### Phase 2 — Strangle the Monolith (next quarter)
+- [ ] Build NotificationService alongside monolith
+- [ ] Route notification calls to new service via API Gateway
+- [ ] Decommission notification code from monolith
+
+### Phase 3 — Database Decoupling (following quarter)
+- [ ] Assign `notifications` table to NotificationService exclusively
+- [ ] Replace OrderModule's direct DB read of customer email with API call to CustomerService
+
+### Phase 4 — Async Communication (6 months)
+- [ ] Replace OrderService → NotificationService sync call with OrderCreated domain event
+- [ ] Add Circuit Breaker to InventoryService call from OrderService
+
+### Phase 5 — Distributed Transactions (as needed)
+- [ ] Design CreateOrderSaga: reserve inventory → charge payment → confirm order
+- [ ] Define compensating transactions: release inventory, void charge
+```

package/microservices-patterns/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-distributed-transaction-no-saga",
+      "prompt": "Review this microservices code for an e-commerce checkout flow:\n\n```java\n// OrderService — orchestrates the entire checkout in one HTTP transaction\n@RestController\npublic class CheckoutController {\n    private final OrderRepository orderRepository;\n    private final InventoryServiceClient inventoryClient;\n    private final PaymentServiceClient paymentClient;\n    private final ShippingServiceClient shippingClient;\n    private final NotificationServiceClient notificationClient;\n    \n    @PostMapping(\"/checkout\")\n    @Transactional  // <-- spans the entire method\n    public OrderConfirmation checkout(@RequestBody CheckoutRequest request) {\n        // Step 1: Reserve inventory\n        inventoryClient.reserveItems(request.getItems());\n        \n        // Step 2: Create order in our DB\n        Order order = orderRepository.save(new Order(request));\n        \n        // Step 3: Charge payment\n        PaymentResult payment = paymentClient.charge(request.getPaymentInfo(), order.getTotal());\n        \n        // Step 4: Create shipping label\n        ShippingLabel label = shippingClient.createLabel(order.getId(), request.getAddress());\n        \n        // Step 5: Send confirmation email\n        notificationClient.sendConfirmation(request.getEmail(), order.getId());\n        \n        order.setShippingLabel(label.getTrackingNumber());\n        order.setStatus(\"CONFIRMED\");\n        return new OrderConfirmation(order.getId(), label.getTrackingNumber());\n    }\n}\n```",
+      "expectations": [
+        "Identifies the core anti-pattern: a distributed transaction where @Transactional spans HTTP calls to 3 external services — this does not work as intended",
+        "Explains why @Transactional cannot span HTTP calls: the ACID transaction boundary is the local database only; remote service calls are not rolled back if a later step fails",
+        "Identifies the failure scenario: if shippingClient.createLabel() throws after paymentClient.charge() succeeds, the customer is charged but never gets a shipping label — and inventory is reserved but no rollback occurs",
+        "Names the pattern that is needed: the Saga pattern (orchestration-based) to handle this cross-service workflow",
+        "Explains compensating transactions: each step needs a corresponding undo — if shipping fails, a ReversePaymentSaga step should issue a refund and a ReleaseInventory step should free reserved stock",
+        "Notes the synchronous chain anti-pattern: OrderService → Inventory → Payment → Shipping → Notification is a fragile chain — if Notification is slow or down, the entire checkout hangs",
+        "Recommends making notifications asynchronous via a message queue (fire-and-forget)",
+        "Suggests using Saga orchestration with explicit saga states (PENDING_INVENTORY, PENDING_PAYMENT, PENDING_SHIPPING, CONFIRMED, FAILED) stored durably"
+      ]
+    },
+    {
+      "id": "eval-02-shared-database",
+      "prompt": "Review this microservices architecture:\n\n```java\n// ProductService — manages product catalog\n@Service\npublic class ProductService {\n    @Autowired\n    private JdbcTemplate jdbc;  // Connects to: jdbc:postgresql://shared-db:5432/platform\n    \n    public Product getProduct(Long id) {\n        return jdbc.queryForObject(\n            \"SELECT * FROM products WHERE id = ?\",\n            new ProductRowMapper(), id);\n    }\n    \n    public void updatePrice(Long productId, BigDecimal newPrice) {\n        jdbc.update(\"UPDATE products SET price = ?, updated_at = NOW() WHERE id = ?\",\n            newPrice, productId);\n    }\n}\n\n// OrderService — in a SEPARATE deployable service/process\n@Service\npublic class OrderService {\n    @Autowired\n    private JdbcTemplate jdbc;  // ALSO connects to: jdbc:postgresql://shared-db:5432/platform\n    \n    public Order createOrder(CreateOrderRequest req) {\n        // Directly reads from products table owned by ProductService\n        BigDecimal price = jdbc.queryForObject(\n            \"SELECT price FROM products WHERE id = ?\",\n            BigDecimal.class, req.getProductId());\n        \n        // Directly joins across service boundaries\n        List<OrderLine> lines = jdbc.query(\n            \"SELECT o.*, p.name, p.sku FROM orders o JOIN products p ON o.product_id = p.id WHERE o.customer_id = ?\",\n            new OrderLineRowMapper(), req.getCustomerId());\n        \n        jdbc.update(\"INSERT INTO orders (product_id, customer_id, price) VALUES (?, ?, ?)\",\n            req.getProductId(), req.getCustomerId(), price);\n        return buildOrder(lines);\n    }\n}\n```",
+      "expectations": [
+        "Identifies the Shared Database anti-pattern: both ProductService and OrderService connect to the same database and directly access each other's tables",
+        "Explains why this is problematic: ProductService cannot change its products table schema without coordinating with OrderService — the services are coupled at the data layer despite being separate deployables",
+        "Flags that OrderService reads from products — meaning ProductService's internal data model is now OrderService's public API; any rename or restructure breaks OrderService",
+        "Flags the cross-service JOIN in SQL: joins across service boundaries are a strong indicator of incorrect service decomposition or a shared database violation",
+        "Explains the correct pattern: each service owns its own database/schema; OrderService should get product information by calling ProductService's API (synchronous) or by maintaining a local read model via events (CQRS)",
+        "Recommends that OrderService should store the price at order-creation time (denormalized) rather than joining live to the products table — price at time of purchase is correct business behavior",
+        "Notes that this architecture makes independent deployment impossible: upgrading ProductService's database schema requires a coordinated deployment with OrderService"
+      ]
+    },
+    {
+      "id": "eval-03-event-driven-saga",
+      "prompt": "Review this saga implementation for a ride-sharing trip booking:\n\n```java\n// TripSaga — orchestrator (Spring Saga / Axon-style pseudocode)\n@Saga\npublic class BookTripSaga {\n    private String tripId;\n    private String driverId;\n    private String paymentAuthId;\n    \n    @StartSaga\n    @SagaEventHandler(associationProperty = \"tripId\")\n    public void on(TripRequestedEvent event) {\n        this.tripId = event.getTripId();\n        commandGateway.send(new FindAvailableDriverCommand(event.getTripId(), event.getLocation()));\n    }\n    \n    @SagaEventHandler(associationProperty = \"tripId\")\n    public void on(DriverAssignedEvent event) {\n        this.driverId = event.getDriverId();\n        commandGateway.send(new AuthorizePaymentCommand(event.getTripId(), event.getEstimatedFare()));\n    }\n    \n    @SagaEventHandler(associationProperty = \"tripId\")\n    public void on(PaymentAuthorizedEvent event) {\n        this.paymentAuthId = event.getAuthorizationId();\n        commandGateway.send(new ConfirmTripCommand(tripId, driverId));\n    }\n    \n    @SagaEventHandler(associationProperty = \"tripId\")\n    public void on(NoDriverAvailableEvent event) {\n        commandGateway.send(new CancelTripCommand(tripId, \"No drivers available\"));\n        SagaLifecycle.end();\n    }\n    \n    @SagaEventHandler(associationProperty = \"tripId\")\n    public void on(PaymentDeclinedEvent event) {\n        // Compensate: release the reserved driver\n        commandGateway.send(new ReleaseDriverCommand(driverId, tripId));\n        commandGateway.send(new CancelTripCommand(tripId, \"Payment declined\"));\n        SagaLifecycle.end();\n    }\n    \n    @EndSaga\n    @SagaEventHandler(associationProperty = \"tripId\")\n    public void on(TripConfirmedEvent event) {\n        // Saga complete — trip is live\n    }\n}\n```",
+      "expectations": [
+        "Recognizes this as a well-designed orchestration-based saga and says so explicitly",
+        "Praises the compensating transactions: PaymentDeclinedEvent triggers both ReleaseDriverCommand and CancelTripCommand — each forward step has a corresponding undo",
+        "Praises that the saga stores intermediate state (driverId, paymentAuthId) to enable compensation — the saga has the information it needs to undo each step",
+        "Praises that the saga is event-driven: each step reacts to an event rather than making synchronous calls — this decouples the booking flow from service availability",
+        "Praises explicit saga lifecycle management: SagaLifecycle.end() on failure paths and @EndSaga on success ensure the saga doesn't leak memory",
+        "Praises modeling failure paths as first-class events (NoDriverAvailableEvent, PaymentDeclinedEvent) — not exceptions, but domain events the saga handles explicitly",
+        "Does NOT manufacture fake issues just to have something to say",
+        "May offer optional suggestions (timeout handling if DriverAssignedEvent never arrives, idempotent command handlers) but frames them as additional robustness, not defects in the current design"
+      ]
+    }
+  ]
+}

package/microservices-patterns/examples/after.md

@@ -0,0 +1,69 @@
+# After
+
+`InventoryService` owns its own read model, populated by consuming `OrderLineItemAdded` domain events published by the Order Service — no shared database access.
+
+```java
+// --- Order Service publishes domain events (its own codebase) ---
+
+@DomainEvent
+public record OrderLineItemAdded(
+    String orderId,
+    String productId,
+    int quantity,
+    Instant occurredAt
+) {}
+
+// Order Service publishes this event after saving the order aggregate
+orderEventPublisher.publish(new OrderLineItemAdded(
+    order.getId(), line.getProductId(), line.getQuantity(), Instant.now()
+));
+
+
+// --- Inventory Service: owns its own read model, no shared DB ---
+
+// Private denormalized table — owned exclusively by Inventory Service
+@Entity @Table(name = "product_weekly_sales")
+public class ProductWeeklySales {
+    @Id private String productId;
+    private int unitsSoldLast7Days;
+    private Instant lastUpdated;
+}
+
+@Component
+public class OrderLineItemAddedConsumer {
+
+    @KafkaListener(topics = "order.events", groupId = "inventory-service")
+    public void handle(OrderLineItemAdded event) {
+        // Idempotent: uses event's occurredAt to filter stale events
+        if (event.occurredAt().isBefore(Instant.now().minus(7, DAYS))) return;
+
+        weeklySalesRepository.incrementUnitsSold(event.productId(), event.quantity());
+    }
+}
+
+@RestController @RequestMapping("/inventory")
+public class InventoryController {
+
+    @GetMapping("/reorder-candidates")
+    public List<ReorderItem> getReorderCandidates() {
+        // Queries Inventory Service's OWN database — no cross-service DB access
+        return weeklySalesRepository.findAll().stream()
+            .filter(sales -> {
+                int stockLevel = stockRepository.getLevel(sales.getProductId());
+                return stockLevel < sales.getUnitsSoldLast7Days() * 2;
+            })
+            .map(sales -> new ReorderItem(
+                sales.getProductId(),
+                sales.getUnitsSoldLast7Days() * 3 - stockRepository.getLevel(sales.getProductId())
+            ))
+            .toList();
+    }
+}
+```
+
+Key improvements:
+- Each service owns its database — `InventoryService` never touches the `orders` schema (Database per Service pattern)
+- `OrderLineItemAdded` domain event decouples the services; Order Service does not know Inventory Service exists
+- `ProductWeeklySales` is a denormalized read model maintained by consuming events — a lightweight CQRS view
+- The Kafka consumer is idempotent: events outside the 7-day window are skipped, making re-delivery safe
+- Deleting the coupling to `sharedDataSource` eliminates the risk that a schema change in Order Service breaks Inventory Service at runtime