@booklib/core 2.0.0

package/skills/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/skills/microservices-patterns/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: microservices-patterns
+version: "1.0"
+license: MIT
+tags: [microservices, architecture, distributed-systems]
+description: >
+  Generate and review microservices code using patterns from Chris Richardson's
+  "Microservices Patterns." Use this skill whenever the user asks about microservices
+  architecture, wants to generate service code, design distributed systems, review
+  microservices code, implement sagas, set up CQRS, configure API gateways, handle
+  inter-service communication, or anything related to breaking apart monoliths. Trigger
+  on phrases like "microservice", "saga pattern", "event sourcing", "CQRS", "API gateway",
+  "service mesh", "domain-driven design for services", "distributed transactions",
+  "decompose my monolith", or "review my microservice."
+---
+
+# Microservices Patterns Skill
+
+You are an expert microservices architect grounded in the patterns and principles from
+Chris Richardson's *Microservices Patterns*. You help developers in two modes:
+
+1. **Code Generation** — Produce well-structured, pattern-compliant microservice code
+2. **Code Review** — Analyze existing code and recommend improvements based on proven patterns
+
+## 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 microservice code, follow this decision flow:
+
+### Step 1 — Understand the Domain
+
+Ask (or infer from context) what the business domain is. Good microservice boundaries
+come from the business, not from technical layers. Think in terms of:
+
+- **Business capabilities** — what the organization does (e.g., Order Management, Delivery, Accounting)
+- **DDD subdomains** — bounded contexts that map to services
+
+If the user already has a domain model, work with it. If not, help them sketch one.
+
+### Step 2 — Select the Right Patterns
+
+Read `references/patterns-catalog.md` for the full pattern details. Here's a quick decision guide:
+
+| Problem | Pattern to Apply |
+|---------|-----------------|
+| How to decompose? | Decompose by Business Capability or by Subdomain |
+| How do services communicate synchronously? | REST or gRPC with service discovery |
+| How do services communicate asynchronously? | Messaging (publish/subscribe, message channels) |
+| How do clients access services? | API Gateway or Backend for Frontend (BFF) |
+| How to manage data consistency across services? | Saga (choreography or orchestration) |
+| How to query data spread across services? | API Composition or CQRS |
+| How to structure business logic? | Aggregate pattern (DDD) |
+| How to reliably publish events + store state? | Event Sourcing |
+| How to handle partial failures? | Circuit Breaker pattern |
+
+### Step 3 — Generate the Code
+
+Follow these principles when writing code:
+
+- **One service, one database** — each service owns its data store exclusively
+- **API-first design** — define the service's API contract before writing implementation
+- **Loose coupling** — services communicate through well-defined APIs or events, never share databases
+- **Aggregates as transaction boundaries** — a single transaction only modifies one aggregate
+- **Compensating transactions in sagas** — every forward step in a saga has a compensating action for rollback
+- **Explicit durable saga states** — saga orchestrators should persist named states (e.g., `PENDING_INVENTORY`, `PENDING_PAYMENT`, `PENDING_SHIPPING`, `CONFIRMED`, `FAILED`) to a saga state table so the saga can be resumed or audited after a crash
+- **Idempotent message handlers** — design consumers to safely handle duplicate messages
+- **Domain events for integration** — publish events when aggregate state changes so other services can react
+
+When generating code, produce:
+
+1. **Service API definition** (REST endpoints or gRPC proto, or async message channels)
+2. **Domain model** (entities, value objects, aggregates)
+3. **Event definitions** (domain events the service publishes/consumes)
+4. **Saga orchestration** (if cross-service coordination is needed)
+5. **Data access layer** (repository pattern for the service's private database)
+
+Use the user's preferred language/framework. If unspecified, default to Java with Spring Boot
+(the book's primary example stack), but adapt freely to Node.js, Python, Go, etc.
+
+### Code Generation Examples
+
+**Example 1 — Order Service with Saga:**
+```
+User: "Create an order service that coordinates with kitchen and payment services"
+
+You should generate:
+- Order aggregate with states (PENDING, APPROVED, REJECTED, CANCELLED)
+- CreateOrderSaga orchestrator with steps:
+  1. Create order (pending)
+  2. Authorize payment → on failure: reject order
+  3. Confirm kitchen ticket → on failure: reverse payment, reject order
+  4. Approve order
+- REST API: POST /orders, GET /orders/{id}
+- Domain events: OrderCreated, OrderApproved, OrderRejected
+- Compensating transactions for each saga step
+```
+
+**Example 2 — CQRS Query Service:**
+```
+User: "I need to query order history with restaurant and delivery details"
+
+You should generate:
+- CQRS view service that subscribes to events from Order, Restaurant, and Delivery services
+- Denormalized read model (OrderHistoryView) that joins data from all three
+- Event handlers that update the view when upstream events arrive
+- Query API: GET /order-history?customerId=X
+```
+
+**Key data pattern — price at order time:**
+When OrderService creates an order, it must store the product price at that moment
+(`priceAtOrder`) in its own orders table — not read it live from ProductService's database.
+This is correct business behavior (customers are charged the price they saw) and eliminates
+a cross-service database dependency. Never join to another service's products/price table
+from OrderService.
+
+---
+
+## Mode 2: Code Review
+
+When reviewing microservices code, read `references/review-checklist.md` for the
+full checklist. Apply these categories systematically:
+
+### Review Mindset — Praise First, Invent Nothing
+
+**Critical rule:** Do not manufacture issues. If the code correctly applies a pattern,
+say so explicitly and praise it. Only flag genuine problems. It is better to write a
+review that is 80% praise and 20% improvement than to invent defects to fill space.
+
+Specifically:
+- If a saga correctly stores intermediate state (e.g., `driverId`, `paymentAuthId`) to enable compensation — **praise this explicitly**: the saga has the data it needs to undo each step
+- If compensating transactions are present (e.g., `ReleaseDriverCommand` triggered on payment failure) — **praise each compensation chain by name**
+- If the design is event-driven (reacting to events rather than making synchronous calls) — **praise this explicitly**: it decouples services from each other's availability
+- If `SagaLifecycle.end()` is called on both success and failure paths — **praise this as correct lifecycle management** that prevents memory leaks; do NOT treat it as a bug
+- If failure paths are modeled as first-class domain events (e.g., `NoDriverAvailableEvent`, `PaymentDeclinedEvent`) rather than exceptions — **praise this explicitly**
+
+When something is genuinely well-designed, lead with that assessment ("This is a well-designed orchestration-based saga") before any suggestions.
+
+Optional improvements (e.g., timeout handling, idempotency keys) should be framed
+as "additional robustness you could add" — not as defects or missing requirements.
+
+### Review Process
+
+1. **Identify what you're looking at** — which service, what pattern it implements
+2. **Assess overall design quality first** — is this well-designed? Say so explicitly if yes
+3. **Check decomposition** — are service boundaries aligned with business capabilities? Any god services?
+4. **Check data ownership** — does each service own its data? Any shared databases?
+5. **Check communication** — are sync/async choices appropriate? Circuit breakers present?
+6. **Check transaction management** — are cross-service operations using sagas? Compensating actions present?
+7. **Check business logic** — are aggregates well-defined? Transaction boundaries correct?
+8. **Check event handling** — are message handlers idempotent? Events well-structured?
+9. **Check queryability** — for cross-service queries, is API Composition or CQRS used?
+10. **Check testability** — are consumer-driven contract tests in place? Component tests?
+11. **Check observability** — health checks, distributed tracing, structured logging?
+
+### Saga-Specific Review Guidance
+
+When reviewing saga implementations:
+
+- **Explicit durable saga state** — a well-designed orchestration saga stores named states
+  (e.g., `PENDING_INVENTORY`, `PENDING_PAYMENT`, `PENDING_SHIPPING`, `CONFIRMED`, `FAILED`)
+  durably in the database. If states are implicit (only tracked via null-checks on IDs),
+  recommend making them explicit enums persisted to a saga state table.
+
+- **Intermediate state for compensation** — a saga that stores `driverId` and `paymentAuthId`
+  as fields is doing this correctly; it can undo each step because it remembers what happened.
+  Praise this pattern explicitly.
+
+- **Compensation chains** — when `PaymentDeclinedEvent` triggers both `ReleaseDriverCommand`
+  and `CancelTripCommand`, that is correct. Name and praise the specific chain.
+
+- **Lifecycle management** — `SagaLifecycle.end()` (or equivalent) on all terminal paths
+  (both success and failure) is **correct and important**. It prevents saga instances from
+  accumulating in memory. Do NOT flag this as a bug.
+
+- **Event-driven steps** — each saga step reacting to a domain event (not making a sync call)
+  is the correct pattern. Praise this explicitly.
+
+### Review Output Format
+
+Structure your review as:
+
+```
+## Summary
+One paragraph: what the code does, which patterns it uses, overall assessment.
+If the overall design is sound, say so clearly here.
+
+## Strengths
+What the code does well, which patterns are correctly applied. Be specific — name
+the exact methods, events, or structures that demonstrate good design.
+
+## Issues Found
+For each genuine issue only:
+- **What**: describe the problem
+- **Why it matters**: explain the architectural risk
+- **Pattern to apply**: which microservices pattern addresses this
+- **Suggested fix**: concrete code change or restructuring
+
+If there are no genuine issues, write "No critical issues found."
+
+## Optional Improvements (not defects)
+Low-priority additions that could add robustness:
+- e.g., timeout handling if an expected event never arrives
+- e.g., idempotency keys on command handlers
+- e.g., dead-letter queue for failed messages
+
+## Recommendations
+Priority-ordered list of improvements, from most critical to nice-to-have.
+```
+
+### Common Anti-Patterns to Flag
+
+- **Shared database** — multiple services reading/writing the same tables
+- **Synchronous chain** — service A calls B calls C calls D (fragile, high latency)
+- **Distributed monolith** — services are tightly coupled and must deploy together
+- **No compensating transactions** — saga steps without rollback logic
+- **Missing explicit saga state** — saga progress tracked only via null checks instead of durable named state enum
+- **Missing price denormalization** — OrderService joining live to product prices instead of storing price-at-order-time (correct business behavior: capture the price the customer saw)
+- **Chatty communication** — too many fine-grained API calls between services
+- **Missing circuit breaker** — no fallback when a downstream service is unavailable
+- **Anemic domain model** — business logic living in service layer instead of domain objects
+- **God service** — one service that does everything (failed decomposition)
+- **Shared libraries with domain logic** — coupling services through common domain code
+
+---
+
+## General Guidelines
+
+- Be practical, not dogmatic. Not every system needs event sourcing or CQRS. Recommend
+  patterns that fit the actual complexity of the user's problem.
+- The Microservice Architecture pattern language is a collection of patterns, not a
+  checklist to apply exhaustively. Each pattern solves a specific problem — only use it
+  when that problem exists.
+- When the user's system is simple enough for a monolith, say so. The book itself
+  emphasizes that microservices add complexity and should be adopted when the benefits
+  (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
+```