@kodrunhq/opencode-autopilot 1.9.0 → 1.11.0

package/assets/skills/frontend-design/SKILL.md

@@ -0,0 +1,433 @@
+---
+name: frontend-design
+description: State-of-the-art frontend UX/UI design patterns covering component architecture, responsive design, accessibility, and design system integration
+stacks:
+  - react
+  - vue
+  - svelte
+  - angular
+requires: []
+---
+
+# Frontend Design Patterns
+
+Practical frontend design patterns for building polished, accessible, and performant user interfaces. Covers component architecture, responsive design, accessibility, state management, animation, visual design principles, and design system integration. Apply these when building, reviewing, or refactoring frontend code.
+
+## 1. Component Architecture
+
+**DO:** Structure components using atomic design principles and clear composition patterns.
+
+- Organize components as atoms, molecules, and organisms:
+  ```
+  atoms/        Button, Input, Label, Icon, Badge
+  molecules/    SearchBar (Input + Button), FormField (Label + Input + Error)
+  organisms/    Header (Logo + Nav + SearchBar), OrderForm (FormFields + Submit)
+  ```
+- Use compound components for related elements that share state:
+  ```jsx
+  // DO: Compound component -- parent manages shared state
+  <Select value={selected} onChange={setSelected}>
+    <Select.Trigger>{selected}</Select.Trigger>
+    <Select.Options>
+      <Select.Option value="a">Option A</Select.Option>
+      <Select.Option value="b">Option B</Select.Option>
+    </Select.Options>
+  </Select>
+  ```
+- Separate container (data fetching, state) from presentational (rendering) components:
+  ```jsx
+  // Container: handles data
+  function OrderListContainer() {
+    const { data, isLoading } = useOrders();
+    return <OrderList orders={data} loading={isLoading} />;
+  }
+
+  // Presentational: pure rendering
+  function OrderList({ orders, loading }) {
+    if (loading) return <Skeleton count={3} />;
+    return orders.map(o => <OrderCard key={o.id} order={o} />);
+  }
+  ```
+- Use composition (children, slots) instead of prop drilling:
+  ```jsx
+  // DO: Composition via children
+  <Card>
+    <Card.Header>Title</Card.Header>
+    <Card.Body>{content}</Card.Body>
+    <Card.Footer><Button>Save</Button></Card.Footer>
+  </Card>
+
+  // DON'T: Prop drilling through many levels
+  <Card title="Title" content={content} buttonText="Save" onButtonClick={...} />
+  ```
+
+**DON'T:**
+
+- Pass data through more than 2 intermediate components (prop drilling) -- use context, composition, or state management
+- Create components with more than 10 props -- split into smaller components or use composition
+- Mix data fetching with rendering in the same component
+- Use `index` as `key` for lists that can be reordered, filtered, or mutated
+
+## 2. Responsive Design
+
+**DO:** Design mobile-first and use modern CSS features for fluid layouts.
+
+- Use `min-width` breakpoints (mobile-first):
+  ```css
+  /* Base: mobile */
+  .grid { display: flex; flex-direction: column; }
+
+  /* Tablet and up */
+  @media (min-width: 768px) {
+    .grid { flex-direction: row; flex-wrap: wrap; }
+  }
+
+  /* Desktop and up */
+  @media (min-width: 1024px) {
+    .grid { max-width: 1200px; margin: 0 auto; }
+  }
+  ```
+- Use `clamp()` for fluid typography:
+  ```css
+  /* Fluid font size: 1rem at 320px, 1.5rem at 1200px */
+  h1 { font-size: clamp(1rem, 0.5rem + 2.5vw, 1.5rem); }
+  ```
+- Use container queries for component-level responsiveness:
+  ```css
+  .card-container { container-type: inline-size; }
+
+  @container (min-width: 400px) {
+    .card { display: flex; flex-direction: row; }
+  }
+  ```
+- Use `aspect-ratio` for media containers:
+  ```css
+  .video-wrapper { aspect-ratio: 16 / 9; width: 100%; }
+  .avatar { aspect-ratio: 1; border-radius: 50%; }
+  ```
+- Use logical properties for internationalization:
+  ```css
+  /* DO: Works for LTR and RTL */
+  .sidebar { margin-inline-start: 1rem; padding-block: 0.5rem; }
+
+  /* DON'T: Only works for LTR */
+  .sidebar { margin-left: 1rem; padding-top: 0.5rem; padding-bottom: 0.5rem; }
+  ```
+- Use responsive images:
+  ```html
+  <picture>
+    <source srcset="hero-wide.webp" media="(min-width: 1024px)" />
+    <source srcset="hero-medium.webp" media="(min-width: 640px)" />
+    <img src="hero-small.webp" alt="Hero image" loading="lazy" />
+  </picture>
+  ```
+
+**DON'T:**
+
+- Use `max-width` breakpoints (desktop-first) -- mobile-first produces smaller CSS and better progressive enhancement
+- Use fixed pixel widths for layouts -- use relative units (`rem`, `%`, `fr`, `vw`)
+- Hide content with `display: none` on mobile instead of designing a mobile-appropriate layout
+- Use `@media` for component-level responsiveness when container queries are available
+
+## 3. Accessibility (a11y)
+
+**DO:** Build accessible interfaces from the start, not as an afterthought.
+
+- Use semantic HTML elements:
+  ```html
+  <!-- DO: Semantic -->
+  <nav aria-label="Main navigation">
+    <ul>
+      <li><a href="/home">Home</a></li>
+      <li><a href="/about">About</a></li>
+    </ul>
+  </nav>
+
+  <!-- DON'T: Div soup -->
+  <div class="nav">
+    <div class="nav-item" onclick="goto('/home')">Home</div>
+    <div class="nav-item" onclick="goto('/about')">About</div>
+  </div>
+  ```
+- Use ARIA only when native HTML semantics are insufficient:
+  ```html
+  <!-- DO: ARIA for custom widgets -->
+  <div role="tablist">
+    <button role="tab" aria-selected="true" aria-controls="panel-1">Tab 1</button>
+    <div role="tabpanel" id="panel-1">Content 1</div>
+  </div>
+
+  <!-- DON'T: ARIA on native elements that already have semantics -->
+  <button role="button">Submit</button>  <!-- Redundant -->
+  ```
+- Manage focus for keyboard navigation:
+  ```jsx
+  // Skip link for keyboard users
+  <a href="#main-content" className="skip-link">Skip to main content</a>
+
+  // Focus management in modals
+  function Modal({ isOpen, onClose }) {
+    const closeRef = useRef(null);
+    useEffect(() => {
+      if (isOpen) closeRef.current?.focus();
+    }, [isOpen]);
+    // Trap focus inside modal while open
+  }
+  ```
+- Meet WCAG AA color contrast minimums:
+  ```css
+  /* AA minimums: 4.5:1 for normal text, 3:1 for large text */
+  .text { color: #333; background: #fff; }     /* 12.6:1 -- PASS */
+  .text { color: #999; background: #fff; }     /* 2.8:1  -- FAIL */
+  ```
+- Use `focus-visible` for keyboard-only focus indicators:
+  ```css
+  button:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }
+  button:focus:not(:focus-visible) { outline: none; }
+  ```
+- Use live regions for dynamic content updates:
+  ```html
+  <div aria-live="polite" aria-atomic="true">
+    {statusMessage}  <!-- Screen readers announce changes -->
+  </div>
+  ```
+
+**DON'T:**
+
+- Use `div` or `span` for interactive elements -- use `button`, `a`, `input`, `select`
+- Remove focus outlines without providing an alternative visual indicator
+- Use color alone to convey information (add icons, text, or patterns)
+- Use `tabindex` values greater than 0 -- it disrupts natural tab order
+- Auto-play video or audio without user consent
+
+## 4. State Management
+
+**DO:** Start with the simplest state solution and scale up only when needed.
+
+- Use local state first -- most state belongs to a single component:
+  ```jsx
+  function Counter() {
+    const [count, setCount] = useState(0);
+    return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+  }
+  ```
+- Separate server state from client state:
+  ```jsx
+  // Server state: fetched, cached, synced with backend (use React Query/SWR)
+  const { data: orders } = useQuery({ queryKey: ['orders'], queryFn: fetchOrders });
+
+  // Client state: UI-only (use useState/useReducer)
+  const [isFilterOpen, setFilterOpen] = useState(false);
+  ```
+- Use URL as state for shareable, bookmarkable views:
+  ```jsx
+  // Search params as state
+  const [searchParams, setSearchParams] = useSearchParams();
+  const page = Number(searchParams.get("page") ?? "1");
+  const filter = searchParams.get("status") ?? "all";
+  ```
+- Use optimistic updates for perceived performance:
+  ```jsx
+  const mutation = useMutation({
+    mutationFn: updateOrder,
+    onMutate: async (newOrder) => {
+      await queryClient.cancelQueries({ queryKey: ['orders'] });
+      const previous = queryClient.getQueryData(['orders']);
+      queryClient.setQueryData(['orders'], old => optimisticUpdate(old, newOrder));
+      return { previous };
+    },
+    onError: (err, newOrder, context) => {
+      queryClient.setQueryData(['orders'], context.previous);  // Rollback
+    },
+  });
+  ```
+
+**DON'T:**
+
+- Put everything in global state -- only share state that multiple components need simultaneously
+- Use global state for server data -- use a data fetching library with caching (React Query, SWR, RTK Query)
+- Store derived values in state -- compute them during render:
+  ```jsx
+  // DON'T: Derived state
+  const [total, setTotal] = useState(0);
+  useEffect(() => setTotal(items.reduce(...)), [items]);
+
+  // DO: Computed value
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+  ```
+
+## 5. Animation and Interaction
+
+**DO:** Use animations purposefully to provide feedback and guide attention.
+
+- Use CSS transitions for simple state changes:
+  ```css
+  .button {
+    transition: background-color 150ms ease, transform 100ms ease;
+  }
+  .button:hover { background-color: var(--color-hover); }
+  .button:active { transform: scale(0.97); }
+  ```
+- Respect reduced motion preferences:
+  ```css
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      animation-duration: 0.01ms !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+  ```
+- Use `will-change` sparingly for GPU acceleration hints:
+  ```css
+  /* Only on elements that WILL animate, not everything */
+  .sliding-panel { will-change: transform; }
+  .sliding-panel.idle { will-change: auto; }  /* Remove when done */
+  ```
+- Use Intersection Observer for scroll-triggered animations:
+  ```jsx
+  function FadeIn({ children }) {
+    const ref = useRef(null);
+    const isVisible = useIntersectionObserver(ref, { threshold: 0.1 });
+    return (
+      <div ref={ref} className={isVisible ? "fade-in visible" : "fade-in"}>
+        {children}
+      </div>
+    );
+  }
+  ```
+- Prefer skeleton screens over spinners:
+  ```jsx
+  // DO: Skeleton preserves layout, reduces perceived wait time
+  function OrderSkeleton() {
+    return <div className="skeleton-card"><div className="skeleton-line" />...</div>;
+  }
+
+  // DON'T: Spinner gives no information about what's loading
+  function Loading() { return <Spinner />; }
+  ```
+
+**DON'T:**
+
+- Animate `width`, `height`, `top`, `left` -- animate `transform` and `opacity` (GPU-composited, no layout recalculation)
+- Use animations that last longer than 300ms for UI transitions (feels sluggish)
+- Add `will-change` to everything -- it consumes GPU memory. Apply only to animating elements
+- Ignore `prefers-reduced-motion` -- some users experience motion sickness
+
+## 6. Visual Design Principles
+
+**DO:** Apply systematic design decisions for consistent, professional interfaces.
+
+- Use a typographic scale (e.g., major third 1.25):
+  ```css
+  :root {
+    --font-xs: 0.64rem;    /* 10.24px */
+    --font-sm: 0.8rem;     /* 12.8px */
+    --font-base: 1rem;     /* 16px */
+    --font-lg: 1.25rem;    /* 20px */
+    --font-xl: 1.563rem;   /* 25px */
+    --font-2xl: 1.953rem;  /* 31.25px */
+  }
+  ```
+- Use a 4px/8px spacing grid:
+  ```css
+  :root {
+    --space-1: 0.25rem;  /* 4px */
+    --space-2: 0.5rem;   /* 8px */
+    --space-3: 0.75rem;  /* 12px */
+    --space-4: 1rem;     /* 16px */
+    --space-6: 1.5rem;   /* 24px */
+    --space-8: 2rem;     /* 32px */
+  }
+  ```
+- Use HSL-based color systems with semantic tokens:
+  ```css
+  :root {
+    /* Primitives */
+    --blue-500: hsl(220 90% 56%);
+    --red-500: hsl(0 84% 60%);
+
+    /* Semantic tokens */
+    --color-primary: var(--blue-500);
+    --color-danger: var(--red-500);
+    --color-text: hsl(220 20% 15%);
+    --color-text-muted: hsl(220 15% 50%);
+    --color-surface: hsl(0 0% 100%);
+    --color-border: hsl(220 15% 88%);
+  }
+  ```
+- Use a consistent elevation/shadow system:
+  ```css
+  :root {
+    --shadow-sm: 0 1px 2px hsl(0 0% 0% / 0.05);
+    --shadow-md: 0 4px 6px hsl(0 0% 0% / 0.07);
+    --shadow-lg: 0 10px 15px hsl(0 0% 0% / 0.1);
+    --shadow-xl: 0 20px 25px hsl(0 0% 0% / 0.15);
+  }
+  ```
+- Establish visual hierarchy through size, weight, and color -- not decoration:
+  ```css
+  .heading { font-size: var(--font-xl); font-weight: 700; color: var(--color-text); }
+  .subheading { font-size: var(--font-lg); font-weight: 500; color: var(--color-text); }
+  .body { font-size: var(--font-base); font-weight: 400; color: var(--color-text); }
+  .caption { font-size: var(--font-sm); font-weight: 400; color: var(--color-text-muted); }
+  ```
+
+**DON'T:**
+
+- Use arbitrary pixel values for spacing -- stick to the grid
+- Use more than 3 font sizes on a single screen (headings + body + caption)
+- Mix color definition methods (hex, rgb, hsl) -- pick one system
+- Use shadows for decoration -- shadows indicate elevation (interactive, floating, overlay)
+
+## 7. Design System Integration
+
+**DO:** Build a token-based system that scales across themes and components.
+
+- Use CSS custom properties for theming:
+  ```css
+  :root {
+    --color-bg: hsl(0 0% 100%);
+    --color-text: hsl(220 20% 15%);
+    --radius-md: 0.375rem;
+    --font-body: system-ui, -apple-system, sans-serif;
+  }
+  ```
+- Support dark mode via custom properties and media query:
+  ```css
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --color-bg: hsl(220 20% 10%);
+      --color-text: hsl(220 15% 85%);
+      --color-surface: hsl(220 20% 14%);
+      --color-border: hsl(220 15% 25%);
+    }
+  }
+
+  /* Manual toggle via data attribute */
+  [data-theme="dark"] {
+    --color-bg: hsl(220 20% 10%);
+    --color-text: hsl(220 15% 85%);
+  }
+  ```
+- Use component variants via data attributes or props:
+  ```css
+  /* Data attribute variants */
+  .button { padding: var(--space-2) var(--space-4); border-radius: var(--radius-md); }
+  .button[data-variant="primary"] { background: var(--color-primary); color: white; }
+  .button[data-variant="secondary"] { background: transparent; border: 1px solid var(--color-border); }
+  .button[data-size="sm"] { padding: var(--space-1) var(--space-2); font-size: var(--font-sm); }
+  ```
+- Use consistent naming across tokens and components:
+  ```
+  Tokens:       --color-primary, --space-4, --radius-md, --shadow-lg
+  Components:   Button, Card, Input (PascalCase)
+  Variants:     data-variant="primary", data-size="sm" (kebab-case values)
+  ```
+- Document component APIs -- props, variants, and usage examples should be clear from the component definition
+
+**DON'T:**
+
+- Hardcode colors or spacing values in components -- always reference tokens
+- Create one-off styles that don't fit the system -- either extend the system or use an existing token
+- Switch themes by overriding individual properties in JS -- toggle a class or data attribute on `<html>`
+- Mix multiple theming approaches (CSS-in-JS, CSS Modules, global CSS) in the same project without clear boundaries

package/assets/skills/java-patterns/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: java-patterns
+description: Idiomatic Java patterns including records, Spring Boot conventions, JPA/Hibernate, and common pitfalls
+stacks:
+  - java
+requires:
+  - coding-standards
+---
+
+# Java Patterns
+
+Idiomatic Java patterns for modern (17+) projects. Covers language features, Spring Boot conventions, JPA/Hibernate best practices, testing idioms, and common pitfalls. Apply these when writing, reviewing, or refactoring Java code.
+
+## 1. Modern Java Idioms
+
+**DO:** Use modern Java features to write concise, safe, and expressive code.
+
+- Use records for immutable data carriers:
+  ```java
+  // Record: immutable, equals/hashCode/toString auto-generated
+  public record UserDto(String name, String email, Instant createdAt) {}
+
+  // Use in APIs, DTOs, value objects -- not JPA entities
+  var user = new UserDto("Alice", "alice@example.com", Instant.now());
+  ```
+- Use sealed classes for restricted type hierarchies:
+  ```java
+  public sealed interface Shape permits Circle, Rectangle, Triangle {
+      double area();
+  }
+
+  public record Circle(double radius) implements Shape {
+      public double area() { return Math.PI * radius * radius; }
+  }
+  ```
+- Use Optional for nullable returns -- never for fields or parameters:
+  ```java
+  // DO: Chain operations safely
+  Optional<User> user = repository.findById(id);
+  String name = user.map(User::name).orElse("Anonymous");
+
+  // DO: Handle absence explicitly
+  return repository.findById(id)
+      .orElseThrow(() -> new UserNotFoundException(id));
+  ```
+- Use pattern matching with `instanceof`:
+  ```java
+  // DO: Pattern matching eliminates manual cast
+  if (shape instanceof Circle c) {
+      return Math.PI * c.radius() * c.radius();
+  }
+  ```
+- Use text blocks for multi-line strings:
+  ```java
+  String query = """
+      SELECT u.name, u.email
+      FROM users u
+      WHERE u.active = true
+      ORDER BY u.name
+      """;
+  ```
+
+**DON'T:**
+
+- Use `Optional.get()` without checking `isPresent()` -- use `orElse()`, `orElseThrow()`, or `map()`
+- Use Optional as a method parameter or field type -- it's for return values only
+- Return `null` from public methods when Optional is appropriate
+- Use raw types: `List` instead of `List<String>`
+- Use `instanceof` followed by a manual cast when pattern matching is available
+
+## 2. Spring Boot Patterns
+
+**DO:** Follow Spring Boot conventions for maintainable, testable applications.
+
+- Use constructor-based dependency injection -- never field injection:
+  ```java
+  // DO: Constructor injection (immutable, testable)
+  @Service
+  public class OrderService {
+      private final OrderRepository orderRepo;
+      private final PaymentGateway paymentGateway;
+
+      public OrderService(OrderRepository orderRepo, PaymentGateway paymentGateway) {
+          this.orderRepo = orderRepo;
+          this.paymentGateway = paymentGateway;
+      }
+  }
+  ```
+- Layer architecture: Controller -> Service -> Repository:
+  ```java
+  @RestController        // Thin: HTTP concerns only
+  @Service               // Business logic and orchestration
+  @Repository            // Data access only
+  ```
+- Place `@Transactional` on the service layer, not on repositories:
+  ```java
+  @Service
+  public class TransferService {
+      @Transactional
+      public void transfer(AccountId from, AccountId to, Money amount) {
+          accountRepo.debit(from, amount);
+          accountRepo.credit(to, amount);
+      }
+  }
+  ```
+- Use `@ConfigurationProperties` for type-safe configuration:
+  ```java
+  @ConfigurationProperties(prefix = "app.email")
+  public record EmailConfig(String host, int port, boolean useTls) {}
+  ```
+- Handle exceptions with `@ControllerAdvice`:
+  ```java
+  @ControllerAdvice
+  public class GlobalExceptionHandler {
+      @ExceptionHandler(UserNotFoundException.class)
+      public ResponseEntity<ErrorResponse> handleNotFound(UserNotFoundException ex) {
+          return ResponseEntity.status(404)
+              .body(new ErrorResponse(ex.getMessage()));
+      }
+  }
+  ```
+
+**DON'T:**
+
+- Use `@Autowired` on fields -- constructor injection is immutable and explicit
+- Put business logic in controllers -- controllers parse HTTP, services execute logic
+- Use `@Transactional` on repository methods -- Spring Data already wraps queries
+- Catch exceptions in controllers individually -- use `@ControllerAdvice` for centralized handling
+- Use Spring profiles for feature flags -- profiles are for environments (dev, staging, prod)
+
+## 3. JPA/Hibernate Conventions
+
+**DO:** Design entities carefully and be explicit about fetching behavior.
+
+- Mark IDs as immutable and use `@Version` for optimistic locking:
+  ```java
+  @Entity
+  public class Order {
+      @Id @GeneratedValue(strategy = GenerationType.UUID)
+      private UUID id;
+
+      @Version
+      private Long version;  // Optimistic locking -- prevents lost updates
+  }
+  ```
+- Default to lazy fetching, use explicit join fetch for read paths:
+  ```java
+  // DO: Lazy by default
+  @ManyToOne(fetch = FetchType.LAZY)
+  private Customer customer;
+
+  // DO: Explicit fetch when needed
+  @EntityGraph(attributePaths = {"customer", "items"})
+  Optional<Order> findWithDetailsById(UUID id);
+  ```
+- Prevent N+1 queries with `@EntityGraph` or `JOIN FETCH`:
+  ```java
+  // Repository method with join fetch
+  @Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.status = :status")
+  List<Order> findByStatusWithItems(@Param("status") OrderStatus status);
+  ```
+- Use DTOs for API responses, never expose entities directly:
+  ```java
+  // DO: Project to DTO
+  public record OrderSummary(UUID id, String customerName, BigDecimal total) {
+      public static OrderSummary from(Order order) {
+          return new OrderSummary(order.getId(), order.getCustomer().getName(), order.getTotal());
+      }
+  }
+  ```
+
+**DON'T:**
+
+- Use `FetchType.EAGER` on `@ManyToOne` or `@OneToMany` -- it causes unexpected extra queries
+- Return JPA entities from REST endpoints -- entities carry lazy proxies and hibernate state
+- Use `CascadeType.ALL` without thinking -- cascade delete can wipe related data unexpectedly
+- Call `entity.getCollection().size()` to check emptiness -- use a count query instead
+- Mutate entity state outside a `@Transactional` context -- changes won't persist or may throw
+
+## 4. Testing
+
+**DO:** Write focused tests that verify behavior, using the right test slice.
+
+- Use JUnit 5 `@Nested` for grouping related test scenarios:
+  ```java
+  class OrderServiceTest {
+      @Nested
+      class WhenOrderIsValid {
+          @Test
+          void shouldCalculateTotal() { ... }
+
+          @Test
+          void shouldApplyDiscount() { ... }
+      }
+
+      @Nested
+      class WhenOrderIsEmpty {
+          @Test
+          void shouldThrowValidationException() { ... }
+      }
+  }
+  ```
+- Use Mockito for isolating dependencies:
+  ```java
+  @ExtendWith(MockitoExtension.class)
+  class OrderServiceTest {
+      @Mock OrderRepository orderRepo;
+      @Mock PaymentGateway paymentGateway;
+      @InjectMocks OrderService service;
+
+      @Test
+      void shouldProcessPayment() {
+          when(paymentGateway.charge(any())).thenReturn(PaymentResult.success());
+          service.placeOrder(order);
+          verify(paymentGateway).charge(any());
+      }
+  }
+  ```
+- Use test slices instead of `@SpringBootTest` for faster tests:
+  ```java
+  @WebMvcTest(OrderController.class)    // Controller tests only
+  @DataJpaTest                          // Repository tests only
+  @JsonTest                             // JSON serialization tests only
+  ```
+- Use AssertJ for fluent, readable assertions:
+  ```java
+  assertThat(orders)
+      .hasSize(3)
+      .extracting(Order::status)
+      .containsExactly(PENDING, SHIPPED, DELIVERED);
+  ```
+
+**DON'T:**
+
+- Use `@SpringBootTest` for every test -- it loads the full application context (slow)
+- Mock everything -- test real behavior where possible, mock only external boundaries
+- Write tests that depend on database state from other tests -- each test should set up its own state
+- Use `assertEquals(expected, actual)` when AssertJ provides a more readable alternative
+
+## 5. Common Pitfalls
+
+**Pitfall: Mutable Date/Time**
+Use `java.time.*` exclusively. Never use `java.util.Date` or `java.util.Calendar` -- they are mutable and error-prone. Use `Instant` for timestamps, `LocalDate` for dates without time, `ZonedDateTime` for timezone-aware dates.
+
+**Pitfall: Checked Exceptions Overuse**
+Reserve checked exceptions for truly recoverable conditions that the caller MUST handle (e.g., `IOException` when writing to disk). Use unchecked exceptions (`RuntimeException` subclasses) for programming errors and business rule violations.
+
+**Pitfall: Null Returns**
+Return `Optional<T>` from methods that may not produce a value. For collections, return empty collections instead of `null`. Use `@Nullable` annotations from `jakarta.annotation` when Optional is not appropriate (e.g., record fields).
+
+**Pitfall: `==` vs `.equals()` for Objects**
+`==` compares references, `.equals()` compares values. Always use `.equals()` for `String`, `Integer`, `BigDecimal`, and all objects. Exception: enum values can use `==` because enums are singletons.
+
+**Pitfall: Raw Types**
+Always specify generic type parameters. `List` instead of `List<String>` bypasses compile-time type safety and can cause `ClassCastException` at runtime.
+
+**Pitfall: Synchronized Blocks in Spring Beans**
+Spring beans are singletons by default. Using `synchronized` on a bean method serializes all requests through that method. Use `@Async`, message queues, or database-level locking instead of in-process synchronization for concurrent request handling.