@chankov/agent-skills 0.3.0 → 0.3.3

package/.versions/0.3.3/hooks/simplify-ignore.sh

@@ -0,0 +1,302 @@
+#!/bin/bash
+# simplify-ignore.sh — Hook for Read (PreToolUse), Edit|Write (PostToolUse), Stop
+#
+# PreToolUse Read   → backs up file, replaces blocks with BLOCK_<hash> in-place
+# PostToolUse Edit  → expands placeholders, re-filters so file stays hidden
+# PostToolUse Write → expands placeholders, re-filters so file stays hidden
+# Stop              → restores real file content from backup
+#
+# The file on disk ALWAYS has placeholders while the session is active.
+# The real content (with model's changes applied) lives in the backup.
+#
+# Dependencies: jq, shasum or sha1sum (auto-detected)
+
+set -euo pipefail
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf '%s\n' "error: missing jq" >&2; exit 1
+fi
+
+CACHE="${CLAUDE_PROJECT_DIR:-.}/.claude/.simplify-ignore-cache"
+if [ -t 0 ]; then INPUT="{}"; else INPUT=$(cat); fi
+
+# Parse hook input — trap errors explicitly so set -e doesn't cause
+# a silent exit on malformed JSON, and surface a useful diagnostic.
+parse_error=""
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null) || {
+  parse_error="failed to parse .tool_name from hook input"
+  TOOL_NAME=""
+}
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null) || {
+  parse_error="failed to parse .tool_input.file_path from hook input"
+  FILE_PATH=""
+}
+if [ -n "$parse_error" ]; then
+  printf 'Warning: %s (input: %.120s)\n' "$parse_error" "$INPUT" >&2
+fi
+
+hash_cmd() {
+  if command -v shasum >/dev/null 2>&1; then shasum
+  elif command -v sha1sum >/dev/null 2>&1; then sha1sum
+  else printf '%s\n' "error: missing shasum or sha1sum" >&2; exit 1; fi
+}
+file_id() { printf '%s' "$1" | hash_cmd | cut -c1-16; }
+block_hash() { printf '%s' "$1" | hash_cmd | cut -c1-8; }
+# Escape glob metacharacters so ${var/pattern/repl} treats pattern as literal.
+# Needed for Bash 3.2 (macOS) where quotes don't suppress globbing in PE patterns.
+escape_glob() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\*/\\*}"
+  s="${s//\?/\\?}"
+  s="${s//\[/\\[}"
+  printf '%s' "$s"
+}
+
+# ── filter_file: replace simplify-ignore blocks with BLOCK_<hash> placeholders ─
+# Reads $1 (source), writes filtered version to $2 (dest), saves blocks to cache.
+# Returns 0 if blocks were found, 1 if none.
+filter_file() {
+  local src="$1" dest="$2" fid="$3"
+  : > "$dest"
+  rm -f "$CACHE/${fid}".block.* "$CACHE/${fid}".reason.* "$CACHE/${fid}".prefix.* "$CACHE/${fid}".suffix.*
+
+  local count=0 in_block=0 buf="" reason="" prefix="" suffix=""
+
+  while IFS= read -r line || [ -n "$line" ]; do
+    # Check for start marker (no fork — uses bash case)
+    if [ $in_block -eq 0 ]; then
+      case "$line" in *simplify-ignore-start*)
+        in_block=1
+        buf="$line"
+        # Extract comment prefix/suffix to preserve language-appropriate syntax
+        prefix="${line%%simplify-ignore-start*}"
+        suffix=""
+        case "$line" in *'*/'*) suffix=" */" ;; *'-->'*) suffix=" -->" ;; esac
+        reason=$(printf '%s' "$line" | sed -n 's/.*simplify-ignore-start:[[:space:]]*//p' \
+          | sed 's/[[:space:]]*\*\/.*$//' | sed 's/[[:space:]]*-->.*$//' | sed 's/[[:space:]]*$//')
+        # Handle single-line block (start + end on same line)
+        case "$line" in *simplify-ignore-end*)
+          in_block=0
+          # Write single-line block immediately and skip to next line
+          # to avoid the end-marker check below firing again
+          local h; h=$(block_hash "$buf")
+          count=$((count + 1))
+          printf '%s' "$buf" > "$CACHE/${fid}.block.${h}"
+          [ -n "$reason" ] && printf '%s' "$reason" > "$CACHE/${fid}.reason.${h}"
+          printf '%s' "$prefix" > "$CACHE/${fid}.prefix.${h}"
+          printf '%s' "$suffix" > "$CACHE/${fid}.suffix.${h}"
+          if [ -n "$reason" ]; then
+            printf '%s\n' "${prefix}BLOCK_${h}: ${reason}${suffix}" >> "$dest"
+          else
+            printf '%s\n' "${prefix}BLOCK_${h}${suffix}" >> "$dest"
+          fi
+          buf=""; reason=""; prefix=""; suffix=""
+          continue
+          ;; *)
+          continue
+          ;;
+        esac
+      ;; esac
+    fi
+    # Accumulate block content
+    if [ $in_block -eq 1 ]; then
+      buf="${buf}
+${line}"
+    fi
+    # Check for end marker
+    case "$line" in *simplify-ignore-end*)
+      if [ $in_block -eq 1 ]; then
+        local h; h=$(block_hash "$buf")
+        count=$((count + 1))
+        printf '%s' "$buf" > "$CACHE/${fid}.block.${h}"
+        [ -n "$reason" ] && printf '%s' "$reason" > "$CACHE/${fid}.reason.${h}"
+        printf '%s' "$prefix" > "$CACHE/${fid}.prefix.${h}"
+        printf '%s' "$suffix" > "$CACHE/${fid}.suffix.${h}"
+        if [ -n "$reason" ]; then
+          printf '%s\n' "${prefix}BLOCK_${h}: ${reason}${suffix}" >> "$dest"
+        else
+          printf '%s\n' "${prefix}BLOCK_${h}${suffix}" >> "$dest"
+        fi
+        in_block=0; buf=""; reason=""; prefix=""; suffix=""
+        continue
+      fi
+      ;;
+    esac
+    [ $in_block -eq 0 ] && printf '%s\n' "$line" >> "$dest"
+  done < "$src"
+
+  # Unclosed block → flush as-is
+  if [ $in_block -eq 1 ] && [ -n "$buf" ]; then
+    printf 'Warning: unclosed simplify-ignore-start in %s (block not hidden)\n' "$src" >&2
+    printf '%s\n' "$buf" >> "$dest"
+  fi
+
+  # Preserve trailing newline status of source
+  if [ -s "$dest" ] && [ -s "$src" ] && [ -n "$(tail -c 1 "$src")" ]; then
+    perl -pe 'chomp if eof' "$dest" > "${dest}.nnl" && \
+      cat "${dest}.nnl" > "$dest" && rm -f "${dest}.nnl"
+  fi
+
+  [ $count -gt 0 ] && return 0 || return 1
+}
+
+# ── Stop: restore all files from backup ───────────────────────────────────────
+if [ -z "$TOOL_NAME" ]; then
+  [ -d "$CACHE" ] || exit 0
+  for bak in "$CACHE"/*.bak; do
+    [ -f "$bak" ] || continue
+    fid="${bak##*/}"; fid="${fid%.bak}"
+    pathfile="$CACHE/${fid}.path"
+    [ -f "$pathfile" ] || { rm -f "$bak"; continue; }
+    orig=$(cat "$pathfile")
+    if [ -f "$orig" ]; then
+      cat "$bak" > "$orig"
+      rm -f "$bak" "$pathfile" "$CACHE/${fid}".block.* "$CACHE/${fid}".reason.* "$CACHE/${fid}".prefix.* "$CACHE/${fid}".suffix.*
+      rmdir "$CACHE/${fid}.lock" 2>/dev/null
+    else
+      # File was moved/deleted — save backup as .recovered, don't destroy it
+      mkdir -p "$(dirname "${orig}.recovered")"
+      mv "$bak" "${orig}.recovered"
+      rm -f "$pathfile" "$CACHE/${fid}".block.* "$CACHE/${fid}".reason.* "$CACHE/${fid}".prefix.* "$CACHE/${fid}".suffix.*
+      rmdir "$CACHE/${fid}.lock" 2>/dev/null
+      printf 'Warning: %s was moved/deleted. Recovered original to %s.recovered\n' "$orig" "$orig" >&2
+    fi
+  done
+  # Clean orphan locks (created but crash before backup)
+  for lockdir in "$CACHE"/*.lock; do
+    [ -d "$lockdir" ] || continue
+    rmdir "$lockdir" 2>/dev/null
+  done
+  exit 0
+fi
+
+[ -z "$FILE_PATH" ] && exit 0
+
+# ── PreToolUse Read: filter in-place ──────────────────────────────────────────
+if [ "$TOOL_NAME" = "Read" ]; then
+  [ -f "$FILE_PATH" ] || exit 0
+  case "$(basename "$FILE_PATH")" in simplify-ignore*|SIMPLIFY-IGNORE*) exit 0 ;; esac
+
+  mkdir -p "$CACHE"
+  ID=$(file_id "$FILE_PATH")
+
+  # If backup exists, file is already filtered — skip
+  [ -f "$CACHE/${ID}.bak" ] && exit 0
+
+  grep -q 'simplify-ignore-start' -- "$FILE_PATH" || exit 0
+
+  # Atomic lock: mkdir fails if another session races us
+  if ! mkdir "$CACHE/${ID}.lock" 2>/dev/null; then
+    # Lock exists — reclaim only if stale (>60s old, no backup = crash leftover)
+    if [ ! -f "$CACHE/${ID}.bak" ] && \
+       [ -n "$(find "$CACHE/${ID}.lock" -maxdepth 0 -mmin +1 2>/dev/null)" ]; then
+      rmdir "$CACHE/${ID}.lock" 2>/dev/null || true
+      mkdir "$CACHE/${ID}.lock" 2>/dev/null || exit 0
+    else
+      exit 0
+    fi
+  fi
+
+  # Back up the original (preserve trailing newline status)
+  cp -p "$FILE_PATH" "$CACHE/${ID}.bak" 2>/dev/null || cp "$FILE_PATH" "$CACHE/${ID}.bak"
+  printf '%s' "$FILE_PATH" > "$CACHE/${ID}.path"
+
+  # Filter in-place (cat > preserves inode and permissions)
+  FILTERED="$CACHE/${ID}.$$.tmp"
+  rm -f "$FILTERED"
+  if filter_file "$FILE_PATH" "$FILTERED" "$ID"; then
+    cat "$FILTERED" > "$FILE_PATH"
+    rm -f "$FILTERED"
+  else
+    rm -f "$FILTERED" "$CACHE/${ID}.bak" "$CACHE/${ID}.path"
+    rmdir "$CACHE/${ID}.lock" 2>/dev/null
+  fi
+  exit 0
+fi
+
+# ── PostToolUse Edit|Write: expand, then re-filter ────────────────────────────
+if [ "$TOOL_NAME" = "Edit" ] || [ "$TOOL_NAME" = "Write" ]; then
+  ID=$(file_id "$FILE_PATH")
+  [ -f "$CACHE/${ID}.bak" ] || exit 0
+  ls "$CACHE/${ID}".block.* >/dev/null 2>&1 || exit 0
+
+  # Expand placeholders, preserving any inline code the model added around them
+  EXPANDED="$CACHE/${ID}.$$.expanded"
+  rm -f "$EXPANDED"
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in *BLOCK_*)
+      # Expand all placeholders on this line (supports multiple per line)
+      for bf in "$CACHE/${ID}".block.*; do
+        [ -f "$bf" ] || continue
+        h="${bf##*.}"
+        case "$line" in *"BLOCK_${h}"*)
+          # Reconstruct the exact placeholder pattern
+          bp=""; bs=""; br=""
+          [ -f "$CACHE/${ID}.prefix.${h}" ] && bp=$(cat "$CACHE/${ID}.prefix.${h}")
+          [ -f "$CACHE/${ID}.suffix.${h}" ] && bs=$(cat "$CACHE/${ID}.suffix.${h}")
+          [ -f "$CACHE/${ID}.reason.${h}" ] && br=$(cat "$CACHE/${ID}.reason.${h}")
+          if [ -n "$br" ]; then
+            placeholder="${bp}BLOCK_${h}: ${br}${bs}"
+          else
+            placeholder="${bp}BLOCK_${h}${bs}"
+          fi
+          block_content=$(cat "$bf"; printf x); block_content="${block_content%x}"
+          # Escape glob metacharacters (* ? [ \) in the pattern
+          esc_placeholder=$(escape_glob "$placeholder")
+          # Bash native substitution (// = global replace): replace placeholder, keep surrounding code
+          line="${line//$esc_placeholder/$block_content}"
+          # Fallback: if model altered the reason text, try without reason
+          # (only trigger if BLOCK_hash is still present AND wasn't in the original block content)
+          case "$block_content" in *"BLOCK_${h}"*) ;; *)
+            case "$line" in *"BLOCK_${h}"*)
+              printf 'Warning: placeholder BLOCK_%s was modified by model, using fuzzy match\n' "$h" >&2
+              esc_fuzzy=$(escape_glob "${bp}BLOCK_${h}${bs}")
+              line="${line//$esc_fuzzy/$block_content}"
+              # Last resort: match just the hash token
+              case "$line" in *"BLOCK_${h}"*)
+                line="${line//BLOCK_${h}/$block_content}"
+              ;; esac
+            ;; esac
+          ;; esac
+        ;; esac
+      done
+    ;; esac
+    printf '%s\n' "$line" >> "$EXPANDED"
+  done < "$FILE_PATH"
+  # Preserve trailing newline status
+  if [ -s "$EXPANDED" ] && [ -s "$FILE_PATH" ] && [ -n "$(tail -c 1 "$FILE_PATH")" ]; then
+    perl -pe 'chomp if eof' "$EXPANDED" > "${EXPANDED}.nnl" && \
+      cat "${EXPANDED}.nnl" > "$EXPANDED" && rm -f "${EXPANDED}.nnl"
+  fi
+  # Warn if model deleted a protected block entirely
+  for bf in "$CACHE/${ID}".block.*; do
+    [ -f "$bf" ] || continue
+    bh="${bf##*.}"
+    # After expansion, blocks appear as original code (simplify-ignore-start).
+    # If neither the expanded code nor the placeholder is in EXPANDED, it was deleted.
+    if ! grep -qF "BLOCK_${bh}" "$EXPANDED" 2>/dev/null; then
+      # Get first line of block to check if it was expanded back
+      first_line=$(head -1 "$bf")
+      if ! grep -qF "$first_line" "$EXPANDED" 2>/dev/null; then
+        printf 'Warning: protected block BLOCK_%s was deleted by model\n' "$bh" >&2
+      fi
+    fi
+  done
+  # Preserve inode and permissions
+  cat "$EXPANDED" > "$FILE_PATH"
+  rm -f "$EXPANDED"
+
+  # Save expanded version as new backup (this is the "real" file with model's changes)
+  cp "$FILE_PATH" "$CACHE/${ID}.bak"
+
+  # Re-filter in-place so the file on disk stays with placeholders
+  FILTERED="$CACHE/${ID}.$$.tmp"
+  rm -f "$FILTERED"
+  if filter_file "$FILE_PATH" "$FILTERED" "$ID"; then
+    cat "$FILTERED" > "$FILE_PATH"
+    rm -f "$FILTERED"
+  fi
+
+  exit 0
+fi

package/.versions/0.3.3/references/accessibility-checklist.md

@@ -0,0 +1,159 @@
+# Accessibility Checklist
+
+Quick reference for WCAG 2.1 AA compliance. Use alongside the `frontend-ui-engineering` skill.
+
+## Table of Contents
+
+- [Essential Checks](#essential-checks)
+- [Common HTML Patterns](#common-html-patterns)
+- [Testing Tools](#testing-tools)
+- [Quick Reference: ARIA Live Regions](#quick-reference-aria-live-regions)
+- [Common Anti-Patterns](#common-anti-patterns)
+
+## Essential Checks
+
+### Keyboard Navigation
+- [ ] All interactive elements focusable via Tab key
+- [ ] Focus order follows visual/logical order
+- [ ] Focus is visible (outline/ring on focused elements)
+- [ ] Custom widgets have keyboard support (Enter to activate, Escape to close)
+- [ ] No keyboard traps (user can always Tab away from a component)
+- [ ] Skip-to-content link at top of page
+- [ ] Modals trap focus while open, return focus on close
+
+### Screen Readers
+- [ ] All images have `alt` text (or `alt=""` for decorative images)
+- [ ] All form inputs have associated labels (`<label>` or `aria-label`)
+- [ ] Buttons and links have descriptive text (not "Click here")
+- [ ] Icon-only buttons have `aria-label`
+- [ ] Page has one `<h1>` and headings don't skip levels
+- [ ] Dynamic content changes announced (`aria-live` regions)
+- [ ] Tables have `<th>` headers with scope
+
+### Visual
+- [ ] Text contrast ≥ 4.5:1 (normal text) or ≥ 3:1 (large text, 18px+)
+- [ ] UI components contrast ≥ 3:1 against background
+- [ ] Color is not the only way to convey information
+- [ ] Text resizable to 200% without breaking layout
+- [ ] No content that flashes more than 3 times per second
+
+### Forms
+- [ ] Every input has a visible label
+- [ ] Required fields indicated (not by color alone)
+- [ ] Error messages specific and associated with the field
+- [ ] Error state visible by more than color (icon, text, border)
+- [ ] Form submission errors summarized and focusable
+
+### Content
+- [ ] Language declared (`<html lang="en">`)
+- [ ] Page has a descriptive `<title>`
+- [ ] Links distinguish from surrounding text (not by color alone)
+- [ ] Touch targets ≥ 44x44px on mobile
+- [ ] Meaningful empty states (not blank screens)
+
+## Common HTML Patterns
+
+### Buttons vs. Links
+
+```html
+<!-- Use <button> for actions -->
+<button onClick={handleDelete}>Delete Task</button>
+
+<!-- Use <a> for navigation -->
+<a href="/tasks/123">View Task</a>
+
+<!-- NEVER use div/span as buttons -->
+<div onClick={handleDelete}>Delete</div>  <!-- BAD -->
+```
+
+### Form Labels
+
+```html
+<!-- Explicit label association -->
+<label htmlFor="email">Email address</label>
+<input id="email" type="email" required />
+
+<!-- Implicit wrapping -->
+<label>
+  Email address
+  <input type="email" required />
+</label>
+
+<!-- Hidden label (visible label preferred) -->
+<input type="search" aria-label="Search tasks" />
+```
+
+### ARIA Roles
+
+```html
+<!-- Navigation -->
+<nav aria-label="Main navigation">...</nav>
+<nav aria-label="Footer links">...</nav>
+
+<!-- Status messages -->
+<div role="status" aria-live="polite">Task saved</div>
+
+<!-- Alert messages -->
+<div role="alert">Error: Title is required</div>
+
+<!-- Modal dialogs -->
+<dialog aria-modal="true" aria-labelledby="dialog-title">
+  <h2 id="dialog-title">Confirm Delete</h2>
+  ...
+</dialog>
+
+<!-- Loading states -->
+<div aria-busy="true" aria-label="Loading tasks">
+  <Spinner />
+</div>
+```
+
+### Accessible Lists
+
+```html
+<ul role="list" aria-label="Tasks">
+  <li>
+    <input type="checkbox" id="task-1" aria-label="Complete: Buy groceries" />
+    <label htmlFor="task-1">Buy groceries</label>
+  </li>
+</ul>
+```
+
+## Testing Tools
+
+```bash
+# Automated audit
+npx axe-core          # Programmatic accessibility testing
+npx pa11y             # CLI accessibility checker
+
+# In browser
+# Chrome DevTools → Lighthouse → Accessibility
+# Chrome DevTools → Elements → Accessibility tree
+
+# Screen reader testing
+# macOS: VoiceOver (Cmd + F5)
+# Windows: NVDA (free) or JAWS
+# Linux: Orca
+```
+
+## Quick Reference: ARIA Live Regions
+
+| Value | Behavior | Use For |
+|-------|----------|---------|
+| `aria-live="polite"` | Announced at next pause | Status updates, saved confirmations |
+| `aria-live="assertive"` | Announced immediately | Errors, time-sensitive alerts |
+| `role="status"` | Same as `polite` | Status messages |
+| `role="alert"` | Same as `assertive` | Error messages |
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| `div` as button | Not focusable, no keyboard support | Use `<button>` |
+| Missing `alt` text | Images invisible to screen readers | Add descriptive `alt` |
+| Color-only states | Invisible to color-blind users | Add icons, text, or patterns |
+| Autoplaying media | Disorienting, can't be stopped | Add controls, don't autoplay |
+| Custom dropdown with no ARIA | Unusable by keyboard/screen reader | Use native `<select>` or proper ARIA listbox |
+| Removing focus outlines | Users can't see where they are | Style outlines, don't remove them |
+| Empty links/buttons | "Link" announced with no description | Add text or `aria-label` |
+| `tabindex > 0` | Breaks natural tab order | Use `tabindex="0"` or `-1` only |

package/.versions/0.3.3/references/performance-checklist.md

@@ -0,0 +1,121 @@
+# Performance Checklist
+
+Quick reference checklist for web application performance. Use alongside the `performance-optimization` skill.
+
+## Table of Contents
+
+- [Core Web Vitals Targets](#core-web-vitals-targets)
+- [Frontend Checklist](#frontend-checklist)
+- [Backend Checklist](#backend-checklist)
+- [Measurement Commands](#measurement-commands)
+- [Common Anti-Patterns](#common-anti-patterns)
+
+## Core Web Vitals Targets
+
+| Metric | Good | Needs Work | Poor |
+|--------|------|------------|------|
+| LCP (Largest Contentful Paint) | ≤ 2.5s | ≤ 4.0s | > 4.0s |
+| INP (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms | > 500ms |
+| CLS (Cumulative Layout Shift) | ≤ 0.1 | ≤ 0.25 | > 0.25 |
+
+## TTFB Diagnosis
+
+When TTFB is slow (> 800ms), check each component in DevTools Network waterfall:
+
+- [ ] **DNS resolution** slow → add `<link rel="dns-prefetch">` or `<link rel="preconnect">` for known origins
+- [ ] **TCP/TLS handshake** slow → enable HTTP/2, consider edge deployment, verify keep-alive
+- [ ] **Server processing** slow → profile backend, check slow queries, add caching
+
+## Frontend Checklist
+
+### Images
+- [ ] Images use modern formats (WebP, AVIF)
+- [ ] Images are responsively sized (`srcset` and `sizes`)
+- [ ] Images and `<source>` elements have explicit `width` and `height` (prevents CLS in art direction)
+- [ ] Below-the-fold images use `loading="lazy"` and `decoding="async"`
+- [ ] Hero/LCP images use `fetchpriority="high"` and no lazy loading
+
+### JavaScript
+- [ ] Bundle size under 200KB gzipped (initial load)
+- [ ] Code splitting with dynamic `import()` for routes and heavy features
+- [ ] Tree shaking enabled (verify dependency ships ESM and marks `sideEffects: false`)
+- [ ] No blocking JavaScript in `<head>` (use `defer` or `async`)
+- [ ] Heavy computation offloaded to Web Workers (if applicable)
+- [ ] `React.memo()` on expensive components that re-render with same props
+- [ ] `useMemo()` / `useCallback()` only where profiling shows benefit
+
+### CSS
+- [ ] Critical CSS inlined or preloaded
+- [ ] No render-blocking CSS for non-critical styles
+- [ ] No CSS-in-JS runtime cost in production (use extraction)
+- [ ] Font display strategy set (`font-display: swap` or `optional`)
+- [ ] System font stack considered before custom fonts
+
+### Network
+- [ ] Static assets cached with long `max-age` + content hashing
+- [ ] API responses cached where appropriate (`Cache-Control`)
+- [ ] HTTP/2 or HTTP/3 enabled
+- [ ] Resources preconnected (`<link rel="preconnect">`) for known origins
+- [ ] No unnecessary redirects
+
+### Rendering
+- [ ] No layout thrashing (forced synchronous layouts)
+- [ ] Animations use `transform` and `opacity` (GPU-accelerated)
+- [ ] Long lists use virtualization (e.g., `react-window`)
+- [ ] No unnecessary full-page re-renders
+
+## Backend Checklist
+
+### Database
+- [ ] No N+1 query patterns (use eager loading / joins)
+- [ ] Queries have appropriate indexes
+- [ ] List endpoints paginated (never `SELECT * FROM table`)
+- [ ] Connection pooling configured
+- [ ] Slow query logging enabled
+
+### API
+- [ ] Response times < 200ms (p95)
+- [ ] No synchronous heavy computation in request handlers
+- [ ] Bulk operations instead of loops of individual calls
+- [ ] Response compression (gzip/brotli)
+- [ ] Appropriate caching (in-memory, Redis, CDN)
+
+### Infrastructure
+- [ ] CDN for static assets
+- [ ] Server located close to users (or edge deployment)
+- [ ] Horizontal scaling configured (if needed)
+- [ ] Health check endpoint for load balancer
+
+## Measurement Commands
+
+```bash
+# Lighthouse CLI
+npx lighthouse https://localhost:3000 --output json --output-path ./report.json
+
+# Bundle analysis
+npx webpack-bundle-analyzer stats.json
+# or for Vite:
+npx vite-bundle-visualizer
+
+# Check bundle size
+npx bundlesize
+
+# Web Vitals in code
+import { onLCP, onINP, onCLS } from 'web-vitals';
+onLCP(console.log);
+onINP(console.log);
+onCLS(console.log);
+```
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Impact | Fix |
+|---|---|---|
+| N+1 queries | Linear DB load growth | Use joins, includes, or batch loading |
+| Unbounded queries | Memory exhaustion, timeouts | Always paginate, add LIMIT |
+| Missing indexes | Slow reads as data grows | Add indexes for filtered/sorted columns |
+| Layout thrashing | Jank, dropped frames | Batch DOM reads, then batch writes |
+| Unoptimized images | Slow LCP, wasted bandwidth | Use WebP, responsive sizes, lazy load |
+| Large bundles | Slow Time to Interactive | Code split, tree shake, audit deps |
+| Blocking main thread | Poor INP, unresponsive UI | Use Web Workers, defer work |
+| Memory leaks | Growing memory, eventual crash | Clean up listeners, intervals, refs |