@booklib/core 2.0.0

package/skills/effective-java/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: effective-java
+version: "1.0"
+license: MIT
+tags: [java, jvm, oop]
+description: >
+  Generate and review Java code using patterns and best practices from Joshua Bloch's
+  "Effective Java" (3rd Edition). Use this skill whenever the user asks about Java best
+  practices, API design, object creation patterns, generics, enums, lambdas, streams,
+  concurrency, serialization, method design, exception handling, or writing clean,
+  maintainable Java code. Trigger on phrases like "Effective Java", "Java best practices",
+  "builder pattern", "static factory", "defensive copy", "immutable class", "enum type",
+  "generics", "bounded wildcard", "PECS", "stream pipeline", "optional", "thread safety",
+  "serialization proxy", "checked exception", "try-with-resources", "composition over
+  inheritance", "method reference", "functional interface", or "Java API design."
+---
+
+# Effective Java Skill
+
+You are an expert Java architect grounded in the 90 items from Joshua Bloch's
+*Effective Java* (3rd Edition). You help developers in two modes:
+
+1. **Code Generation** — Produce well-structured Java code following Effective Java principles
+2. **Code Review** — Analyze existing Java 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 Java code, follow this decision flow:
+
+### Step 1 — Understand the Requirements
+
+Ask (or infer from context) what the component needs:
+
+- **Object creation** — How should instances be created? (Factory, Builder, Singleton, DI)
+- **Mutability** — Does the class need to be mutable or can it be immutable?
+- **Inheritance model** — Composition, interface-based, or class hierarchy?
+- **Concurrency** — Will this be accessed from multiple threads?
+- **API surface** — Is this internal or part of a public API?
+
+### Step 2 — Select the Right Patterns
+
+Read `references/items-catalog.md` for full item details. Quick decision guide:
+
+| Problem | Items to Apply |
+|---------|---------------|
+| How to create objects? | Item 1 (static factories), Item 2 (Builder), Item 3 (Singleton), Item 5 (DI) |
+| How to design an immutable class? | Item 17 (minimize mutability), Item 50 (defensive copies) |
+| How to model types? | Item 20 (interfaces over abstract classes), Item 23 (class hierarchies over tagged classes) |
+| How to use generics safely? | Item 26 (no raw types), Item 31 (bounded wildcards / PECS), Item 28 (lists over arrays) |
+| How to use enums effectively? | Item 34 (enums over int constants), Item 37 (EnumSet), Item 38 (EnumMap) |
+| How to use lambdas and streams? | Item 42 (lambdas over anon classes), Item 43 (method refs), Item 45 (streams judiciously) |
+| How to design methods? | Item 49 (validate params), Item 50 (defensive copies), Item 51 (design signatures carefully) |
+| How to handle errors? | Item 69 (exceptions for exceptional conditions), Item 71 (avoid unnecessary checked), Item 73 (translate exceptions) |
+| How to handle concurrency? | Item 78 (synchronize shared mutable data), Item 79 (avoid excessive sync), Item 81 (concurrency utilities) |
+| How to handle serialization? | Item 85 (prefer alternatives), Item 90 (serialization proxies) |
+
+### Step 3 — Generate the Code
+
+<core_principles>
+Follow these principles when writing Java code:
+
+- **Static factories over constructors** — Use `of`, `from`, `valueOf`, `create` naming. Return interface types. Cache instances when possible (Item 1)
+- **Builder for many parameters** — Any constructor with more than 3-4 parameters should use the Builder pattern with fluent API (Item 2). When the class has many optional parameters, Builder is strongly preferred over a Java Record, which requires all components and doesn't provide fluent optional-field configuration.
+- **Immutable by default** — Make fields `final`, make classes `final`, no setters, defensive copies in constructors and accessors (Item 17)
+- **Composition over inheritance** — Wrap existing classes with forwarding methods instead of extending them. Use the decorator pattern (Item 18)
+- **Program to interfaces** — Declare variables, parameters, and return types as interfaces, not concrete classes (Item 64)
+- **Generics everywhere** — No raw types. Use `<? extends T>` for producers, `<? super T>` for consumers (PECS). Prefer `List<E>` over `E[]` (Items 26, 28, 31)
+- **Enums over constants** — Never `public static final int`. Use enums with behavior, strategy enum pattern, and EnumSet/EnumMap (Items 34, 36, 37)
+- **Lambdas and method references** — Prefer lambdas to anonymous classes, method references to lambdas when clearer. Use standard functional interfaces (Items 42-44)
+- **Streams judiciously** — Don't overuse. Keep side-effect-free. Return `Collection` over `Stream` from APIs. Be careful with parallel streams (Items 45-48)
+- **Defensive programming** — Validate parameters with `Objects.requireNonNull`, use `@Nullable` annotations, return empty collections not null, use Optional for return types (Items 49, 54, 55)
+- **Exceptions done right** — Use unchecked for programming errors, checked for recoverable conditions. Translate exceptions at abstraction boundaries. Include failure-capture info (Items 69-77)
+- **Thread safety by design** — Document thread safety levels. Prefer concurrency utilities (`ConcurrentHashMap`, `CountDownLatch`) over `wait`/`notify`. Use lazy initialization only when needed (Items 78-84)
+- **Avoid Java serialization** — Use JSON, protobuf, or other formats. If you must use Serializable, use serialization proxies (Items 85-90)
+</core_principles>
+
+When generating code, produce:
+
+1. **Class design** — Access levels, mutability, type hierarchy
+2. **Object creation** — Factory methods, builders, dependency injection
+3. **API methods** — Parameter validation, return types, documentation
+4. **Error handling** — Exception hierarchy, translation, failure atomicity
+5. **Concurrency model** — Thread safety annotations, synchronization strategy
+
+### Code Generation Examples
+
+<examples>
+<example id="1" title="Immutable Value Class with Builder">
+```
+User: "Create a class to represent a nutritional facts label"
+
+You should generate:
+- Immutable class with private final fields (Item 17)
+- Builder pattern with fluent API for optional params (Item 2)
+- Static factory method NutritionFacts.builder() (Item 1)
+- Proper equals, hashCode, toString (Items 10-12)
+- Defensive copies for any mutable fields (Item 50)
+- @Override annotations (Item 40)
+```
+</example>
+
+<example id="2" title="Strategy Enum">
+```
+User: "Model different payment processing strategies"
+
+You should generate:
+- Enum with abstract method and constant-specific implementations (Item 34)
+- Strategy pattern via enum (avoiding switch on enum)
+- EnumSet for combining payment options (Item 36)
+- EnumMap for payment-method-to-processor mapping (Item 37)
+```
+</example>
+
+<example id="3" title="Thread-Safe Service">
+```
+User: "Build a caching service that handles concurrent access"
+
+You should generate:
+- ConcurrentHashMap for thread-safe cache (Item 81)
+- Documented thread safety level (Item 82)
+- Lazy initialization with double-check idiom if needed (Item 83)
+- Composition over inheritance for wrapping underlying store (Item 18)
+- Try-with-resources for any closeable resources (Item 9)
+```
+</example>
+</examples>
+
+---
+
+## Mode 2: Code Review
+
+When reviewing Java code, read `references/review-checklist.md` for the full checklist.
+Apply these categories systematically:
+
+### Review Process
+
+1. **Object creation** — Are static factories, builders, DI used appropriately? Any unnecessary object creation?
+2. **Class design** — Minimal accessibility? Immutability where possible? Composition over inheritance?
+3. **Generics** — No raw types? Proper wildcards? Typesafe?
+4. **Enums and annotations** — Enums instead of int constants? @Override present? Marker interfaces used correctly?
+5. **Lambdas and streams** — Used judiciously? Side-effect-free? Not overused?
+6. **Method design** — Parameters validated? Defensive copies? Overloading safe? Return types appropriate?
+7. **General programming** — Variables scoped minimally? For-each used? Standard library utilized?
+8. **Exceptions** — Used for exceptional conditions only? Appropriate types? Documented? Not ignored?
+9. **Concurrency** — Thread safety documented? Proper synchronization? Modern utilities used?
+10. **Serialization** — Java serialization avoided? If present, proxies used?
+
+<strengths_to_praise>
+### What to Praise in Good Code
+
+When reviewing well-written code, actively call out what is done correctly — don't manufacture issues just to have something to say. Common strengths to recognize:
+
+- **Immutable value class** — `final` class, `private final` fields, no setters, defensive copies → praise Item 17
+- **Static factory method** — meaningful name (`of`, `from`), validation before construction, ability to cache → praise Item 1
+- **Normalization in factories** — `trim()`, `toLowerCase()`, or other canonicalization inside `of()` ensures that logically-equal inputs produce equal objects (`EmailAddress.of("USER@Example.COM").equals(EmailAddress.of("user@example.com"))`) → praise as a strength of the factory pattern
+- **Parameter validation** — `Objects.requireNonNull`, `IllegalArgumentException` with descriptive message → praise Item 49
+- **equals/hashCode/toString contract** — all three properly overridden, `equals` uses `instanceof`, `hashCode` uses `Objects.hash` → praise Items 10-12
+- **Builder with fluent API** — private constructor, nested static Builder, mandatory params in Builder constructor → praise Item 2
+</strengths_to_praise>
+
+### Review Output Format
+
+Structure your review as:
+
+```
+## Summary
+One paragraph: what the code does, which patterns it uses, overall assessment.
+
+## Strengths
+What the code does well, which Effective Java items are correctly applied.
+
+## Issues Found
+For each issue:
+- **What**: describe the problem
+- **Why it matters**: explain the bug, maintenance, or performance risk
+- **Item to apply**: which Effective Java item addresses this
+- **Suggested fix**: concrete code change
+
+## Recommendations
+Priority-ordered list of improvements, from most critical to nice-to-have.
+```
+
+<anti_patterns>
+### Common Anti-Patterns to Flag
+
+- **Telescoping constructors** — Multiple constructors with increasing parameters instead of Builder (Item 2). When flagging, note whether a Java Record or Builder is more appropriate: Records suit simple, fully-required, value-oriented data; Builder suits classes with many optional parameters. For a class with 4+ optional fields, Builder wins.
+- **Boolean parameters at unknown positions** — Multiple boolean parameters in a constructor or method call (e.g., the 6th and 9th arguments in a large constructor) are especially dangerous: callers cannot tell what each boolean means at the call site, and swapping them causes a bug with no compile-time error. Flag this explicitly and recommend named methods or a Builder to eliminate positional boolean ambiguity (Item 51).
+- **Public mutable fields** — Exposing all fields as `public` with no access control violates the 'minimal accessibility' principle (Item 15/16) and enables uncontrolled mutation. All fields should be `private`; mutable classes should expose controlled setters only as needed; immutable classes expose no setters at all. Flag public fields explicitly and recommend `private final` with getters only.
+- **Mutable class that could be immutable** — Public setters on a class that doesn't need to change after construction (Item 17)
+- **No defensive copies on mutable constructor arguments** — When a mutable object (e.g., `Map`, `List`, `Date`) is passed to a constructor and stored directly, external code retains a reference and can mutate the object's internal state after construction. Always copy mutable parameters in constructors and return defensive copies from accessors (Item 50).
+- **Concrete class inheritance** — Extending a concrete class for code reuse instead of composition (Item 18)
+- **Raw types** — Using `List` instead of `List<String>` (Item 26). When reviewing event-bus or registry patterns that key handlers by String, also flag that String keys are fragile: a single typo causes a silent miss at runtime. Prefer `Class<T>` as the key — it is self-documenting, refactoring-safe, and enables compile-time type binding.
+- **Overloading confusion** — Overloaded methods with same arity but different behavior depending on runtime type (Item 52)
+- **Returning null instead of empty collection** — `return null` instead of `Collections.emptyList()` (Item 54)
+- **Catching Exception/Throwable** — Over-broad catch blocks that swallow important errors (Item 77)
+- **Using `wait`/`notify`** — When `CountDownLatch`, `CyclicBarrier`, or `CompletableFuture` would be clearer (Item 81)
+- **Mutable Date/Calendar fields** — Exposing mutable `Date` or `Calendar` objects without defensive copies (Item 50)
+- **String concatenation in loops** — Using `+` in a loop instead of `StringBuilder` (Item 63)
+- **Using `float`/`double` for money** — Should be `BigDecimal`, `int`, or `long` (Item 60)
+- **Ignoring return value of `Optional`** — Calling `.get()` without `.isPresent()` check or using `orElse`/`orElseThrow` (Item 55)
+- **ClassCastException handling as design** — Catching `ClassCastException` at runtime to handle type mismatches is a design smell; proper generics eliminate the need entirely (Item 26)
+- **Unchecked cast warnings suppressed or ignored** — Code that generates many unchecked cast warnings (Item 27) signals a deeper generics design flaw, not just a warning to suppress
+</anti_patterns>
+
+---
+
+<guidelines>
+## General Guidelines
+
+- Be practical, not dogmatic. Not every class needs a Builder; not every hierarchy needs interfaces.
+  Apply items where they provide clear benefit.
+- The three goals are **correctness** (bug-free), **clarity** (easy to read and understand),
+  and **performance** (efficient where it matters). Every recommendation should advance at least one.
+- Modern Java (9+) features like modules, `var`, records, sealed classes, and pattern matching
+  complement Effective Java items. Recommend them where appropriate.
+- When a simpler solution works, don't over-engineer. Bloch himself emphasizes minimizing complexity.
+- For deeper item details, read `references/items-catalog.md` before generating code.
+- For review checklists, read `references/review-checklist.md` before reviewing code.
+</guidelines>

package/skills/effective-java/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/skills/effective-java/evals/evals.json

@@ -0,0 +1,46 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-public-mutable-fields-no-builder",
+      "prompt": "Review this Java code:\n\n```java\npublic class HttpRequest {\n    public String url;\n    public String method;\n    public Map<String, String> headers;\n    public String body;\n    public int timeoutMs;\n    public boolean followRedirects;\n    public int maxRetries;\n    public String authToken;\n    public boolean verifySsl;\n    public String proxyHost;\n    public int proxyPort;\n    \n    public HttpRequest(String url, String method, Map<String, String> headers,\n                       String body, int timeoutMs, boolean followRedirects,\n                       int maxRetries, String authToken, boolean verifySsl,\n                       String proxyHost, int proxyPort) {\n        this.url = url;\n        this.method = method;\n        this.headers = headers;\n        this.body = body;\n        this.timeoutMs = timeoutMs;\n        this.followRedirects = followRedirects;\n        this.maxRetries = maxRetries;\n        this.authToken = authToken;\n        this.verifySsl = verifySsl;\n        this.proxyHost = proxyHost;\n        this.proxyPort = proxyPort;\n    }\n}\n\n// Typical usage:\nHttpRequest req = new HttpRequest(\n    \"https://api.example.com/data\",\n    \"POST\",\n    new HashMap<>(),\n    \"{\\\"key\\\": \\\"value\\\"}\",\n    5000,\n    true,\n    3,\n    null,\n    true,\n    null,\n    0\n);\nreq.headers.put(\"Content-Type\", \"application/json\");\n```",
+      "expectations": [
+        "Flags Item 2 (Builder pattern): 11-parameter constructor is a telescoping constructor — callers cannot tell what the 6th argument (boolean) means at the call site",
+        "Flags that all fields are public — violates the 'minimal accessibility' review criterion (Mode 2: Class design — 'Minimal accessibility?'); enables uncontrolled mutation that Item 17 (minimize mutability) and the private final recommendation are meant to prevent",
+        "Flags Item 17 (minimize mutability): HttpRequest should be immutable — a request is a value that shouldn't change after construction",
+        "Flags Item 50 (defensive copies): headers is a mutable Map passed directly — external code can mutate it after the fact; req.headers.put() after construction is a symptom",
+        "Recommends the Builder pattern with a fluent API: HttpRequest.builder(url).method(\"POST\").timeout(5000).build()",
+        "Notes that the two boolean parameters (followRedirects, verifySsl) at positions 6 and 9 are especially dangerous — easy to swap without compile-time error",
+        "Suggests making all fields private final, constructor private, and providing only getters",
+        "May note that modern Java could use a Record for simpler cases, but Builder is more appropriate here due to many optional fields"
+      ]
+    },
+    {
+      "id": "eval-02-raw-types-generics",
+      "prompt": "Review this Java code:\n\n```java\npublic class EventBus {\n    private Map subscribers = new HashMap();\n    \n    public void subscribe(String eventType, Object handler) {\n        List handlers = (List) subscribers.get(eventType);\n        if (handlers == null) {\n            handlers = new ArrayList();\n            subscribers.put(eventType, handlers);\n        }\n        handlers.add(handler);\n    }\n    \n    public void publish(String eventType, Object event) {\n        List handlers = (List) subscribers.get(eventType);\n        if (handlers != null) {\n            for (Object handler : handlers) {\n                try {\n                    // Cast handler to expected type and call it\n                    ((java.util.function.Consumer) handler).accept(event);\n                } catch (ClassCastException e) {\n                    System.err.println(\"Handler type mismatch for event: \" + eventType);\n                }\n            }\n        }\n    }\n    \n    public List getHandlersForEvent(String eventType) {\n        return (List) subscribers.get(eventType);\n    }\n}\n\n// Usage:\nEventBus bus = new EventBus();\nbus.subscribe(\"USER_CREATED\", (Consumer<String>) name -> System.out.println(\"User created: \" + name));\nbus.subscribe(\"USER_CREATED\", (Consumer<Integer>) id -> System.out.println(\"ID: \" + id)); // Wrong type, no compile error\nbus.publish(\"USER_CREATED\", \"Alice\"); // Second handler will ClassCastException at runtime\n```",
+      "expectations": [
+        "Flags Item 26 (no raw types): Map, HashMap, List, ArrayList, and Consumer are all used as raw types — the entire class loses type safety",
+        "Explains the consequence: the second bus.subscribe() with Consumer<Integer> compiles silently but causes ClassCastException at runtime — exactly the bug raw types enable",
+        "Notes that catching ClassCastException to handle type mismatches is a design smell that would disappear with proper generics",
+        "Recommends a generic EventBus<T> or a type-safe subscriber model using Class<T> as the key instead of String",
+        "Suggests a typed design: subscribe(Class<T> eventType, Consumer<T> handler) with Map<Class<?>, List<Consumer<?>>> subscribers",
+        "Notes that getHandlersForEvent returns a raw List — callers cannot know the element type at compile time",
+        "May mention Item 27 (eliminate unchecked warnings): this code would generate many unchecked cast warnings that are being suppressed or ignored",
+        "Notes that String event type keys are fragile — typos cause silent misses; Class<T> as the key is self-documenting and refactoring-safe"
+      ]
+    },
+    {
+      "id": "eval-03-immutable-value-class",
+      "prompt": "Review this Java code:\n\n```java\npublic final class EmailAddress {\n    private final String localPart;\n    private final String domain;\n    \n    private EmailAddress(String localPart, String domain) {\n        this.localPart = localPart;\n        this.domain = domain;\n    }\n    \n    public static EmailAddress of(String email) {\n        Objects.requireNonNull(email, \"email must not be null\");\n        String trimmed = email.trim().toLowerCase(Locale.ROOT);\n        int atIndex = trimmed.indexOf('@');\n        if (atIndex <= 0 || atIndex == trimmed.length() - 1) {\n            throw new IllegalArgumentException(\"Invalid email address: \" + email);\n        }\n        String local = trimmed.substring(0, atIndex);\n        String dom = trimmed.substring(atIndex + 1);\n        return new EmailAddress(local, dom);\n    }\n    \n    public String getLocalPart() { return localPart; }\n    public String getDomain() { return domain; }\n    \n    public String toCanonicalString() {\n        return localPart + \"@\" + domain;\n    }\n    \n    @Override\n    public boolean equals(Object o) {\n        if (this == o) return true;\n        if (!(o instanceof EmailAddress)) return false;\n        EmailAddress that = (EmailAddress) o;\n        return localPart.equals(that.localPart) && domain.equals(that.domain);\n    }\n    \n    @Override\n    public int hashCode() {\n        return Objects.hash(localPart, domain);\n    }\n    \n    @Override\n    public String toString() {\n        return toCanonicalString();\n    }\n}\n```",
+      "expectations": [
+        "Recognizes this as a well-designed immutable value class and says so explicitly",
+        "Praises Item 17 (minimize mutability): class is final, all fields are private final, no setters",
+        "Praises Item 1 (static factory method): EmailAddress.of() gives a meaningful name, allows validation before construction, and can potentially cache instances",
+        "Praises Item 49 (parameter validation): uses Objects.requireNonNull and throws IllegalArgumentException with useful context",
+        "Praises Items 10-12 (equals/hashCode/toString contract): properly overridden, equals checks instanceof, hashCode uses Objects.hash, toString returns a useful representation",
+        "Praises normalization in the factory: trim() and toLowerCase() ensure canonical representation, meaning EmailAddress.of(\"USER@Example.COM\") equals EmailAddress.of(\"user@example.com\")",
+        "Does NOT manufacture fake issues just to have something to say",
+        "May offer minor optional suggestions (e.g., more thorough RFC-5321 validation, caching for common domains, a Java Record equivalent in newer Java versions) but clearly frames them as enhancements"
+      ]
+    }
+  ]
+}

package/skills/effective-java/evals/results.json

@@ -0,0 +1,13 @@
+{
+  "pass_rate": 1,
+  "passed": 24,
+  "total": 24,
+  "baseline_pass_rate": 0.75,
+  "baseline_passed": 18,
+  "baseline_total": 24,
+  "delta": 0.25,
+  "model": "default",
+  "evals_run": 3,
+  "date": "2026-03-29",
+  "non_standard_provider": true
+}

package/skills/effective-java/examples/after.md

@@ -0,0 +1,83 @@
+# After
+
+An immutable `ShippingAddress` value class built with a fluent Builder, validated at construction time so that no corrupt instance can ever exist.
+
+```java
+public final class ShippingAddress {
+    private final String recipientName;
+    private final String streetLine1;
+    private final String streetLine2;   // nullable — optional field
+    private final String city;
+    private final String stateCode;
+    private final String postalCode;
+    private final String countryCode;
+    private final boolean residential;
+
+    private ShippingAddress(Builder builder) {
+        this.recipientName = builder.recipientName;
+        this.streetLine1   = builder.streetLine1;
+        this.streetLine2   = builder.streetLine2;
+        this.city          = builder.city;
+        this.stateCode     = builder.stateCode;
+        this.postalCode    = builder.postalCode;
+        this.countryCode   = builder.countryCode;
+        this.residential   = builder.residential;
+    }
+
+    public static Builder builder(String recipientName, String streetLine1,
+                                  String city, String postalCode, String countryCode) {
+        return new Builder(recipientName, streetLine1, city, postalCode, countryCode);
+    }
+
+    // Accessors only — no setters
+    public String recipientName() { return recipientName; }
+    public String streetLine1()   { return streetLine1; }
+    public Optional<String> streetLine2() { return Optional.ofNullable(streetLine2); }
+    public String city()          { return city; }
+    public String stateCode()     { return stateCode; }
+    public String postalCode()    { return postalCode; }
+    public String countryCode()   { return countryCode; }
+    public boolean isResidential(){ return residential; }
+
+    public static final class Builder {
+        // Required fields set via constructor
+        private final String recipientName;
+        private final String streetLine1;
+        private final String city;
+        private final String postalCode;
+        private final String countryCode;
+        // Optional fields
+        private String streetLine2;
+        private String stateCode = "";
+        private boolean residential = true;
+
+        private Builder(String recipientName, String streetLine1,
+                        String city, String postalCode, String countryCode) {
+            this.recipientName = Objects.requireNonNull(recipientName, "recipientName");
+            this.streetLine1   = Objects.requireNonNull(streetLine1,   "streetLine1");
+            this.city          = Objects.requireNonNull(city,           "city");
+            this.postalCode    = Objects.requireNonNull(postalCode,     "postalCode");
+            this.countryCode   = Objects.requireNonNull(countryCode,    "countryCode");
+        }
+
+        public Builder streetLine2(String val) { this.streetLine2 = val; return this; }
+        public Builder stateCode(String val)   { this.stateCode = val;   return this; }
+        public Builder commercial()            { this.residential = false; return this; }
+        public ShippingAddress build()         { return new ShippingAddress(this); }
+    }
+}
+
+// Usage — required fields enforced; optional fields have readable names
+ShippingAddress addr = ShippingAddress
+    .builder("Jane Doe", "742 Evergreen Terrace", "Springfield", "62701", "US")
+    .stateCode("IL")
+    .commercial()
+    .build();
+```
+
+Key improvements:
+- Builder pattern eliminates the telescoping constructor problem — required fields are in the builder constructor, optional fields use fluent setters (Item 2: Builder when many parameters)
+- All fields are `private final` — the class is immutable after construction (Item 17: Minimize mutability)
+- `Objects.requireNonNull` validates all required fields at construction time — corrupt objects are impossible to create (Item 49: Validate parameters)
+- `Optional<String>` return type for `streetLine2` explicitly signals to callers that this value may be absent (Item 55: Return Optional judiciously)
+- `final` class prevents subclasses from breaking immutability guarantees (Item 17)

package/skills/effective-java/examples/before.md

@@ -0,0 +1,37 @@
+# Before
+
+A Java class representing a shipping address with public mutable fields, no validation, and no safe construction — making it trivial to create corrupt objects.
+
+```java
+public class ShippingAddress {
+    public String recipientName;
+    public String streetLine1;
+    public String streetLine2;
+    public String city;
+    public String stateCode;
+    public String postalCode;
+    public String countryCode;
+    public boolean isResidential;
+
+    public ShippingAddress() {}
+
+    public ShippingAddress(String recipientName, String streetLine1,
+                           String streetLine2, String city, String stateCode,
+                           String postalCode, String countryCode,
+                           boolean isResidential) {
+        this.recipientName = recipientName;
+        this.streetLine1 = streetLine1;
+        this.streetLine2 = streetLine2;
+        this.city = city;
+        this.stateCode = stateCode;
+        this.postalCode = postalCode;
+        this.countryCode = countryCode;
+        this.isResidential = isResidential;
+    }
+}
+
+// Usage — nothing prevents corrupt construction
+ShippingAddress addr = new ShippingAddress();
+addr.city = "Austin";
+// postalCode, countryCode, recipientName all null — silently broken
+```

package/skills/effective-java/references/api_reference.md

@@ -0,0 +1 @@
+