@booklib/skills 1.2.0 → 1.3.0

package/domain-driven-design/SKILL.md

@@ -219,3 +219,123 @@ Priority-ordered list of improvements, from most critical to nice-to-have.
   but the patterns are framework-agnostic.
 - 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: Domain Migration Planning
+
+**Trigger phrases:** "migrate to DDD", "enrich my domain model", "extract value objects from", "refactor toward DDD", "strangler fig for domain"
+
+You are helping a developer incrementally migrate an existing codebase toward Domain-Driven Design — without a full rewrite. The goal is a **phased migration plan** that progressively enriches the domain model, reduces Primitive Obsession, and establishes proper Aggregate boundaries.
+
+### Step 1 — Assess Current State
+
+Classify the codebase as one of:
+- **Transaction Script** — Procedural service methods manipulating passive data objects. All logic in services, domain objects are mere structs.
+- **Anemic Domain Model** — Classes look like Entities but have only getters/setters. Business logic lives in services.
+- **Partial DDD** — Some patterns applied (e.g., Value Objects exist) but boundaries are fuzzy or Aggregates are anemic.
+
+Identify the worst anti-patterns present (Primitive Obsession, missing invariant enforcement, broken Bounded Contexts, leaking infrastructure).
+
+### Step 2 — Phase 1: Ubiquitous Language (Zero-Risk)
+
+**Goal:** Rename classes and methods to domain terms. No structural change.
+**Risk:** Near zero — rename-only refactoring.
+
+Actions:
+- Rename technical names to domain language (e.g., `UserData` → `Customer`, `ItemManager` → `InventoryService`)
+- Build a Ubiquitous Language glossary mapping old names → new names
+- Ensure method names reflect domain operations (e.g., `updateStatus(2)` → `approve()`)
+
+**Definition of Done:** A domain expert can read class and method names without a translator.
+
+### Step 3 — Phase 2: Value Objects (Low-Risk)
+
+**Goal:** Extract Primitive Obsession into immutable Value Objects.
+**Risk:** Low — additive change; old primitives gradually replaced.
+
+Actions:
+- Identify primitives used as domain concepts: orderId (String), price (double), email (String)
+- Create immutable Value Objects with validation in constructor: `OrderId`, `Money`, `Email`
+- Replace primitive usages one class at a time
+- Add equality semantics (attribute-based equality, not identity)
+
+Before: `String email = "user@example.com";`
+After: `Email email = Email.of("user@example.com"); // validates format`
+
+**Definition of Done:** No primitive types represent domain concepts in Entity constructors or method signatures.
+
+### Step 4 — Phase 3: Aggregate Boundaries (Medium-Risk)
+
+**Goal:** Define Aggregate roots and enforce invariants inside them.
+**Risk:** Medium — changes cascade to callers and repositories.
+
+Actions:
+- Identify clusters of objects that change together (Aggregate candidates)
+- Designate Aggregate roots; route all external access through them
+- Remove external setters; enforce invariants via domain methods
+- Reference other Aggregates by ID only (no direct object references across boundaries)
+- Wrap related creation logic in Factory methods
+
+**Definition of Done:** No code outside an Aggregate can violate its invariants. Cross-Aggregate references are by ID only.
+
+### Step 5 — Phase 4: Repositories & Domain Services (Medium-Risk)
+
+**Goal:** Add Repository interfaces per Aggregate root; extract Domain Services.
+**Risk:** Medium — requires infrastructure layer changes.
+
+Actions:
+- Add a Repository interface (domain layer) for each Aggregate root
+- Move persistence implementation to infrastructure; domain layer knows nothing about databases
+- Extract operations that don't belong to any Entity into stateless Domain Services
+- Name Domain Services in Ubiquitous Language
+
+**Definition of Done:** Domain layer has zero imports from persistence frameworks. Each Aggregate root has exactly one Repository.
+
+### Step 6 — Phase 5: Strategic Design (High-Risk, Optional)
+
+**Goal:** Identify Bounded Contexts; protect domain model from external systems.
+**Risk:** High — may require restructuring module/package boundaries.
+
+Actions:
+- Map Bounded Contexts (where does one domain model end and another begin?)
+- Build Anticorruption Layers for external integrations (legacy systems, third-party APIs)
+- Identify Shared Kernels vs. Customer/Supplier relationships between contexts
+- Apply Strangler Fig if migrating from a monolith: route new domain through new model, keep legacy running
+
+**Definition of Done:** Each Bounded Context has a clear boundary. External models don't corrupt the core domain.
+
+### Migration Output Format
+
+```
+## DDD Migration Plan: [System/Module Name]
+
+### Current State Assessment
+**Classification:** Anemic Domain Model
+**Key anti-patterns:** Primitive Obsession (orderId as String), external setters on Order, all logic in OrderService
+
+### Phase 1 — Ubiquitous Language (start now)
+- [ ] Rename `OrderData` → `Order`
+- [ ] Rename `processOrder()` → `placeOrder()`
+**Glossary:**
+| Old Name | New Name | Reason |
+|----------|----------|--------|
+| OrderData | Order | Domain entity, not a data bag |
+
+### Phase 2 — Value Objects (next sprint)
+- [ ] Extract `OrderId` from `String orderId`
+- [ ] Extract `Money` from `double price`
+**Before:** `double price = 99.99;`
+**After:** `Money price = Money.of(new BigDecimal("99.99"), Currency.USD);`
+
+### Phase 3 — Aggregate Boundaries (following sprint)
+- [ ] Make Order the Aggregate root; remove direct LineItem mutation from OrderController
+- [ ] Add `Order.addLineItem(LineItem)` enforcing max-items invariant
+
+### Phase 4 — Repositories & Services (planned)
+- [ ] Add `OrderRepository` interface in domain layer
+- [ ] Extract `PricingService` from `OrderService.calculateTotal()`
+
+### Phase 5 — Strategic Design (future)
+- [ ] Identify Billing Context boundary; add ACL to translate Payment gateway model
+```

package/domain-driven-design/evals/evals.json

@@ -0,0 +1,48 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-anemic-domain-model",
+      "prompt": "Review this code for a loan application system:\n\n```java\n// Domain object — just data\npublic class LoanApplication {\n    private String applicantId;\n    private BigDecimal requestedAmount;\n    private int termMonths;\n    private String status; // PENDING, APPROVED, REJECTED, DISBURSED\n    private BigDecimal approvedAmount;\n    private String rejectionReason;\n    private LocalDate applicationDate;\n    private String reviewerId;\n    \n    // getters and setters for all fields...\n}\n\n// All logic lives here\npublic class LoanApplicationService {\n    private LoanApplicationRepository repository;\n    private CreditScoreService creditScoreService;\n    private RiskEngine riskEngine;\n    \n    public void approveLoan(String applicationId, String reviewerId, BigDecimal approvedAmount) {\n        LoanApplication application = repository.findById(applicationId);\n        if (!application.getStatus().equals(\"PENDING\")) {\n            throw new IllegalStateException(\"Can only approve PENDING applications\");\n        }\n        if (approvedAmount.compareTo(application.getRequestedAmount()) > 0) {\n            throw new IllegalArgumentException(\"Approved amount cannot exceed requested amount\");\n        }\n        application.setStatus(\"APPROVED\");\n        application.setApprovedAmount(approvedAmount);\n        application.setReviewerId(reviewerId);\n        repository.save(application);\n    }\n    \n    public void rejectLoan(String applicationId, String reviewerId, String reason) {\n        LoanApplication application = repository.findById(applicationId);\n        if (!application.getStatus().equals(\"PENDING\")) {\n            throw new IllegalStateException(\"Can only reject PENDING applications\");\n        }\n        application.setStatus(\"REJECTED\");\n        application.setRejectionReason(reason);\n        application.setReviewerId(reviewerId);\n        repository.save(application);\n    }\n    \n    public boolean isEligibleForFastTrack(String applicationId) {\n        LoanApplication application = repository.findById(applicationId);\n        int creditScore = creditScoreService.getScore(application.getApplicantId());\n        return creditScore > 750 && application.getRequestedAmount().compareTo(new BigDecimal(\"50000\")) <= 0;\n    }\n}\n```",
+      "expectations": [
+        "Identifies this as an Anemic Domain Model — LoanApplication is a data bag with no behavior, all logic pushed into the service layer",
+        "Flags that approve() and reject() are domain operations that belong on the LoanApplication aggregate, not in the service",
+        "Notes that the invariant 'can only approve PENDING applications' is a business rule that LoanApplication should enforce internally",
+        "Flags Primitive Obsession: status as String instead of a LoanStatus enum or Value Object; applicantId and reviewerId as raw Strings instead of typed Value Objects (ApplicantId, ReviewerId)",
+        "Notes that requestedAmount and approvedAmount should be a Money Value Object (amount + currency), not a bare BigDecimal",
+        "Points out that the service directly sets fields via setters (setStatus, setApprovedAmount) — bypasses any invariant enforcement and breaks encapsulation",
+        "Recommends moving approve(ReviewerId reviewerId, Money approvedAmount) and reject(ReviewerId reviewerId, String reason) methods onto LoanApplication itself",
+        "Suggests that the service layer should be thin: load aggregate → call domain method → save",
+        "References the anti-pattern: 'Transaction Script masquerading as DDD — procedural service methods that manipulate passive data objects'"
+      ]
+    },
+    {
+      "id": "eval-02-missing-value-object",
+      "prompt": "Review this code for a shipping system:\n\n```java\npublic class Shipment {\n    private String id;\n    private String recipientName;\n    private String streetAddress;\n    private String city;\n    private String stateCode;\n    private String postalCode;\n    private String countryCode;\n    private String senderName;\n    private String senderStreet;\n    private String senderCity;\n    private String senderStateCode;\n    private String senderPostalCode;\n    private String senderCountryCode;\n    private double weightKg;\n    private double lengthCm;\n    private double widthCm;\n    private double heightCm;\n    private String trackingNumber;\n    private String status;\n    \n    public double calculateVolumetricWeight() {\n        return (lengthCm * widthCm * heightCm) / 5000.0;\n    }\n    \n    public double getBillableWeight() {\n        double volumetric = calculateVolumetricWeight();\n        return Math.max(weightKg, volumetric);\n    }\n    \n    public boolean isInternational() {\n        return !senderCountryCode.equals(countryCode);\n    }\n    \n    public String formatRecipientAddress() {\n        return recipientName + \"\\n\" + streetAddress + \"\\n\" +\n               city + \", \" + stateCode + \" \" + postalCode + \"\\n\" + countryCode;\n    }\n    \n    public String formatSenderAddress() {\n        return senderName + \"\\n\" + senderStreet + \"\\n\" +\n               senderCity + \", \" + senderStateCode + \" \" + senderPostalCode + \"\\n\" + senderCountryCode;\n    }\n}\n```",
+      "expectations": [
+        "Identifies the missing Value Objects: Address (street, city, state, postal code, country) is a natural concept that is duplicated for sender and recipient",
+        "Identifies a second Value Object: Dimensions (length, width, height) with volumetric weight behavior",
+        "Identifies a third Value Object candidate: Weight (value + unit — kg is baked into the field name but not the type)",
+        "Notes that the Shipment Entity is bloated with 19 fields — a God Entity collecting too many responsibilities",
+        "Points out that formatRecipientAddress() and formatSenderAddress() are the same logic duplicated with different field names — a symptom of not having an Address Value Object",
+        "Notes that calculateVolumetricWeight() belongs on a Dimensions Value Object, not on Shipment",
+        "Flags Primitive Obsession: all fields are raw strings/doubles instead of typed domain concepts",
+        "Recommends concrete refactoring: extract Address, Dimensions, Weight Value Objects; Shipment holds Address recipient, Address sender, Dimensions, Weight",
+        "Notes Value Objects should be immutable with attribute-based equality"
+      ]
+    },
+    {
+      "id": "eval-03-well-designed-aggregate",
+      "prompt": "Review this domain model for a bank account system:\n\n```java\npublic class AccountId {\n    private final String value;\n    \n    public AccountId(String value) {\n        if (value == null || value.isBlank()) throw new IllegalArgumentException(\"AccountId cannot be blank\");\n        this.value = value;\n    }\n    \n    public String getValue() { return value; }\n    \n    @Override public boolean equals(Object o) {\n        if (this == o) return true;\n        if (!(o instanceof AccountId)) return false;\n        return value.equals(((AccountId) o).value);\n    }\n    @Override public int hashCode() { return value.hashCode(); }\n}\n\npublic class Money {\n    private final BigDecimal amount;\n    private final Currency currency;\n    \n    public Money(BigDecimal amount, Currency currency) {\n        if (amount == null || currency == null) throw new IllegalArgumentException();\n        this.amount = amount;\n        this.currency = currency;\n    }\n    \n    public Money add(Money other) {\n        if (!this.currency.equals(other.currency)) throw new IllegalArgumentException(\"Currency mismatch\");\n        return new Money(this.amount.add(other.amount), this.currency);\n    }\n    \n    public Money subtract(Money other) {\n        if (!this.currency.equals(other.currency)) throw new IllegalArgumentException(\"Currency mismatch\");\n        return new Money(this.amount.subtract(other.amount), this.currency);\n    }\n    \n    public boolean isNegative() { return amount.compareTo(BigDecimal.ZERO) < 0; }\n    \n    // equals, hashCode based on amount and currency\n}\n\npublic class BankAccount {\n    private final AccountId id;\n    private Money balance;\n    private final List<Transaction> ledger;\n    private AccountStatus status;\n    \n    private BankAccount(AccountId id, Money initialBalance) {\n        this.id = id;\n        this.balance = initialBalance;\n        this.ledger = new ArrayList<>();\n        this.status = AccountStatus.ACTIVE;\n    }\n    \n    public static BankAccount open(AccountId id, Money initialDeposit) {\n        if (initialDeposit.isNegative()) throw new IllegalArgumentException(\"Initial deposit must be positive\");\n        return new BankAccount(id, initialDeposit);\n    }\n    \n    public void deposit(Money amount) {\n        if (status != AccountStatus.ACTIVE) throw new IllegalStateException(\"Cannot deposit to a \" + status + \" account\");\n        if (amount.isNegative()) throw new IllegalArgumentException(\"Deposit amount must be positive\");\n        this.balance = this.balance.add(amount);\n        ledger.add(Transaction.credit(amount));\n    }\n    \n    public void withdraw(Money amount) {\n        if (status != AccountStatus.ACTIVE) throw new IllegalStateException(\"Cannot withdraw from a \" + status + \" account\");\n        if (amount.isNegative()) throw new IllegalArgumentException(\"Withdrawal amount must be positive\");\n        Money newBalance = this.balance.subtract(amount);\n        if (newBalance.isNegative()) throw new DomainException(\"Insufficient funds\");\n        this.balance = newBalance;\n        ledger.add(Transaction.debit(amount));\n    }\n    \n    public void close() {\n        if (!balance.equals(Money.zero(balance.getCurrency()))) {\n            throw new DomainException(\"Cannot close account with non-zero balance\");\n        }\n        this.status = AccountStatus.CLOSED;\n    }\n    \n    public Money getBalance() { return balance; }\n    public List<Transaction> getLedger() { return Collections.unmodifiableList(ledger); }\n    public AccountId getId() { return id; }\n}\n```",
+      "expectations": [
+        "Recognizes this as a well-designed Aggregate and says so explicitly",
+        "Praises AccountId and Money as properly modeled Value Objects — immutable, attribute-based equality, validated in constructor",
+        "Praises the factory method BankAccount.open() for enforcing invariants at creation time",
+        "Praises that all business rules (no overdraft, no deposit to closed account, cannot close with balance) are enforced inside the aggregate rather than in a service layer",
+        "Praises that getLedger() returns an unmodifiable list — protecting the internal collection from external mutation",
+        "Praises the closed constructor — external code cannot create a BankAccount without going through the factory method",
+        "Does NOT manufacture fake issues just to have something to say",
+        "May offer optional suggestions (domain events for deposit/withdrawal, separate TransactionId Value Object) but clearly frames them as enhancements, not defects"
+      ]
+    }
+  ]
+}

package/domain-driven-design/examples/after.md

@@ -0,0 +1,80 @@
+# After
+
+`Order` becomes a rich aggregate root that owns its invariants and exposes domain-language behavior; `OrderService` becomes a thin application-layer coordinator.
+
+```java
+// Rich aggregate root — enforces all invariants internally
+public class Order {
+    private final OrderId id;
+    private final List<OrderLine> lines = new ArrayList<>();
+    private OrderStatus status;
+    private Money total;
+
+    private Order(OrderId id, CustomerId customerId) {
+        this.id = id;
+        this.status = OrderStatus.PENDING;
+        this.total = Money.ZERO;
+    }
+
+    public static Order place(OrderId id, CustomerId customerId) {
+        return new Order(id, customerId);
+    }
+
+    public void addItem(Product product, int quantity) {
+        Validate.isTrue(quantity > 0, "Quantity must be positive");
+        Validate.isTrue(status == OrderStatus.PENDING, "Cannot modify a non-pending order");
+        lines.add(OrderLine.of(product.getId(), product.getPrice(), quantity));
+        recalculateTotal();
+    }
+
+    public void confirm() {
+        if (lines.isEmpty()) {
+            throw new DomainException("Cannot confirm an order with no items");
+        }
+        this.status = OrderStatus.CONFIRMED;
+    }
+
+    public void cancel() {
+        if (!status.isCancellable()) {
+            throw new DomainException("Order in status " + status + " cannot be cancelled");
+        }
+        this.status = OrderStatus.CANCELLED;
+    }
+
+    private void recalculateTotal() {
+        this.total = lines.stream()
+            .map(OrderLine::lineTotal)
+            .reduce(Money.ZERO, Money::add);
+    }
+
+    // Getters return immutable views only
+    public List<OrderLine> lines() { return Collections.unmodifiableList(lines); }
+    public Money total()           { return total; }
+    public OrderStatus status()    { return status; }
+}
+
+// Application service is thin — orchestrates, does not contain business rules
+public class PlaceOrderUseCase {
+    private final OrderRepository orderRepository;
+    private final ProductRepository productRepository;
+
+    public OrderId execute(PlaceOrderCommand cmd) {
+        Order order = Order.place(OrderId.generate(), cmd.customerId());
+        for (var item : cmd.requestedItems()) {
+            Product product = productRepository.findById(item.productId())
+                .orElseThrow(() -> new ProductNotFoundException(item.productId()));
+            order.addItem(product, item.quantity());
+        }
+        order.confirm();
+        orderRepository.save(order);
+        return order.getId();
+    }
+}
+```
+
+Key improvements:
+- Business rules (`confirm`, `cancel`, `addItem`) live inside `Order` — the anemic model anti-pattern is eliminated
+- `Order.status.isCancellable()` encapsulates the cancellation-eligibility rule in an enum method rather than in a service
+- External code cannot corrupt the aggregate: `lines` is returned as an unmodifiable view; `total` is always recalculated internally
+- `OrderService` is renamed to `PlaceOrderUseCase` per the Ubiquitous Language (application command, not a generic "service")
+- `Money` is a Value Object, preventing `double` arithmetic errors on financial amounts (Primitive Obsession eliminated)

package/domain-driven-design/examples/before.md

@@ -0,0 +1,43 @@
+# Before
+
+An anemic domain model where the `Order` class is a passive data container with no behavior, and all business logic is scattered across `OrderService`.
+
+```java
+// Anemic entity — just a data bag
+public class Order {
+    public Long id;
+    public List<OrderLine> lines;
+    public String status;
+    public BigDecimal totalAmount;
+    public String customerId;
+}
+
+// All logic lives in the service
+public class OrderService {
+
+    public void addItem(Order order, Product product, int quantity) {
+        OrderLine line = new OrderLine();
+        line.productId = product.id;
+        line.quantity = quantity;
+        line.unitPrice = product.price;
+        order.lines.add(line);
+        order.totalAmount = order.lines.stream()
+            .map(l -> l.unitPrice.multiply(BigDecimal.valueOf(l.quantity)))
+            .reduce(BigDecimal.ZERO, BigDecimal::add);
+    }
+
+    public void cancel(Order order) {
+        if (!order.status.equals("PENDING") && !order.status.equals("CONFIRMED")) {
+            throw new IllegalStateException("Cannot cancel");
+        }
+        order.status = "CANCELLED";
+    }
+
+    public void confirm(Order order) {
+        if (order.lines == null || order.lines.isEmpty()) {
+            throw new IllegalStateException("Cannot confirm empty order");
+        }
+        order.status = "CONFIRMED";
+    }
+}
+```