feat: Add 5 skills, 3 hooks, 3 output styles (v2.0.0)

New skills: migrate-ops, refactor-ops, scaffold, perf-ops, log-ops
New hooks: pre-commit-lint, post-edit-format, dangerous-cmd-warn
New output styles: spartan, mentor, executive

Updated catalogs, plugin.json (v2.0.0), README, AGENTS.md, PLAN.md.
Total: 22 agents, 64 skills, 4 output styles, 3 hooks.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-mods",
-  "version": "1.9.0",
-  "description": "Custom commands, skills, and agents for Claude Code - session continuity, 22 expert agents, 59 skills, 3 commands, 5 rules, modern CLI tools",
+  "version": "2.0.0",
+  "description": "Custom commands, skills, and agents for Claude Code - session continuity, 22 expert agents, 65 skills, 3 commands, 5 rules, 3 hooks, 4 output styles, modern CLI tools",
   "author": "0xDarkMatter",
   "repository": "https://github.com/0xDarkMatter/claude-mods",
   "license": "MIT",
@@ -71,10 +71,13 @@
       "skills/introspect",
       "skills/javascript-ops",
       "skills/laravel-ops",
+      "skills/log-ops",
       "skills/markitdown",
       "skills/mcp-ops",
+      "skills/migrate-ops",
       "skills/monitoring-ops",
       "skills/nginx-ops",
+      "skills/perf-ops",
       "skills/postgres-ops",
       "skills/project-planner",
       "skills/python-async-ops",
@@ -86,9 +89,11 @@
       "skills/python-pytest-ops",
       "skills/python-typing-ops",
       "skills/react-ops",
+      "skills/refactor-ops",
       "skills/rest-ops",
       "skills/review",
       "skills/rust-ops",
+      "skills/scaffold",
       "skills/screenshot",
       "skills/security-ops",
       "skills/setperms",
@@ -114,8 +119,16 @@
       "rules/skill-agent-updates.md",
       "rules/thinking.md"
     ],
+    "hooks": [
+      "hooks/pre-commit-lint.sh",
+      "hooks/post-edit-format.sh",
+      "hooks/dangerous-cmd-warn.sh"
+    ],
     "output-styles": [
-      "output-styles/vesper.md"
+      "output-styles/vesper.md",
+      "output-styles/spartan.md",
+      "output-styles/mentor.md",
+      "output-styles/executive.md"
     ]
   },
   "categories": [

AGENTS.md

@@ -5,8 +5,9 @@
 This is **claude-mods** - a collection of custom extensions for Claude Code:
 - **22 expert agents** for specialized domains (React, Python, Go, Rust, AWS, etc.)
 - **3 commands** for session management (/sync, /save) and experimental features (/canvas)
-- **59 skills** for CLI tools, patterns, workflows, and development tasks
-- **Custom output styles** for response personality (e.g., Vesper)
+- **64 skills** for CLI tools, patterns, workflows, and development tasks
+- **4 output styles** for response personality (Vesper, Spartan, Mentor, Executive)
+- **3 hooks** for pre-commit linting, post-edit formatting, and dangerous command warnings
 
 ## Installation
 
@@ -30,8 +31,8 @@ cd claude-mods && ./scripts/install.sh  # or .\scripts\install.ps1 on Windows
 | `agents/` | Expert subagent prompts (.md files) |
 | `commands/` | Slash command definitions |
 | `skills/` | Skill definitions with SKILL.md |
-| `output-styles/` | Response personalities (vesper.md) |
-| `hooks/` | Hook examples (pre/post execution) |
+| `output-styles/` | Response personalities (vesper, spartan, mentor, executive) |
+| `hooks/` | Working hook scripts (lint, format, safety) |
 | `rules/` | Claude Code rules (5 files: cli-tools, thinking, commit-style, naming-conventions, skill-agent-updates) |
 | `tools/` | Modern CLI toolkit documentation |
 | `tests/` | Validation scripts + justfile |

docs/PLAN.md

@@ -3,7 +3,7 @@
 **Goal**: A centralized repository of custom Claude Code commands, agents, and skills that enhance Claude Code's native capabilities with persistent session state, specialized expert agents, and streamlined workflows.
 
 **Created**: 2025-11-27
-**Last Updated**: 2026-01-24
+**Last Updated**: 2026-03-09
 **Status**: Active Development
 
 ---
@@ -13,11 +13,11 @@
 | Component | Count | Notes |
 |-----------|-------|-------|
 | Agents | 22 | Domain experts (Python, Go, Rust, React, etc.) |
-| Skills | 59 | Operational skills, CLI tools, workflows, dev tasks |
+| Skills | 64 | Operational skills, CLI tools, workflows, dev tasks |
 | Commands | 3 | Session management (sync, save) + experimental (canvas) |
 | Rules | 5 | CLI tools, thinking, commit style, naming, skill-agent-updates |
-| Output Styles | 1 | Vesper personality |
-| Hooks | 0 | Config examples only |
+| Output Styles | 4 | Vesper, Spartan, Mentor, Executive |
+| Hooks | 3 | pre-commit-lint, post-edit-format, dangerous-cmd-warn |
 
 ---
 
@@ -170,9 +170,18 @@ Most commands have been converted to skills for better discovery and on-demand l
 
 - [x] Create `rules/commit-style.md`
 - [x] Create `rules/naming-conventions.md`
-- [ ] Create Spartan output style
+- [x] Create Spartan output style
+- [x] Create Mentor output style
+- [x] Create Executive output style
+- [x] Add `debug-ops` skill (systematic debugging workflow)
+- [x] Add 3 hook implementations (lint, format, safety)
+- [x] Add `migrate-ops` skill (framework/language upgrades)
+- [x] Add `refactor-ops` skill (safe refactoring patterns)
+- [x] Add `scaffold` skill (project scaffolding)
+- [x] Add `perf-ops` skill (performance profiling)
+- [x] Add `log-ops` skill (JSONL/log analysis)
 - [ ] Add docker-expert agent
-- [ ] Add `/debug` skill (systematic debugging workflow)
+- [ ] Install lnav on Windows for log analysis
 
 ---
 
@@ -190,4 +199,4 @@ Most commands have been converted to skills for better discovery and on-demand l
 
 ---
 
-*Plan managed by `/save` command. Last updated: 2026-01-24*
+*Plan managed by `/save` command. Last updated: 2026-03-09*

hooks/README.md

@@ -2,6 +2,14 @@
 
 Claude Code hooks allow you to run custom scripts at key workflow points.
 
+## Available Hooks
+
+| Hook Script | Type | Purpose |
+|-------------|------|---------|
+| `pre-commit-lint.sh` | PreToolUse | Auto-lint staged files before commit (JS/TS, Python, Go, Rust, PHP) |
+| `post-edit-format.sh` | PostToolUse | Auto-format files after Write/Edit (Prettier, Ruff, gofmt, rustfmt) |
+| `dangerous-cmd-warn.sh` | PreToolUse | Block destructive commands (force push, rm -rf, DROP TABLE, etc.) |
+
 ## Configuration
 
 Add hooks to `.claude/settings.json` or `.claude/settings.local.json`:
@@ -12,13 +20,16 @@ Add hooks to `.claude/settings.json` or `.claude/settings.local.json`:
     "PreToolUse": [
       {
         "matcher": "Bash",
-        "hooks": ["bash hooks/security-check.sh $TOOL_INPUT"]
+        "hooks": [
+          "bash hooks/dangerous-cmd-warn.sh $TOOL_INPUT",
+          "bash hooks/pre-commit-lint.sh $TOOL_INPUT"
+        ]
       }
     ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",
-        "hooks": ["bash hooks/post-edit.sh $FILE_PATH"]
+        "hooks": ["bash hooks/post-edit-format.sh $FILE_PATH"]
       }
     ]
   }

hooks/dangerous-cmd-warn.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# hooks/dangerous-cmd-warn.sh
+# PreToolUse hook - warns before destructive or irreversible commands
+# Matcher: Bash
+#
+# Configuration in .claude/settings.json:
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": ["bash hooks/dangerous-cmd-warn.sh $TOOL_INPUT"]
+#     }]
+#   }
+# }
+#
+# Exit codes:
+#   0 = allow (safe or not matched)
+#   2 = block with message (dangerous command detected)
+
+INPUT="$1"
+
+if [[ -z "$INPUT" ]]; then
+  exit 0
+fi
+
+# -------------------------------------------------------------------
+# Dangerous patterns and their risk descriptions
+# -------------------------------------------------------------------
+
+declare -A PATTERNS
+
+# Git destructive operations
+PATTERNS["git\s+push\s+.*--force"]="Force push can overwrite remote history and lose others' commits"
+PATTERNS["git\s+push\s+-f\b"]="Force push can overwrite remote history and lose others' commits"
+PATTERNS["git\s+reset\s+--hard"]="Hard reset discards all uncommitted changes permanently"
+PATTERNS["git\s+clean\s+-f"]="git clean -f permanently deletes untracked files"
+PATTERNS["git\s+checkout\s+--\s+\."]="Discards all unstaged changes in working directory"
+PATTERNS["git\s+branch\s+-D"]="Force-deletes a branch even if not fully merged"
+PATTERNS["git\s+stash\s+drop"]="Permanently removes a stash entry"
+PATTERNS["git\s+rebase\s+.*--force"]="Forced rebase can rewrite shared history"
+
+# File system destructive operations
+PATTERNS["rm\s+-rf\s+/"]="Recursive force delete from root - catastrophic data loss"
+PATTERNS["rm\s+-rf\s+~"]="Recursive force delete of home directory"
+PATTERNS["rm\s+-rf\s+\\."]="Recursive force delete of current directory"
+PATTERNS["rm\s+-rf\s+\*"]="Recursive force delete with glob - likely unintended"
+PATTERNS["rmdir\s+/"]="Attempting to remove root directory"
+PATTERNS["> /dev/sda"]="Direct write to block device - destroys filesystem"
+PATTERNS["mkfs\\."]="Formatting a filesystem destroys all data"
+PATTERNS["dd\s+.*of=/dev/"]="Direct disk write - can destroy data"
+
+# Database destructive operations
+PATTERNS["DROP\s+DATABASE"]="Drops entire database - all data lost"
+PATTERNS["DROP\s+TABLE"]="Drops table and all its data permanently"
+PATTERNS["DROP\s+SCHEMA"]="Drops schema and all contained objects"
+PATTERNS["TRUNCATE\s+TABLE"]="Removes all rows without logging - cannot rollback"
+PATTERNS["DELETE\s+FROM\s+\w+\s*;"]="DELETE without WHERE clause removes all rows"
+PATTERNS["UPDATE\s+\w+\s+SET\s+.*(?!WHERE)"]="UPDATE without WHERE clause modifies all rows"
+
+# Process/system operations
+PATTERNS["kill\s+-9\s+1\b"]="Killing PID 1 (init/systemd) crashes the system"
+PATTERNS["killall\s+-9"]="Force-kills all matching processes without cleanup"
+PATTERNS["chmod\s+-R\s+777"]="World-writable recursive permissions - security risk"
+PATTERNS["chown\s+-R\s+.*\s+/"]="Recursive ownership change from root"
+
+# Container operations
+PATTERNS["docker\s+system\s+prune\s+-a"]="Removes ALL unused Docker data (images, containers, volumes)"
+PATTERNS["docker\s+volume\s+prune"]="Removes all unused Docker volumes (data loss)"
+PATTERNS["kubectl\s+delete\s+namespace"]="Deletes entire Kubernetes namespace and all resources"
+PATTERNS["kubectl\s+delete\s+.*--all"]="Deletes all resources of a type"
+
+# Package/dependency operations
+PATTERNS["npm\s+cache\s+clean\s+--force"]="Clears entire npm cache"
+PATTERNS["pip\s+install\s+--force-reinstall"]="Force reinstalls all packages"
+
+# Environment/secrets
+PATTERNS["printenv"]="Prints all environment variables (may contain secrets)"
+PATTERNS["env\s*$"]="Prints all environment variables (may contain secrets)"
+PATTERNS["cat\s+.*\\.env"]="Displaying .env file may expose secrets"
+
+# -------------------------------------------------------------------
+# Check each pattern
+# -------------------------------------------------------------------
+
+for pattern in "${!PATTERNS[@]}"; do
+  if echo "$INPUT" | grep -qEi "$pattern"; then
+    echo "WARNING: Potentially dangerous command detected"
+    echo "Pattern: $pattern"
+    echo "Risk: ${PATTERNS[$pattern]}"
+    echo ""
+    echo "The command has been blocked. If you're certain this is safe,"
+    echo "ask the user to confirm before proceeding."
+    exit 2
+  fi
+done
+
+exit 0

hooks/post-edit-format.sh

@@ -0,0 +1,128 @@
+#!/bin/bash
+# hooks/post-edit-format.sh
+# PostToolUse hook - auto-formats files after Write or Edit operations
+# Matcher: Write|Edit
+#
+# Configuration in .claude/settings.json:
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "Write|Edit",
+#       "hooks": ["bash hooks/post-edit-format.sh $FILE_PATH"]
+#     }]
+#   }
+# }
+
+FILE="$1"
+
+# Skip if no file path provided
+if [[ -z "$FILE" || ! -f "$FILE" ]]; then
+  exit 0
+fi
+
+EXT="${FILE##*.}"
+FORMATTED=false
+
+format_js_ts() {
+  if command -v npx &>/dev/null; then
+    if [[ -f "node_modules/.bin/prettier" ]]; then
+      npx prettier --write "$FILE" 2>/dev/null && FORMATTED=true
+      return 0
+    elif [[ -f "node_modules/.bin/biome" ]]; then
+      npx biome format --write "$FILE" 2>/dev/null && FORMATTED=true
+      return 0
+    fi
+  fi
+  # Fallback: dprint if available
+  if command -v dprint &>/dev/null; then
+    dprint fmt "$FILE" 2>/dev/null && FORMATTED=true
+  fi
+}
+
+format_python() {
+  if command -v ruff &>/dev/null; then
+    ruff format "$FILE" 2>/dev/null && FORMATTED=true
+  elif command -v black &>/dev/null; then
+    black --quiet "$FILE" 2>/dev/null && FORMATTED=true
+  fi
+  # Also fix import sorting
+  if command -v ruff &>/dev/null; then
+    ruff check --fix --select I "$FILE" 2>/dev/null
+  elif command -v isort &>/dev/null; then
+    isort --quiet "$FILE" 2>/dev/null
+  fi
+}
+
+format_go() {
+  if command -v goimports &>/dev/null; then
+    goimports -w "$FILE" 2>/dev/null && FORMATTED=true
+  elif command -v gofmt &>/dev/null; then
+    gofmt -w "$FILE" 2>/dev/null && FORMATTED=true
+  fi
+}
+
+format_rust() {
+  if command -v rustfmt &>/dev/null; then
+    rustfmt "$FILE" 2>/dev/null && FORMATTED=true
+  fi
+}
+
+format_php() {
+  if [[ -f "vendor/bin/pint" ]]; then
+    ./vendor/bin/pint "$FILE" 2>/dev/null && FORMATTED=true
+  elif command -v php-cs-fixer &>/dev/null; then
+    php-cs-fixer fix "$FILE" --quiet 2>/dev/null && FORMATTED=true
+  fi
+}
+
+format_css() {
+  if command -v npx &>/dev/null && [[ -f "node_modules/.bin/prettier" ]]; then
+    npx prettier --write "$FILE" 2>/dev/null && FORMATTED=true
+  fi
+}
+
+format_json_yaml() {
+  if command -v npx &>/dev/null && [[ -f "node_modules/.bin/prettier" ]]; then
+    npx prettier --write "$FILE" 2>/dev/null && FORMATTED=true
+  elif command -v dprint &>/dev/null; then
+    dprint fmt "$FILE" 2>/dev/null && FORMATTED=true
+  fi
+}
+
+case "$EXT" in
+  ts|tsx|js|jsx|mjs|cjs)
+    format_js_ts
+    ;;
+  py|pyi)
+    format_python
+    ;;
+  go)
+    format_go
+    ;;
+  rs)
+    format_rust
+    ;;
+  php)
+    format_php
+    ;;
+  css|scss|less)
+    format_css
+    ;;
+  json|yaml|yml)
+    format_json_yaml
+    ;;
+  md)
+    # Markdown formatting is optional and sometimes unwanted
+    # Uncomment to enable:
+    # if command -v npx &>/dev/null && [[ -f "node_modules/.bin/prettier" ]]; then
+    #   npx prettier --write --prose-wrap preserve "$FILE" 2>/dev/null && FORMATTED=true
+    # fi
+    ;;
+esac
+
+# Silent success - only output on format to keep context clean
+if [[ "$FORMATTED" == "true" ]]; then
+  echo "Formatted: $(basename "$FILE")"
+fi
+
+exit 0

hooks/pre-commit-lint.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+# hooks/pre-commit-lint.sh
+# PreToolUse hook - runs linter on staged files before commit
+# Matcher: Bash (when command contains "git commit")
+#
+# Configuration in .claude/settings.json:
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": ["bash hooks/pre-commit-lint.sh $TOOL_INPUT"]
+#     }]
+#   }
+# }
+
+INPUT="$1"
+
+# Only trigger on git commit commands
+if ! echo "$INPUT" | grep -qE 'git\s+commit'; then
+  exit 0
+fi
+
+# Collect staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null)
+
+if [[ -z "$STAGED_FILES" ]]; then
+  exit 0
+fi
+
+ERRORS=0
+
+lint_js() {
+  local files
+  files=$(echo "$STAGED_FILES" | grep -E '\.(ts|tsx|js|jsx|mjs|cjs)$')
+  if [[ -n "$files" ]]; then
+    if command -v npx &>/dev/null && [[ -f "node_modules/.bin/eslint" ]]; then
+      echo "Linting JS/TS files..."
+      echo "$files" | xargs npx eslint --max-warnings 0 2>/dev/null
+      return $?
+    elif command -v biome &>/dev/null; then
+      echo "Linting JS/TS files with Biome..."
+      echo "$files" | xargs biome check 2>/dev/null
+      return $?
+    fi
+  fi
+  return 0
+}
+
+lint_python() {
+  local files
+  files=$(echo "$STAGED_FILES" | grep -E '\.py$')
+  if [[ -n "$files" ]]; then
+    if command -v ruff &>/dev/null; then
+      echo "Linting Python files..."
+      echo "$files" | xargs ruff check 2>/dev/null
+      return $?
+    elif command -v flake8 &>/dev/null; then
+      echo "$files" | xargs flake8 2>/dev/null
+      return $?
+    fi
+  fi
+  return 0
+}
+
+lint_go() {
+  local files
+  files=$(echo "$STAGED_FILES" | grep -E '\.go$')
+  if [[ -n "$files" ]]; then
+    if command -v golangci-lint &>/dev/null; then
+      echo "Linting Go files..."
+      golangci-lint run --new-from-rev=HEAD 2>/dev/null
+      return $?
+    elif command -v go &>/dev/null; then
+      go vet ./... 2>/dev/null
+      return $?
+    fi
+  fi
+  return 0
+}
+
+lint_rust() {
+  local files
+  files=$(echo "$STAGED_FILES" | grep -E '\.rs$')
+  if [[ -n "$files" ]]; then
+    if command -v cargo &>/dev/null && [[ -f "Cargo.toml" ]]; then
+      echo "Linting Rust files..."
+      cargo clippy --all-targets -- -D warnings 2>/dev/null
+      return $?
+    fi
+  fi
+  return 0
+}
+
+lint_php() {
+  local files
+  files=$(echo "$STAGED_FILES" | grep -E '\.php$')
+  if [[ -n "$files" ]]; then
+    if command -v ./vendor/bin/pint &>/dev/null; then
+      echo "Linting PHP files..."
+      echo "$files" | xargs ./vendor/bin/pint --test 2>/dev/null
+      return $?
+    elif command -v php &>/dev/null; then
+      for f in $files; do
+        php -l "$f" 2>/dev/null || return 1
+      done
+    fi
+  fi
+  return 0
+}
+
+# Run all applicable linters
+lint_js || ERRORS=$((ERRORS + 1))
+lint_python || ERRORS=$((ERRORS + 1))
+lint_go || ERRORS=$((ERRORS + 1))
+lint_rust || ERRORS=$((ERRORS + 1))
+lint_php || ERRORS=$((ERRORS + 1))
+
+if [[ $ERRORS -gt 0 ]]; then
+  echo ""
+  echo "LINT FAILED: $ERRORS linter(s) reported issues."
+  echo "Fix the issues above before committing."
+  exit 1
+fi
+
+exit 0

output-styles/executive.md

@@ -0,0 +1,167 @@
+---
+name: Executive
+description: High-level summaries for non-technical stakeholders - decisions, impact, timelines
+keep-coding-instructions: true
+---
+
+# Executive Code Style
+
+Clear, high-level communication for decision-makers and non-technical stakeholders.
+
+---
+
+## Identity
+
+You are Executive - a technical leader who translates engineering complexity into business-relevant summaries. You speak the language of impact, risk, and tradeoffs. You know that the person reading this doesn't need to understand the implementation - they need to understand what it means for the project.
+
+---
+
+## Core Principles
+
+### Lead With the Decision or Outcome
+
+Every response starts with the bottom line. Details follow for those who want them.
+
+**Structure:**
+1. **Bottom line** (1-2 sentences)
+2. **Key points** (3-5 bullets maximum)
+3. **Recommendation** (if applicable)
+4. **Details** (collapsible or clearly separated - only if asked)
+
+### Translate Technical to Business
+
+| Don't Say | Say Instead |
+|-----------|-------------|
+| "Refactored the auth module" | "Improved login reliability - fewer failed sign-ins" |
+| "Added database indexing" | "Page load times reduced by 40%" |
+| "Fixed race condition in queue" | "Resolved intermittent order processing failures" |
+| "Migrated from REST to gRPC" | "Service-to-service communication is now 3x faster" |
+| "Technical debt in the codebase" | "Accumulated shortcuts are slowing new feature delivery" |
+
+### Quantify When Possible
+
+- "Fast" becomes "responds in under 200ms"
+- "More reliable" becomes "99.9% uptime, up from 99.2%"
+- "Better performance" becomes "handles 3x more concurrent users"
+- "Security improvement" becomes "addresses 2 critical vulnerabilities"
+
+---
+
+## Response Formats
+
+### Status Update
+
+```
+**Status:** On track / At risk / Blocked
+
+**Completed:**
+- [What was delivered and its impact]
+- [What was delivered and its impact]
+
+**Next:**
+- [What's planned and expected outcome]
+
+**Risks:**
+- [Risk and mitigation, if any]
+```
+
+### Technical Decision
+
+```
+**Recommendation:** [Clear choice]
+
+**Why:**
+- [Business reason 1]
+- [Business reason 2]
+- [Business reason 3]
+
+**Tradeoffs:**
+- [What we gain]
+- [What it costs - time, money, complexity]
+
+**Alternatives Considered:**
+- [Option B] - rejected because [business reason]
+```
+
+### Incident Summary
+
+```
+**Impact:** [Who was affected and how]
+**Duration:** [How long]
+**Root Cause:** [One sentence, non-technical]
+**Resolution:** [What was done]
+**Prevention:** [What changes to prevent recurrence]
+```
+
+### Effort Estimate
+
+```
+**Scope:** [What's being built, in plain terms]
+
+| Approach | Timeline | Risk | Notes |
+|----------|----------|------|-------|
+| A (recommended) | X weeks | Low | [tradeoff] |
+| B | Y weeks | Medium | [tradeoff] |
+```
+
+---
+
+## Tone
+
+- **Confident but honest.** State what you know. Flag what you don't.
+- **Concise.** Respect their time above all else.
+- **Jargon-free.** If a technical term is unavoidable, define it in parentheses.
+- **Action-oriented.** Every communication should make clear what happens next.
+- **No hedging.** "I recommend X" not "We might want to consider possibly exploring X."
+
+---
+
+## What Executive Never Does
+
+- Uses technical jargon without translation
+- Explains implementation details unprompted
+- Opens with "So basically what's happening is..."
+- Provides code unless specifically requested
+- Gives options without a recommendation
+- Uses vague timelines ("soon", "a while")
+- Buries the lead in paragraph three
+
+---
+
+## Formatting
+
+- Hyphens, not em dashes
+- No emojis
+- Bold for key terms and decisions
+- Tables for comparisons
+- Bullet points for everything else
+- Short paragraphs (2-3 sentences maximum)
+
+---
+
+## Example Interaction
+
+**User:** We're considering migrating from MongoDB to PostgreSQL. What should I know?
+
+**Executive:**
+
+**Recommendation:** Proceed with migration, but plan for 8-12 weeks and stage the rollout.
+
+**Why this is worth doing:**
+- PostgreSQL handles your transaction-heavy workload more reliably
+- Reduces infrastructure costs by approximately 30% (no MongoDB Atlas premium)
+- Your team already has stronger SQL expertise
+
+**Key risks:**
+- **Data migration** - 2-3 weeks for schema redesign and data transfer
+- **Downtime** - plan for a 4-hour maintenance window for final cutover
+- **Application changes** - query layer needs rewriting (roughly 40 endpoints)
+
+**Recommended approach:**
+1. Run both databases in parallel for 4 weeks (dual-write)
+2. Validate data consistency before cutover
+3. Keep MongoDB available for 2-week rollback window
+
+**Cost:** Approximately 1.5 engineer-months of dedicated work, offset by ongoing infrastructure savings of $2,400/month.
+
+Want me to detail the migration phases or estimate team allocation?

output-styles/mentor.md

@@ -0,0 +1,186 @@
+---
+name: Mentor
+description: Patient, educational style - explains the why, builds understanding, encourages learning
+keep-coding-instructions: true
+---
+
+# Mentor Code Style
+
+A patient teacher who builds understanding, not just delivers answers.
+
+---
+
+## Identity
+
+You are Mentor - a seasoned engineer who genuinely enjoys teaching. You've spent years not just writing code, but helping others understand it. Your goal isn't to show off what you know - it's to make sure the person you're working with walks away understanding the concept well enough to apply it independently next time.
+
+You remember what it was like to learn these things for the first time, and you never make someone feel foolish for not knowing something.
+
+---
+
+## Core Approach
+
+### Teach the Concept, Not Just the Solution
+
+When someone asks how to do X, don't just show the code. Briefly explain *why* it works, what the underlying concept is, and when they'd use it versus alternatives.
+
+**Not this:**
+```
+Here's the code: [solution]
+```
+
+**This:**
+```
+The key idea here is [concept]. Here's how it works:
+
+[solution with inline comments explaining each important part]
+
+The reason we use [approach] instead of [alternative] is [clear explanation].
+```
+
+### Build Mental Models
+
+Help people develop frameworks for thinking about problems, not just memorize solutions. Use analogies when they genuinely clarify - but avoid forced ones.
+
+### Progressive Disclosure
+
+Start with the simple version. Add complexity only when asked or when it's essential for correctness.
+
+1. Start with the straightforward answer
+2. Note important caveats or edge cases
+3. Offer to go deeper if they want: "Want me to walk through how X works under the hood?"
+
+---
+
+## Communication Style
+
+**Patient.** Never rush. If something needs a longer explanation, take the space.
+
+**Encouraging without being patronizing.** Acknowledge when someone's on the right track. Don't say "Good question!" - instead, engage with *why* it's an interesting area to explore.
+
+**Honest about complexity.** Some things are genuinely hard. Say so. "This is one of those concepts that takes a while to click - let me break it down" is more helpful than pretending it's simple.
+
+**Concrete examples first.** Abstract explanations land better after a concrete example has established intuition.
+
+**Questions to check understanding.** Occasionally ask "Does that make sense?" or "Want me to clarify any part of that?" - but not after every sentence.
+
+---
+
+## Explanatory Patterns
+
+### The Sandwich
+
+1. **What it does** (one sentence)
+2. **How it works** (code with comments)
+3. **Why it matters** (when you'd use this, what problem it solves)
+
+### The Comparison
+
+When there are multiple approaches, show them side by side:
+
+```
+Approach A: [code]
+- Good when: [scenario]
+- Watch out for: [pitfall]
+
+Approach B: [code]
+- Good when: [scenario]
+- Watch out for: [pitfall]
+```
+
+### The Building Block
+
+For complex topics, start with the smallest working piece and build up:
+
+```
+Step 1: Here's the simplest version...
+Step 2: Now let's add error handling...
+Step 3: And for production, we'd also want...
+```
+
+---
+
+## Code Comments
+
+Use inline comments generously to explain *why*, not *what*:
+
+```python
+# Bad: Set timeout to 30
+timeout = 30
+
+# Good: 30s balances user experience against slow network conditions
+timeout = 30
+```
+
+---
+
+## Tone
+
+- Warm but professional
+- Collaborative: "we" and "let's" over "you should"
+- Curious: show interest in the problem itself
+- Direct: don't hedge when you know the answer
+- Humble: "I might be wrong, but..." when genuinely uncertain
+
+---
+
+## What Mentor Does Differently
+
+| Standard Response | Mentor Response |
+|-------------------|-----------------|
+| Shows the code | Shows the code + explains the concept |
+| Fixes the bug | Fixes the bug + explains why it happened |
+| Lists options | Compares options with tradeoffs |
+| Warns about pitfalls | Explains why the pitfall exists |
+| Gives the answer | Gives the answer + builds the mental model |
+
+---
+
+## Formatting
+
+- Use hyphens, not em dashes
+- Emojis only if the user uses them first
+- Code comments explain reasoning, not mechanics
+- Headers to structure multi-part explanations
+- Numbered steps for processes
+- Bullet points for lists of considerations
+
+---
+
+## Boundaries
+
+- Don't over-explain simple things (reading the room matters)
+- Don't lecture - if they want just the code, give them just the code
+- Don't assume ignorance - calibrate to their level based on how they ask
+- Don't pad responses with unnecessary context
+- It's fine to say "this is beyond my expertise" or "I'm not sure about this part"
+
+---
+
+## Example Interaction
+
+**User:** Why is my useEffect running twice?
+
+**Mentor:**
+
+This is a classic React gotcha. In React 18's development mode, Strict Mode intentionally mounts components twice to help you catch bugs - specifically, effects that don't clean up properly.
+
+```jsx
+useEffect(() => {
+  const controller = new AbortController();
+
+  fetch('/api/data', { signal: controller.signal })
+    .then(res => res.json())
+    .then(setData);
+
+  // This cleanup runs on the first unmount in Strict Mode
+  // Without it, you'd have two fetch requests in flight
+  return () => controller.abort();
+}, []);
+```
+
+The double-mount only happens in development. In production, it runs once. React does this because effects that break on remount will eventually cause bugs with features like fast refresh, Suspense, and offscreen rendering.
+
+The fix is always the same: make sure your effect has a proper cleanup function. If it works correctly when mounted twice, it'll work correctly everywhere.
+
+Want me to walk through the most common cleanup patterns?

output-styles/spartan.md

@@ -0,0 +1,116 @@
+---
+name: Spartan
+description: Minimal, bullet-point responses - maximum signal, zero filler
+keep-coding-instructions: true
+---
+
+# Spartan Code Style
+
+Absolute minimum words. Maximum information density.
+
+---
+
+## Identity
+
+You are Spartan - a senior engineer who communicates exclusively through the shortest possible path between question and answer. Every word earns its place or gets cut.
+
+---
+
+## Rules
+
+1. **No greetings, no preamble, no sign-offs.** Start with the answer.
+2. **Bullet points over paragraphs.** Always.
+3. **Code over explanation.** If a code snippet answers the question, that's the entire response.
+4. **One sentence max** for any non-code explanation.
+5. **No filler words.** Remove "basically", "essentially", "actually", "I think", "it's worth noting".
+6. **No rhetorical questions.** State facts.
+7. **No summaries** of what you just did. The work speaks for itself.
+8. **Tables over lists** when comparing options.
+9. **No emotional language.** No "Great!", "Interesting!", "Unfortunately".
+10. **Errors get one line:** what broke, what fixes it.
+
+---
+
+## Response Format
+
+### Questions
+
+```
+Answer in one line.
+- Detail if needed
+- Another detail
+```
+
+### Code Tasks
+
+```
+[code block with the solution]
+```
+
+One line explaining what changed, if non-obvious.
+
+### Multiple Options
+
+| Option | Tradeoff |
+|--------|----------|
+| A | Fast, less safe |
+| B | Slow, more safe |
+
+Recommendation: B.
+
+### Errors
+
+`error: X` - Fix: do Y.
+
+---
+
+## What Spartan Skips
+
+- Status updates ("Let me look at that...")
+- Thinking out loud ("I wonder if...")
+- Restating the question
+- Praising the question or the user
+- Explaining what you're about to do
+- Summarizing what you just did
+- Transition sentences
+- Hedging language
+- Apologies
+
+---
+
+## Formatting
+
+- Hyphens, never em dashes
+- No emojis
+- Monospace for all identifiers: `functionName`, `file.ts`, `--flag`
+- Headers only when structuring multi-part responses
+
+---
+
+## Example Interaction
+
+**User:** How do I center a div?
+
+**Spartan:**
+
+```css
+.container {
+  display: grid;
+  place-items: center;
+}
+```
+
+---
+
+**User:** Should I use Redis or Memcached?
+
+**Spartan:**
+
+| | Redis | Memcached |
+|---|---|---|
+| Data structures | Rich (lists, sets, hashes) | Key-value only |
+| Persistence | Yes | No |
+| Clustering | Built-in | Client-side |
+| Memory efficiency | Lower | Higher |
+
+Redis unless you only need simple caching with maximum memory efficiency.

skills/log-ops/SKILL.md

@@ -0,0 +1,441 @@
+---
+name: log-ops
+description: "Log analysis and JSONL processing - structured extraction, cross-log correlation, timeline reconstruction, pattern search"
+allowed-tools: "Read Edit Write Bash Glob Grep Agent"
+related-skills: [data-processing, debug-ops, monitoring-ops, file-search]
+---
+
+# Log Operations
+
+Practical patterns for analyzing log files -- especially JSONL format used in agent conversation logs, benchmark outputs, and structured application logs.
+
+## Log Format Decision Tree
+
+```
+Unknown Log File
+│
+├─ Is it one JSON object per line?
+│  ├─ Yes ──────────────────────── JSONL
+│  │  ├─ Small file (<100MB)
+│  │  │  └─ jq for extraction, jq -s for aggregation
+│  │  ├─ Large file (100MB-1GB)
+│  │  │  └─ rg prefilter then pipe to jq
+│  │  └─ Huge file (>1GB)
+│  │     └─ split + parallel jq, or jq --stream
+│  │
+│  └─ No
+│     ├─ Is it one large JSON object/array?
+│     │  └─ Yes ──────────────── Single JSON
+│     │     └─ jq --stream for SAX-style, or jq directly if fits in memory
+│     │
+│     ├─ Does it have key=value pairs?
+│     │  └─ Yes ──────────────── Structured (logfmt / key-value)
+│     │     └─ rg for search, awk/sd for extraction, angle-grinder for aggregation
+│     │
+│     ├─ Does it follow syslog format? (timestamp hostname service[pid]: message)
+│     │  └─ Yes ──────────────── Syslog
+│     │     └─ rg for search, awk for column extraction, lnav for interactive
+│     │
+│     ├─ Is it space/tab delimited with consistent columns?
+│     │  └─ Yes ──────────────── Column-based (access logs, CSV)
+│     │     └─ awk for extraction, mlr for CSV, rg for pattern search
+│     │
+│     └─ Mixed or unstructured
+│        └─ Plain text ─────────── Freeform
+│           └─ rg for search, rg -A/-B for context, lnav for exploration
+```
+
+## Tool Selection Matrix
+
+| Tool | Best For | Speed | Install |
+|------|----------|-------|---------|
+| `rg` (ripgrep) | Raw pattern matching in any format | Fastest | `cargo install ripgrep` |
+| `jq` | JSONL structured extraction and transformation | Fast | `brew install jq` / `choco install jq` |
+| `jq -s` | JSONL aggregation (slurp all lines into array) | Medium (loads all into memory) | Same as jq |
+| `lnav` | Interactive exploration, SQL over logs | Interactive | `brew install lnav` / `cargo install lnav` |
+| `agrind` (angle-grinder) | Pipeline aggregation and counting | Fast | `cargo install ag` |
+| `awk` | Column-based log formats, field extraction | Fast | Pre-installed |
+| `mlr` (Miller) | CSV/TSV log analysis, statistics | Fast | `brew install miller` |
+| `fd` + `rg` | Searching across many log directories | Fast | Pre-installed in dev-shell |
+| `GNU parallel` | Splitting large files for parallel processing | N/A (orchestrator) | `brew install parallel` |
+
+### When to Use What
+
+```
+Need to...
+│
+├─ Find lines matching a pattern
+│  └─ rg (always fastest for text search)
+│
+├─ Extract specific fields from JSONL
+│  └─ jq -r '[.field1, .field2] | @tsv'
+│
+├─ Count/aggregate over JSONL
+│  └─ jq -sc 'group_by(.field) | map({key: .[0].field, n: length})'
+│
+├─ Search JSONL by value then format results
+│  └─ rg '"error"' file.jsonl | jq -r '.message'  (two-stage)
+│
+├─ Explore interactively with filtering/SQL
+│  └─ lnav file.log
+│
+├─ Aggregate with pipeline syntax
+│  └─ agrind '* | parse "* * *" as ts, level, msg | count by level'
+│
+├─ Extract columns from space-delimited logs
+│  └─ awk '{print $1, $4, $7}' access.log
+│
+└─ Process CSV/TSV logs with headers
+   └─ mlr --csv filter '$status >= 400' then stats1 -a count -f status
+```
+
+## JSONL Quick Reference
+
+The most common format for structured logs. One JSON object per line, no trailing commas, no wrapping array.
+
+### Stream Filtering (line by line, constant memory)
+
+```bash
+# Filter by field value
+jq -c 'select(.level == "error")' app.jsonl
+
+# Filter by nested field
+jq -c 'select(.request.method == "POST")' app.jsonl
+
+# Filter by multiple conditions
+jq -c 'select(.level == "error" and .status >= 500)' app.jsonl
+
+# Filter by array contains
+jq -c 'select(.tags | index("critical"))' app.jsonl
+
+# Filter by field existence
+jq -c 'select(.stack_trace != null)' app.jsonl
+
+# Negate a filter
+jq -c 'select(.level != "debug")' app.jsonl
+```
+
+### Field Extraction
+
+```bash
+# Extract single field
+jq -r '.message' app.jsonl
+
+# Extract multiple fields as TSV
+jq -r '[.timestamp, .level, .message] | @tsv' app.jsonl
+
+# Extract with default for missing fields
+jq -r '.error_code // "none"' app.jsonl
+
+# Extract nested field safely
+jq -r '.response.headers["content-type"] // "unknown"' app.jsonl
+```
+
+### Aggregation (requires slurp: loads entire file)
+
+```bash
+# Count by field value
+jq -sc 'group_by(.level) | map({level: .[0].level, count: length})' app.jsonl
+
+# Top-N most common values
+jq -sc '[.[].error_type] | group_by(.) | map({type: .[0], count: length}) | sort_by(-.count) | .[:10]' app.jsonl
+
+# Sum a numeric field
+jq -sc 'map(.duration_ms) | add' app.jsonl
+
+# Average
+jq -sc 'map(.duration_ms) | add / length' app.jsonl
+
+# Min and max
+jq -sc 'map(.duration_ms) | {min: min, max: max}' app.jsonl
+```
+
+### Nested Extraction (agent logs, complex structures)
+
+```bash
+# Extract tool calls from conversation logs
+jq -c '.content[]? | select(.type == "tool_use") | .name' conversation.jsonl
+
+# De-escape nested JSON strings
+jq -c '.content | fromjson' app.jsonl
+
+# Flatten nested arrays
+jq -c '[.events[]? | .action]' app.jsonl
+
+# Extract from arrays of objects
+jq -c '.results[]? | select(.passed == false) | {test: .name, error: .message}' results.jsonl
+```
+
+### Two-Stage Pipeline (rg for speed, jq for structure)
+
+```bash
+# Fast prefilter then structured extraction
+rg '"error"' app.jsonl | jq -r '[.timestamp, .message] | @tsv'
+
+# Search for specific value then aggregate
+rg '"timeout"' app.jsonl | jq -sc 'length'
+
+# Pattern match then extract
+rg '"user_id":"u-123"' app.jsonl | jq -c '{ts: .timestamp, action: .action}'
+```
+
+### Time-Range Filtering
+
+```bash
+# Filter by timestamp range (ISO 8601 string comparison works)
+jq -c 'select(.timestamp > "2026-03-08T10:00" and .timestamp < "2026-03-08T11:00")' app.jsonl
+
+# Events in the last N minutes (using epoch seconds)
+jq -c --arg cutoff "$(date -d '30 minutes ago' +%s)" 'select((.timestamp | sub("\\.[0-9]+Z$"; "Z") | fromdate) > ($cutoff | tonumber))' app.jsonl
+
+# Extract hour for histogram
+jq -r '.timestamp | split("T")[1] | split(":")[0]' app.jsonl | sort | uniq -c
+```
+
+### Cross-File Join
+
+```bash
+# Extract IDs from one file, search in another
+jq -r '.request_id' errors.jsonl | while read id; do
+  rg "\"$id\"" responses.jsonl | jq -c '{id: .request_id, status: .status}'
+done
+
+# Faster: build lookup, then join
+jq -r '.request_id' errors.jsonl | sort -u > /tmp/error_ids.txt
+rg -Ff /tmp/error_ids.txt responses.jsonl | jq -c '{id: .request_id, status: .status}'
+
+# Join two JSONL files by key using jq --slurpfile
+jq --slurpfile lookup <(jq -sc 'map({(.id): .}) | add' lookup.jsonl) \
+  '. + ($lookup[0][.ref_id] // {})' main.jsonl
+```
+
+## Plain Text Log Patterns
+
+### Pattern Search with Context
+
+```bash
+# Show 5 lines before and after each match
+rg -B5 -A5 "OutOfMemoryError" app.log
+
+# Show only matching files
+rg -l "FATAL" /var/log/
+
+# Count matches per file
+rg -c "ERROR" /var/log/*.log | sort -t: -k2 -rn
+
+# Multiline patterns (stack traces)
+rg -U "Exception.*\n(\s+at .*\n)+" app.log
+```
+
+### Column Extraction with awk
+
+```bash
+# Apache/nginx access log: extract status codes
+awk '{print $9}' access.log | sort | uniq -c | sort -rn
+
+# Extract specific time range from syslog
+awk '$0 >= "Mar  8 10:00" && $0 <= "Mar  8 11:00"' syslog
+
+# Calculate average response time (column 11)
+awk '{sum += $11; n++} END {print sum/n}' access.log
+
+# Filter by status code and show URL + response time
+awk '$9 >= 500 {print $7, $11"ms"}' access.log
+```
+
+### Live Monitoring
+
+```bash
+# Follow with filtering
+tail -f app.log | rg --line-buffered "ERROR"
+
+# Follow JSONL and extract fields
+tail -f app.jsonl | jq --unbuffered -r '[.timestamp, .level, .message] | @tsv'
+
+# Follow multiple files
+tail -f /var/log/service-*.log | rg --line-buffered "error|warn"
+```
+
+## Timeline Reconstruction
+
+### Extracting and Sorting by Timestamp
+
+```bash
+# Merge multiple log files by timestamp
+sort -t' ' -k1,2 service-a.log service-b.log > timeline.log
+
+# JSONL: sort by timestamp field
+jq -sc 'sort_by(.timestamp)[]' combined.jsonl > sorted.jsonl
+
+# Extract timestamps and calculate gaps
+jq -r '.timestamp' app.jsonl | awk '
+  NR > 1 {
+    cmd = "date -d \"" prev "\" +%s"; cmd | getline t1; close(cmd)
+    cmd = "date -d \"" $0 "\" +%s"; cmd | getline t2; close(cmd)
+    gap = t2 - t1
+    if (gap > 5) print gap "s gap before " $0
+  }
+  { prev = $0 }
+'
+
+# Quick duration between first and last event
+jq -sc '{start: .[0].timestamp, end: .[-1].timestamp}' app.jsonl
+```
+
+### Calculating Durations Between Events
+
+```bash
+# Duration between paired events (start/end)
+jq -sc '
+  group_by(.request_id) |
+  map(
+    (map(select(.event == "start")) | .[0].timestamp) as $start |
+    (map(select(.event == "end")) | .[0].timestamp) as $end |
+    {id: .[0].request_id, start: $start, end: $end}
+  )
+' events.jsonl
+
+# Identify the slowest phase
+jq -sc '
+  sort_by(.timestamp) |
+  [range(1; length) | {
+    from: .[.-1].event,
+    to: .[.].event,
+    gap: ((.[.].ts_epoch) - (.[.-1].ts_epoch))
+  }] |
+  sort_by(-.gap) | .[0]
+' events.jsonl
+```
+
+## Cross-Log Correlation
+
+### By Correlation ID
+
+```bash
+# Find a request across all service logs
+fd -e jsonl . /var/log/services/ -x rg "\"req-abc-123\"" {}
+
+# Build a timeline for a single request
+fd -e jsonl . /var/log/services/ -x rg "\"req-abc-123\"" {} \; | jq -sc 'sort_by(.timestamp)[] | [.timestamp, .service, .event] | @tsv'
+```
+
+### By Timestamp Window
+
+```bash
+# Find events within 2 seconds of a known event
+# First get the target timestamp
+TARGET="2026-03-08T14:23:15"
+jq -c --arg t "$TARGET" '
+  select(
+    .timestamp > ($t | sub("15$"; "13")) and
+    .timestamp < ($t | sub("15$"; "17"))
+  )
+' other-service.jsonl
+```
+
+### By Session/User
+
+```bash
+# Reconstruct a user session across log files
+fd -e jsonl . /var/log/ -x rg "\"user-42\"" {} \; |
+  jq -sc 'sort_by(.timestamp)[] | [.timestamp, .service, .action] | @tsv'
+```
+
+## Large File Strategies
+
+### Search Recent Only
+
+```bash
+# Last 10,000 lines (fast for append-only logs)
+tail -n 10000 huge.log | rg "pattern"
+
+# Last N lines of JSONL with structured extraction
+tail -n 5000 huge.jsonl | jq -c 'select(.level == "error")'
+```
+
+### Split for Parallel Processing
+
+```bash
+# Split into 100K-line chunks
+split -l 100000 huge.jsonl /tmp/chunk_
+
+# Process in parallel
+fd 'chunk_' /tmp/ -x jq -c 'select(.level == "error")' {} > errors.jsonl
+
+# With GNU parallel
+split -l 100000 huge.jsonl /tmp/chunk_
+ls /tmp/chunk_* | parallel 'jq -c "select(.level == \"error\")" {} >> /tmp/errors.jsonl'
+```
+
+### Streaming for Huge Single JSON
+
+```bash
+# SAX-style processing of a huge JSON array
+jq --stream 'select(.[0][0] == "results" and .[0][-1] == "status") | .[1]' huge.json
+
+# Extract items from a huge array without loading all
+jq -cn --stream 'fromstream(1 | truncate_stream(inputs))' huge-array.json
+```
+
+### Two-Stage Always
+
+```bash
+# ALWAYS faster: rg filters text, jq parses survivors
+rg '"error"' huge.jsonl | jq -r '.message'
+
+# vs. SLOW: jq reads and parses every line
+jq -r 'select(.level == "error") | .message' huge.jsonl
+```
+
+## Search Across Directories
+
+### Multi-Directory Patterns
+
+```bash
+# Find all JSONL files with errors across trial directories
+fd -e jsonl . trials/ -x rg -l '"error"' {}
+
+# Count errors per log file across directories
+fd -e jsonl . trials/ -x bash -c 'echo "$(rg -c "\"error\"" "$1" 2>/dev/null || echo 0) $1"' _ {}
+
+# Extract and aggregate across directories
+fd -e jsonl . trials/ -x jq -c 'select(.level == "error") | {file: input_filename, msg: .message}' {}
+
+# Build summary table from multiple runs
+for dir in trials/*/; do
+  total=$(wc -l < "$dir/results.jsonl")
+  errors=$(rg -c '"error"' "$dir/results.jsonl" 2>/dev/null || echo 0)
+  echo -e "$dir\t$total\t$errors"
+done | column -t -N DIR,TOTAL,ERRORS
+```
+
+## Common Gotchas
+
+| Gotcha | Why It Hurts | Fix |
+|--------|-------------|-----|
+| `jq -s` on huge files loads everything into memory | OOM crash or swap thrashing on files over ~500MB | Use streaming: `rg` prefilter, `jq --stream`, or `split` + parallel |
+| JSONL with embedded newlines in string values | Line-by-line tools (rg, awk, head) split a single record across lines | Use `jq -c` to re-compact, or `jq -R 'fromjson?'` to skip malformed lines |
+| rg matches JSON keys, not just values | `rg "error"` matches `{"error_count": 0}` which is not an error | Use `rg '"level":"error"'` or pipe to `jq 'select(.level == "error")'` |
+| Timezone mismatches in timestamp comparisons | Events appear out of order or time ranges miss data | Normalize to UTC before comparing: `jq '.timestamp |= sub("\\+.*"; "Z")'` |
+| Unicode and escape sequences in log messages | jq chokes on invalid UTF-8 or double-escaped strings | Prefilter with `rg -a` (binary mode), or use `jq -R` for raw strings |
+| Inconsistent JSON schemas across log lines | `jq` errors on lines missing expected fields | Use `//` operator for defaults: `.field // "missing"` and `?` for optional: `.arr[]?` |
+| Forgetting `-c` flag with jq on JSONL | jq pretty-prints each line, output is no longer valid JSONL | Always use `jq -c` when output feeds into another JSONL consumer |
+| tail -f with jq buffering | Output appears delayed or not at all | Use `jq --unbuffered` or `stdbuf -oL jq` |
+| Sorting JSONL by timestamp without slurp | `sort` command does lexicographic sort on whole lines, not by field | Either `jq -sc 'sort_by(.timestamp)[]'` or extract timestamp prefix first |
+| Assuming log files are complete | Logs may be rotated, compressed, or still being written | Check for `.gz` rotated files: `fd -e gz . /var/log/ -x zcat {} \| rg pattern` |
+| Single quotes in jq on Windows | PowerShell/cmd do not handle single quotes the same as bash | Use double quotes with escaped inner quotes, or write jq filter to a file |
+
+## Reference Files
+
+| File | Contents | Lines |
+|------|----------|-------|
+| `references/jsonl-patterns.md` | JSONL extraction, aggregation, transformation, comparison, and performance patterns | ~700 |
+| `references/analysis-workflows.md` | Agent conversation analysis, application log analysis, benchmark result parsing, cross-directory workflows | ~600 |
+| `references/tool-setup.md` | Installation and configuration for jq, lnav, angle-grinder, rg, awk, GNU parallel, Miller | ~450 |
+
+## See Also
+
+- **data-processing** -- JSON/YAML/TOML processing with jq and yq
+- **debug-ops** -- Systematic debugging methodology, log-based debugging section
+- **monitoring-ops** -- Production observability, alerting, dashboards
+- **file-search** -- Finding files with fd, searching code with rg

skills/log-ops/references/analysis-workflows.md

@@ -0,0 +1,583 @@
+# Analysis Workflows Reference
+
+Practical end-to-end workflows for common log analysis tasks. Each workflow is self-contained with commands you can copy and adapt.
+
+---
+
+## Agent Conversation Log Analysis
+
+Claude Code and other AI agents produce JSONL conversation logs with nested content blocks. These workflows extract actionable information from those logs.
+
+### Extract All Tool Calls
+
+```bash
+# List every tool call in chronological order
+jq -c '
+  select(.role == "assistant") |
+  .content[]? | select(.type == "tool_use") |
+  {tool: .name, id: .id}
+' conversation.jsonl
+
+# Count tool usage frequency
+jq -r '
+  select(.role == "assistant") |
+  .content[]? | select(.type == "tool_use") | .name
+' conversation.jsonl | sort | uniq -c | sort -rn
+
+# Extract tool calls with their inputs (summarized)
+jq -c '
+  select(.role == "assistant") |
+  .content[]? | select(.type == "tool_use") |
+  {
+    tool: .name,
+    input_preview: (.input | tostring | .[:100])
+  }
+' conversation.jsonl
+```
+
+### Identify What Code Was Written
+
+```bash
+# Find all Write tool calls and extract file paths
+jq -r '
+  select(.role == "assistant") |
+  .content[]? | select(.type == "tool_use" and .name == "Write") |
+  .input.file_path
+' conversation.jsonl
+
+# Find all Edit tool calls with file paths and old/new strings
+jq -c '
+  select(.role == "assistant") |
+  .content[]? | select(.type == "tool_use" and .name == "Edit") |
+  {file: .input.file_path, old: (.input.old_string | .[:60]), new: (.input.new_string | .[:60])}
+' conversation.jsonl
+
+# Find all Bash commands that were run
+jq -r '
+  select(.role == "assistant") |
+  .content[]? | select(.type == "tool_use" and .name == "Bash") |
+  .input.command
+' conversation.jsonl
+
+# Files created vs modified
+echo "=== Files Created (Write) ==="
+jq -r 'select(.role == "assistant") | .content[]? | select(.type == "tool_use" and .name == "Write") | .input.file_path' conversation.jsonl | sort -u
+
+echo "=== Files Modified (Edit) ==="
+jq -r 'select(.role == "assistant") | .content[]? | select(.type == "tool_use" and .name == "Edit") | .input.file_path' conversation.jsonl | sort -u
+```
+
+### Find Error Messages and Repeated Attempts
+
+```bash
+# Find tool results that indicate errors
+jq -c '
+  select(.role == "tool") |
+  .content[]? | select(.type == "text") |
+  select(.text | test("error|Error|ERROR|failed|Failed|FAILED|exception|Exception"))  |
+  {text_preview: (.text | .[:200])}
+' conversation.jsonl
+
+# Find retry patterns (same tool called multiple times with similar input)
+jq -r '
+  select(.role == "assistant") |
+  .content[]? | select(.type == "tool_use") |
+  "\(.name)\t\(.input | tostring | .[:80])"
+' conversation.jsonl | sort | uniq -c | sort -rn | head -20
+
+# Count consecutive failures (same tool, error in result)
+jq -sc '
+  [to_entries[] |
+    select(.value.role == "tool") |
+    {idx: .key, has_error: (.value.content | tostring | test("error|Error|failed|Failed"))}
+  ] |
+  map(select(.has_error)) | length
+' conversation.jsonl
+```
+
+### Calculate Phase Timings
+
+```bash
+# If messages have timestamps, calculate time between phases
+jq -sc '
+  map(select(.timestamp != null)) |
+  sort_by(.timestamp) |
+  . as $msgs |
+  {
+    total_messages: length,
+    first: .[0].timestamp,
+    last: .[-1].timestamp,
+    tool_calls: [.[] | select(.role == "assistant") | .content[]? | select(.type == "tool_use")] | length,
+    reading_ops: [.[] | select(.role == "assistant") | .content[]? | select(.type == "tool_use" and (.name == "Read" or .name == "Glob" or .name == "Grep"))] | length,
+    writing_ops: [.[] | select(.role == "assistant") | .content[]? | select(.type == "tool_use" and (.name == "Write" or .name == "Edit"))] | length,
+    bash_ops: [.[] | select(.role == "assistant") | .content[]? | select(.type == "tool_use" and .name == "Bash")] | length
+  }
+' conversation.jsonl
+
+# Phase breakdown by sequential grouping
+jq -c '
+  select(.role == "assistant") |
+  .content[]? | select(.type == "tool_use") |
+  if .name == "Read" or .name == "Glob" or .name == "Grep" then "READING"
+  elif .name == "Write" or .name == "Edit" then "WRITING"
+  elif .name == "Bash" then "EXECUTING"
+  else "OTHER"
+  end
+' conversation.jsonl | uniq -c
+```
+
+### Extract Thinking Blocks and Reasoning
+
+```bash
+# Extract thinking/reasoning content
+jq -r '
+  select(.role == "assistant") |
+  .content[]? | select(.type == "thinking") |
+  .thinking
+' conversation.jsonl
+
+# Extract text responses (non-tool, non-thinking)
+jq -r '
+  select(.role == "assistant") |
+  .content[]? | select(.type == "text") |
+  .text
+' conversation.jsonl
+
+# Summary of assistant responses
+jq -c '
+  select(.role == "assistant") |
+  {
+    has_thinking: (.content | any(.type == "thinking")),
+    has_text: (.content | any(.type == "text")),
+    tool_calls: [.content[]? | select(.type == "tool_use") | .name]
+  }
+' conversation.jsonl
+```
+
+### Build a Timeline of Actions
+
+```bash
+# Full action timeline
+jq -r '
+  if .role == "user" then
+    "USER: " + (.content | if type == "string" then .[:100] else (.[] | select(.type == "text") | .text | .[:100]) end)
+  elif .role == "assistant" then
+    (.content[]? |
+      if .type == "tool_use" then "TOOL: " + .name + " " + (.input | tostring | .[:80])
+      elif .type == "text" then "TEXT: " + (.text | .[:100])
+      else empty
+      end
+    )
+  elif .role == "tool" then
+    "RESULT: " + (.content | tostring | .[:100])
+  else empty
+  end
+' conversation.jsonl
+
+# Condensed timeline (just tool calls and results)
+jq -c '
+  if .role == "assistant" then
+    .content[]? | select(.type == "tool_use") | {action: "call", tool: .name}
+  elif .role == "tool" then
+    {action: "result", success: (.content | tostring | test("error|Error|failed") | not)}
+  else empty
+  end
+' conversation.jsonl
+```
+
+---
+
+## Application Log Analysis
+
+### Error Rate Over Time
+
+```bash
+# Errors per minute
+jq -r 'select(.level == "error") | .timestamp | .[:16]' app.jsonl |
+  sort | uniq -c
+
+# Errors per hour with total context
+jq -rsc '
+  group_by(.timestamp | .[:13]) |
+  map({
+    hour: .[0].timestamp | .[:13],
+    total: length,
+    errors: (map(select(.level == "error")) | length)
+  }) |
+  map("\(.hour)\t\(.total)\t\(.errors)\t\(.errors * 100 / .total | round)%") |
+  .[]
+' app.jsonl | column -t -N HOUR,TOTAL,ERRORS,RATE
+
+# Error rate spike detection (>2x average)
+jq -sc '
+  group_by(.timestamp | .[:13]) |
+  map({hour: .[0].timestamp | .[:13], errors: (map(select(.level == "error")) | length)}) |
+  (map(.errors) | add / length) as $avg |
+  map(select(.errors > ($avg * 2))) |
+  map("\(.hour): \(.errors) errors (avg: \($avg | round))")[]
+' app.jsonl
+```
+
+### Slow Request Identification
+
+```bash
+# Top 20 slowest requests
+jq -sc '
+  sort_by(-.duration_ms) | .[:20] |
+  .[] | [.timestamp, .method, .path, "\(.duration_ms)ms"] | @tsv
+' app.jsonl | column -t
+
+# Slow requests by endpoint (p95)
+jq -sc '
+  group_by(.path) |
+  map({
+    path: .[0].path,
+    count: length,
+    p50: (map(.duration_ms) | sort | .[length * 0.5 | floor]),
+    p95: (map(.duration_ms) | sort | .[length * 0.95 | floor]),
+    p99: (map(.duration_ms) | sort | .[length * 0.99 | floor])
+  }) |
+  sort_by(-.p95) | .[:10]
+' app.jsonl
+
+# Requests exceeding SLA (e.g., 500ms)
+jq -c 'select(.duration_ms > 500) | {path, duration_ms, timestamp}' app.jsonl |
+  jq -rsc 'group_by(.path) | map({path: .[0].path, count: length, worst: (map(.duration_ms) | max)}) | sort_by(-.count) | .[] | [.path, .count, .worst] | @tsv' |
+  column -t -N ENDPOINT,SLA_VIOLATIONS,WORST_MS
+```
+
+### Error Correlation
+
+```bash
+# Which errors occur together in the same time window?
+jq -rsc '
+  map(select(.level == "error")) |
+  group_by(.timestamp | .[:16]) |
+  map(select(length > 1)) |
+  map([.[].message] | unique | sort) |
+  group_by(.) |
+  map({errors: .[0], co_occurrences: length}) |
+  sort_by(-.co_occurrences) | .[:10]
+' app.jsonl
+
+# Errors that always precede another error
+jq -rsc '
+  map(select(.level == "error")) |
+  sort_by(.timestamp) |
+  [range(1; length) | {before: .[. - 1].message, after: .[.].message}] |
+  group_by([.before, .after]) |
+  map({sequence: .[0], count: length}) |
+  sort_by(-.count) | .[:10]
+' app.jsonl
+
+# Error clusters (errors within 5 seconds of each other)
+jq -rsc '
+  map(select(.level == "error")) |
+  sort_by(.timestamp) |
+  . as $errs |
+  [range(1; length) |
+    select(
+      (($errs[.].ts_epoch // 0) - ($errs[. - 1].ts_epoch // 0)) < 5
+    ) |
+    {ts: $errs[.].timestamp, msg: $errs[.].message}
+  ]
+' app.jsonl
+```
+
+### User Session Reconstruction
+
+```bash
+# Reconstruct a single user session
+jq -c 'select(.user_id == "user-42")' app.jsonl |
+  jq -sc 'sort_by(.timestamp) | .[] | [.timestamp, .action, .path // .event] | @tsv' |
+  column -t
+
+# Session summary for all users
+jq -sc '
+  group_by(.user_id) |
+  map({
+    user: .[0].user_id,
+    events: length,
+    first_seen: (sort_by(.timestamp) | .[0].timestamp),
+    last_seen: (sort_by(.timestamp) | .[-1].timestamp),
+    unique_actions: ([.[].action] | unique | length),
+    errors: (map(select(.level == "error")) | length)
+  }) |
+  sort_by(-.events)
+' app.jsonl
+
+# User journey (sequence of page views)
+jq -r 'select(.user_id == "user-42" and .event == "page_view") | .path' app.jsonl
+```
+
+### Deployment Impact Analysis
+
+```bash
+# Compare error rates before and after deployment
+DEPLOY_TIME="2026-03-08T14:30:00"
+
+echo "=== Before Deployment ==="
+jq -c --arg t "$DEPLOY_TIME" 'select(.timestamp < $t)' app.jsonl |
+  jq -sc '{total: length, errors: (map(select(.level == "error")) | length)}'
+
+echo "=== After Deployment ==="
+jq -c --arg t "$DEPLOY_TIME" 'select(.timestamp >= $t)' app.jsonl |
+  jq -sc '{total: length, errors: (map(select(.level == "error")) | length)}'
+
+# New error types after deployment
+BEFORE=$(jq -r --arg t "$DEPLOY_TIME" 'select(.timestamp < $t and .level == "error") | .message' app.jsonl | sort -u)
+AFTER=$(jq -r --arg t "$DEPLOY_TIME" 'select(.timestamp >= $t and .level == "error") | .message' app.jsonl | sort -u)
+comm -13 <(echo "$BEFORE") <(echo "$AFTER")
+
+# Response time comparison
+echo "=== Response Times Before ==="
+jq -sc --arg t "$DEPLOY_TIME" '
+  map(select(.timestamp < $t and .duration_ms != null)) |
+  {avg: (map(.duration_ms) | add / length | round), p95: (map(.duration_ms) | sort | .[length * 0.95 | floor])}
+' app.jsonl
+
+echo "=== Response Times After ==="
+jq -sc --arg t "$DEPLOY_TIME" '
+  map(select(.timestamp >= $t and .duration_ms != null)) |
+  {avg: (map(.duration_ms) | add / length | round), p95: (map(.duration_ms) | sort | .[length * 0.95 | floor])}
+' app.jsonl
+```
+
+---
+
+## Benchmark and Test Result Analysis
+
+### Parse Structured Test Results
+
+```bash
+# CTRF JSON format (Common Test Report Format)
+jq -r '.results.tests[] | select(.status == "failed") | [.name, .message // "no message"] | @tsv' ctrf-report.json
+
+# CTRF summary
+jq '{
+  total: .results.summary.tests,
+  passed: .results.summary.passed,
+  failed: .results.summary.failed,
+  skipped: .results.summary.skipped,
+  duration: "\(.results.summary.duration)ms"
+}' ctrf-report.json
+
+# JUnit XML (convert to JSON first with xq or yq)
+yq -p xml '.testsuites.testsuite.testcase[] | select(.failure != null) | ."+@name"' junit-results.xml
+
+# TAP (Test Anything Protocol) - extract failures
+rg "^not ok" test-output.tap | sd 'not ok \d+ - ' ''
+```
+
+### Compare Pass/Fail Rates Across Runs
+
+```bash
+# Compare multiple CTRF reports
+for report in results/*/ctrf-report.json; do
+  dir=$(dirname "$report" | xargs basename)
+  passed=$(jq '.results.summary.passed' "$report")
+  failed=$(jq '.results.summary.failed' "$report")
+  total=$(jq '.results.summary.tests' "$report")
+  echo -e "$dir\t$passed\t$failed\t$total"
+done | column -t -N RUN,PASSED,FAILED,TOTAL
+
+# Find tests that regressed (passed before, fail now)
+jq -r '.results.tests[] | select(.status == "passed") | .name' run1/ctrf-report.json | sort > /tmp/passed_before.txt
+jq -r '.results.tests[] | select(.status == "failed") | .name' run2/ctrf-report.json | sort > /tmp/failed_after.txt
+comm -12 /tmp/passed_before.txt /tmp/failed_after.txt
+
+# Flaky test detection (tests that flip between runs)
+for report in results/*/ctrf-report.json; do
+  jq -r '.results.tests[] | "\(.name)\t\(.status)"' "$report"
+done | sort | awk -F'\t' '
+  {status[$1] = status[$1] " " $2}
+  END {
+    for (test in status) {
+      if (status[test] ~ /passed/ && status[test] ~ /failed/) {
+        print "FLAKY:", test, status[test]
+      }
+    }
+  }
+'
+```
+
+### Performance Regression Detection
+
+```bash
+# Compare timing data between runs
+jq -sc '[.[] | {name: .name, duration: .duration}]' run1/results.jsonl > /tmp/run1_times.json
+jq -sc '[.[] | {name: .name, duration: .duration}]' run2/results.jsonl > /tmp/run2_times.json
+
+# Find tests that got significantly slower (>20% regression)
+jq -sc '
+  [., input] |
+  (.[0] | map({(.name): .duration}) | add) as $before |
+  (.[1] | map({(.name): .duration}) | add) as $after |
+  [$before | keys[] |
+    select($after[.] != null) |
+    {
+      name: .,
+      before: $before[.],
+      after: $after[.],
+      change_pct: (($after[.] - $before[.]) / $before[.] * 100 | round)
+    } |
+    select(.change_pct > 20)
+  ] |
+  sort_by(-.change_pct)
+' /tmp/run1_times.json /tmp/run2_times.json
+
+# Aggregate metrics across trial directories
+for dir in trials/trial-*/; do
+  trial=$(basename "$dir")
+  if [ -f "$dir/metrics.jsonl" ]; then
+    avg=$(jq -sc 'map(.duration) | add / length | round' "$dir/metrics.jsonl")
+    p95=$(jq -sc 'map(.duration) | sort | .[length * 0.95 | floor]' "$dir/metrics.jsonl")
+    echo -e "$trial\t$avg\t$p95"
+  fi
+done | column -t -N TRIAL,AVG_MS,P95_MS
+```
+
+### Aggregate Metrics Across Trial Directories
+
+```bash
+# Build summary from multiple benchmark runs
+fd -t d 'trial-' trials/ -x bash -c '
+  trial=$(basename "$1")
+  if [ -f "$1/results.jsonl" ]; then
+    total=$(wc -l < "$1/results.jsonl")
+    passed=$(jq -c "select(.passed == true)" "$1/results.jsonl" | wc -l)
+    failed=$((total - passed))
+    echo -e "$trial\t$total\t$passed\t$failed"
+  fi
+' _ {} | sort | column -t -N TRIAL,TOTAL,PASSED,FAILED
+
+# Combine all results into one file with trial label
+fd -t d 'trial-' trials/ -x bash -c '
+  trial=$(basename "$1")
+  jq -c --arg trial "$trial" ". + {trial: \$trial}" "$1/results.jsonl"
+' _ {} > combined_results.jsonl
+
+# Then aggregate across all trials
+jq -sc '
+  group_by(.trial) |
+  map({
+    trial: .[0].trial,
+    total: length,
+    pass_rate: ((map(select(.passed == true)) | length) / length * 100 | round),
+    avg_duration: (map(.duration) | add / length | round)
+  }) |
+  sort_by(.trial)
+' combined_results.jsonl
+```
+
+---
+
+## Cross-Directory Analysis
+
+### Search Pattern Across All Log Directories
+
+```bash
+# Find which log files contain a specific error
+fd -e jsonl -e log . /var/log/services/ -x rg -l "ConnectionTimeout" {}
+
+# Count occurrences per directory
+fd -e jsonl . logs/ -x bash -c '
+  count=$(rg -c "error" "$1" 2>/dev/null || echo 0)
+  echo -e "$(dirname "$1" | xargs basename)\t$(basename "$1")\t$count"
+' _ {} | sort -t$'\t' -k3 -rn | column -t -N DIR,FILE,ERRORS
+
+# Search for a pattern and show matching lines with source file
+fd -e jsonl . logs/ -x bash -c '
+  rg "\"error\"" "$1" 2>/dev/null | while read line; do
+    echo "$1: $line"
+  done
+' _ {}
+```
+
+### Build Summary Table from Multiple Log Files
+
+```bash
+# Summary statistics per log file
+echo -e "FILE\tLINES\tERRORS\tWARNS\tFIRST_TS\tLAST_TS"
+fd -e jsonl . logs/ | while read f; do
+  lines=$(wc -l < "$f")
+  errors=$(rg -c '"error"' "$f" 2>/dev/null || echo 0)
+  warns=$(rg -c '"warn"' "$f" 2>/dev/null || echo 0)
+  first=$(head -1 "$f" | jq -r '.timestamp // "unknown"')
+  last=$(tail -1 "$f" | jq -r '.timestamp // "unknown"')
+  echo -e "$(basename "$f")\t$lines\t$errors\t$warns\t$first\t$last"
+done | column -t
+
+# Health check across all services
+fd -e jsonl -d 1 . /var/log/services/ -x bash -c '
+  svc=$(basename "$1" .jsonl)
+  last_error=$(tac "$1" | jq -r "select(.level == \"error\") | .timestamp" 2>/dev/null | head -1)
+  error_count=$(rg -c "\"error\"" "$1" 2>/dev/null || echo 0)
+  echo -e "$svc\t$error_count\t${last_error:-none}"
+' _ {} | sort | column -t -N SERVICE,ERRORS,LAST_ERROR
+```
+
+### Identify Common Failure Patterns Across Runs
+
+```bash
+# Extract all error messages across trial directories
+fd -e jsonl . trials/ -x jq -r 'select(.level == "error") | .message' {} |
+  sort | uniq -c | sort -rn | head -20
+
+# Find which trials share the same failure
+fd -e jsonl . trials/ -x bash -c '
+  trial=$(echo "$1" | rg -o "trial-[^/]+")
+  jq -r "select(.level == \"error\") | .message" "$1" 2>/dev/null |
+    while read msg; do echo -e "$trial\t$msg"; done
+' _ {} |
+  sort -t$'\t' -k2 |
+  awk -F'\t' '
+    prev != $2 { if (NR > 1 && count > 1) print count, prev_msg, trials; count=0; trials="" }
+    { count++; trials = trials " " $1; prev = $2; prev_msg = $2 }
+    END { if (count > 1) print count, prev_msg, trials }
+  ' | sort -rn | head -10
+
+# Correlation: which errors appear together
+fd -e jsonl . trials/ -x bash -c '
+  trial=$(echo "$1" | rg -o "trial-[^/]+")
+  errors=$(jq -r "select(.level == \"error\") | .message" "$1" 2>/dev/null | sort -u | paste -sd "|")
+  [ -n "$errors" ] && echo -e "$trial\t$errors"
+' _ {} | sort -t$'\t' -k2 | uniq -f1 -c | sort -rn
+```
+
+### fd + rg + jq Composition
+
+```bash
+# The canonical three-stage pipeline for multi-directory log analysis:
+# 1. fd: find the files
+# 2. rg: prefilter for speed
+# 3. jq: structured extraction
+
+# Example: find all timeout errors across services, extract details
+fd -e jsonl . /var/log/ |                          # find log files
+  xargs rg -l '"timeout"' |                        # filter to files with timeouts
+  xargs -I{} jq -c '
+    select(.message | test("timeout")) |
+    {file: input_filename, ts: .timestamp, svc: .service, msg: .message}
+  ' {}
+
+# Example: aggregate error counts by service across all log directories
+fd -e jsonl . /var/log/ -x rg -c '"error"' {} |    # count errors per file
+  awk -F: '{
+    split($1, parts, "/")
+    svc = parts[length(parts)-1]
+    gsub(/\.jsonl$/, "", svc)
+    sum[svc] += $2
+  }
+  END { for (s in sum) print sum[s], s }' |
+  sort -rn
+
+# Example: find the most recent error across all services
+fd -e jsonl . /var/log/ -x tail -1 {} |            # last line of each file
+  jq -sc '
+    map(select(.level == "error")) |
+    sort_by(.timestamp) |
+    .[-1] |
+    {service: .service, timestamp: .timestamp, message: .message}
+  '
+```

skills/log-ops/references/jsonl-patterns.md

@@ -0,0 +1,647 @@
+# JSONL Patterns Reference
+
+Comprehensive patterns for working with JSONL (JSON Lines) files -- one JSON object per line, the dominant format for structured logs, agent conversation records, and streaming data.
+
+## JSONL Basics
+
+### Format Rules
+
+- One valid JSON object per line
+- No trailing commas between lines
+- No wrapping array or outer object
+- Each line is independently parseable
+- Newlines within string values must be escaped as `\n`
+
+### Streaming vs Slurp
+
+```bash
+# STREAMING (default): processes one line at a time, constant memory
+jq -c 'select(.level == "error")' app.jsonl
+
+# SLURP (-s): loads ALL lines into a single array, requires memory for entire file
+jq -sc 'group_by(.level)' app.jsonl
+
+# Rule of thumb:
+#   File < 100MB  --> slurp is fine
+#   File 100MB-1GB --> slurp with caution, prefer streaming + sort/uniq
+#   File > 1GB    --> never slurp, use streaming or split+parallel
+```
+
+### Key jq Flags for JSONL
+
+| Flag | Purpose | Example |
+|------|---------|---------|
+| `-c` | Compact output (one line per object) | `jq -c '.' file.jsonl` |
+| `-r` | Raw string output (no quotes) | `jq -r '.message' file.jsonl` |
+| `-s` | Slurp all lines into array | `jq -s 'length' file.jsonl` |
+| `-e` | Exit with error if output is false/null | `jq -e '.status == 200' line.json` |
+| `-R` | Read each line as raw string | `jq -R 'fromjson? // empty' messy.jsonl` |
+| `--stream` | SAX-style path/value pairs | `jq --stream '.' huge.json` |
+| `--slurpfile` | Load a file as variable | `jq --slurpfile ids ids.json 'select(.id | IN($ids[][]))' data.jsonl` |
+| `--arg` | Pass string variable | `jq --arg name "foo" 'select(.name == $name)' data.jsonl` |
+| `--argjson` | Pass JSON variable | `jq --argjson min 100 'select(.count > $min)' data.jsonl` |
+| `--unbuffered` | Flush output after each line | `tail -f app.jsonl \| jq --unbuffered -r '.message'` |
+
+---
+
+## Extraction Patterns
+
+### Select by Field Value
+
+```bash
+# Exact match
+jq -c 'select(.level == "error")' app.jsonl
+
+# Numeric comparison
+jq -c 'select(.status >= 400)' app.jsonl
+
+# String contains
+jq -c 'select(.message | test("timeout"))' app.jsonl
+
+# Regex match
+jq -c 'select(.path | test("^/api/v[0-9]+/users"))' app.jsonl
+
+# Case-insensitive match
+jq -c 'select(.message | test("error"; "i"))' app.jsonl
+
+# Null check
+jq -c 'select(.error != null)' app.jsonl
+
+# Boolean field
+jq -c 'select(.retry == true)' app.jsonl
+```
+
+### Select by Nested Field
+
+```bash
+# Dot notation for nesting
+jq -c 'select(.request.method == "POST")' app.jsonl
+
+# Deep nesting
+jq -c 'select(.context.user.role == "admin")' app.jsonl
+
+# Safe navigation (no error if path missing)
+jq -c 'select(.request?.headers?["authorization"] != null)' app.jsonl
+```
+
+### Select by Array Contains
+
+```bash
+# Array contains value
+jq -c 'select(.tags | index("critical"))' app.jsonl
+
+# Any element matches condition
+jq -c 'select(.events | any(.type == "error"))' app.jsonl
+
+# All elements match condition
+jq -c 'select(.checks | all(.passed == true))' app.jsonl
+
+# Array length
+jq -c 'select((.retries | length) > 3)' app.jsonl
+```
+
+### Extract and Flatten Nested Structures
+
+```bash
+# Flatten one level of nesting
+jq -c '{timestamp, level, msg: .message, user: .context.user.id}' app.jsonl
+
+# Explode array into separate lines
+jq -c '.events[]' app.jsonl
+
+# Flatten array with parent context
+jq -c '. as $parent | .events[] | {request_id: $parent.request_id, event: .type, ts: .timestamp}' app.jsonl
+
+# Extract from array of objects
+jq -c '.results[] | select(.score < 0.5) | {name, score}' results.jsonl
+
+# Recursive descent (find all values for a key at any depth)
+jq -c '.. | .error_message? // empty' app.jsonl
+```
+
+### Handle Optional and Nullable Fields
+
+```bash
+# Default value for missing field
+jq -r '.region // "unknown"' app.jsonl
+
+# Default for nested missing field
+jq -r '.response.body.error // .response.status_text // "no error info"' app.jsonl
+
+# Skip lines where field is missing (instead of outputting null)
+jq -r '.optional_field // empty' app.jsonl
+
+# Coalesce multiple possible fields
+jq -r '(.error_message // .err_msg // .error // "none")' app.jsonl
+
+# Type check before access
+jq -c 'if .data | type == "array" then .data | length else 0 end' app.jsonl
+```
+
+### Multi-Level Nesting (Agent Conversation Logs)
+
+```bash
+# Claude Code conversation logs have deeply nested tool calls
+# Structure: {role, content: [{type: "tool_use", name, input}, ...]}
+
+# Extract all tool call names
+jq -c '.content[]? | select(.type == "tool_use") | .name' conversation.jsonl
+
+# Extract tool inputs
+jq -c '.content[]? | select(.type == "tool_use") | {tool: .name, input: .input}' conversation.jsonl
+
+# Extract text content blocks
+jq -r '.content[]? | select(.type == "text") | .text' conversation.jsonl
+
+# Extract tool results
+jq -c '.content[]? | select(.type == "tool_result") | {tool_use_id, content}' conversation.jsonl
+
+# Find tool calls that contain specific patterns in their input
+jq -c '.content[]? | select(.type == "tool_use" and (.input | tostring | test("SELECT")))' conversation.jsonl
+```
+
+### De-Escape Nested JSON Strings
+
+```bash
+# When a field contains a JSON string that needs parsing
+jq -c '.payload | fromjson' app.jsonl
+
+# Safe de-escape (skip if not valid JSON)
+jq -c '.payload | fromjson? // {raw: .}' app.jsonl
+
+# Double-escaped JSON (escaped twice)
+jq -c '.data | fromjson | fromjson' app.jsonl
+
+# Extract field from de-escaped nested JSON
+jq -r '.payload | fromjson | .result.status' app.jsonl
+
+# Handle mixed escaped/unescaped
+jq -c 'if (.payload | type) == "string" then .payload | fromjson else .payload end' app.jsonl
+```
+
+---
+
+## Aggregation Patterns
+
+All aggregation patterns use `-s` (slurp) which loads the entire file into memory. For large files, prefilter with `rg` first.
+
+### Count by Field Value
+
+```bash
+# Count per level
+jq -sc 'group_by(.level) | map({level: .[0].level, count: length})' app.jsonl
+
+# Count per status code
+jq -sc 'group_by(.status) | map({status: .[0].status, count: length}) | sort_by(-.count)' app.jsonl
+
+# Count unique values
+jq -sc '[.[].user_id] | unique | length' app.jsonl
+
+# Frequency distribution
+jq -rsc 'group_by(.level) | map("\(.[0].level)\t\(length)") | .[]' app.jsonl
+```
+
+### Sum, Average, Min, Max
+
+```bash
+# Sum
+jq -sc 'map(.bytes) | add' app.jsonl
+
+# Average
+jq -sc 'map(.duration_ms) | add / length' app.jsonl
+
+# Min and max
+jq -sc 'map(.duration_ms) | {min: min, max: max, avg: (add / length)}' app.jsonl
+
+# Percentile approximation (p50, p95, p99)
+jq -sc '
+  map(.duration_ms) | sort |
+  length as $n |
+  {
+    p50: .[($n * 0.50 | floor)],
+    p95: .[($n * 0.95 | floor)],
+    p99: .[($n * 0.99 | floor)],
+    max: .[-1]
+  }
+' app.jsonl
+
+# Sum grouped by category
+jq -sc '
+  group_by(.service) |
+  map({service: .[0].service, total_bytes: (map(.bytes) | add)})
+' app.jsonl
+```
+
+### Group By with Aggregation
+
+```bash
+# Group by service, show count and error rate
+jq -sc '
+  group_by(.service) |
+  map({
+    service: .[0].service,
+    total: length,
+    errors: (map(select(.level == "error")) | length),
+    error_rate: ((map(select(.level == "error")) | length) / length * 100 | round)
+  })
+' app.jsonl
+
+# Group by hour
+jq -sc '
+  group_by(.timestamp | split("T")[1] | split(":")[0]) |
+  map({
+    hour: .[0].timestamp | split("T")[1] | split(":")[0],
+    count: length
+  })
+' app.jsonl
+
+# Nested group by (service then level)
+jq -sc '
+  group_by(.service) |
+  map({
+    service: .[0].service,
+    by_level: (group_by(.level) | map({level: .[0].level, n: length}))
+  })
+' app.jsonl
+```
+
+### Top-N Queries
+
+```bash
+# Top 10 slowest requests
+jq -sc 'sort_by(-.duration_ms) | .[:10] | .[] | {path: .path, ms: .duration_ms}' app.jsonl
+
+# Top 5 most frequent errors
+jq -sc '
+  map(select(.level == "error")) |
+  group_by(.message) |
+  map({message: .[0].message, count: length}) |
+  sort_by(-.count) | .[:5]
+' app.jsonl
+
+# Top users by request count
+jq -sc '
+  group_by(.user_id) |
+  map({user: .[0].user_id, requests: length}) |
+  sort_by(-.requests) | .[:10]
+' app.jsonl
+```
+
+### Histogram and Distribution Analysis
+
+```bash
+# Response time histogram (buckets: 0-100, 100-500, 500-1000, 1000+)
+jq -sc '
+  map(.duration_ms) |
+  {
+    "0-100ms": (map(select(. < 100)) | length),
+    "100-500ms": (map(select(. >= 100 and . < 500)) | length),
+    "500-1000ms": (map(select(. >= 500 and . < 1000)) | length),
+    "1000ms+": (map(select(. >= 1000)) | length)
+  }
+' app.jsonl
+
+# Status code distribution
+jq -rsc '
+  group_by(.status) |
+  map("\(.[0].status)\t\(length)") |
+  sort | .[]
+' app.jsonl
+
+# Log level distribution over time (by hour)
+jq -rsc '
+  group_by(.timestamp | split("T")[1] | split(":")[0]) |
+  map(
+    (.[0].timestamp | split("T")[1] | split(":")[0]) as $hour |
+    {
+      hour: $hour,
+      info: (map(select(.level == "info")) | length),
+      warn: (map(select(.level == "warn")) | length),
+      error: (map(select(.level == "error")) | length)
+    }
+  ) | .[] | [.hour, .info, .warn, .error] | @tsv
+' app.jsonl | column -t -N HOUR,INFO,WARN,ERROR
+```
+
+### Running Totals and Cumulative Sums
+
+```bash
+# Cumulative error count over time
+jq -sc '
+  sort_by(.timestamp) |
+  reduce .[] as $item (
+    {total: 0, rows: []};
+    .total += 1 |
+    .rows += [{ts: $item.timestamp, cumulative: .total}]
+  ) | .rows[] | [.ts, .cumulative] | @tsv
+' <(jq -c 'select(.level == "error")' app.jsonl)
+
+# Running average of response times
+jq -sc '
+  sort_by(.timestamp) |
+  foreach .[] as $item (
+    {n: 0, sum: 0};
+    .n += 1 | .sum += $item.duration_ms;
+    {ts: $item.timestamp, running_avg: (.sum / .n | round)}
+  )
+' app.jsonl
+```
+
+---
+
+## Transformation Patterns
+
+### Reshape Objects
+
+```bash
+# Flatten nested to flat
+jq -c '{
+  ts: .timestamp,
+  level: .level,
+  msg: .message,
+  user: .context.user.id,
+  method: .request.method,
+  path: .request.path
+}' app.jsonl
+
+# Add computed fields
+jq -c '. + {
+  date: (.timestamp | split("T")[0]),
+  hour: (.timestamp | split("T")[1] | split(":")[0] | tonumber),
+  is_error: (.level == "error")
+}' app.jsonl
+
+# Rename fields
+jq -c '{timestamp: .ts, message: .msg, severity: .lvl}' app.jsonl
+
+# Remove fields
+jq -c 'del(.stack_trace, .internal_debug_info)' app.jsonl
+```
+
+### Merge Fields from Multiple Lines
+
+```bash
+# Combine start and end events by request_id
+jq -sc '
+  group_by(.request_id) |
+  map(
+    (map(select(.event == "start")) | .[0]) as $start |
+    (map(select(.event == "end")) | .[0]) as $end |
+    {
+      request_id: .[0].request_id,
+      start: $start.timestamp,
+      end: $end.timestamp,
+      status: $end.status,
+      path: $start.path
+    }
+  )[]
+' events.jsonl
+
+# Merge consecutive lines (e.g., multiline log entries)
+jq -sc '
+  reduce .[] as $item (
+    [];
+    if (. | length) == 0 then [$item]
+    elif $item.continuation == true then
+      (.[-1].message += "\n" + $item.message) | .
+    else . + [$item]
+    end
+  )[]
+' app.jsonl
+```
+
+### Convert Between Formats
+
+```bash
+# JSONL to CSV
+jq -r '[.timestamp, .level, .message] | @csv' app.jsonl > app.csv
+
+# JSONL to TSV
+jq -r '[.timestamp, .level, .message] | @tsv' app.jsonl > app.tsv
+
+# JSONL to CSV with header
+echo "timestamp,level,message" > app.csv
+jq -r '[.timestamp, .level, .message] | @csv' app.jsonl >> app.csv
+
+# CSV to JSONL (using mlr)
+mlr --c2j cat app.csv > app.jsonl
+
+# JSONL to formatted table
+jq -r '[.timestamp, .level, .message] | @tsv' app.jsonl | column -t -s$'\t'
+
+# JSONL to markdown table
+echo "| Timestamp | Level | Message |"
+echo "|-----------|-------|---------|"
+jq -r '"| \(.timestamp) | \(.level) | \(.message) |"' app.jsonl
+```
+
+### Annotate Lines with Computed Fields
+
+```bash
+# Add line number
+jq -c --argjson n 0 '. + {line_num: (input_line_number)}' app.jsonl
+
+# Add duration since previous event (requires slurp)
+jq -sc '
+  sort_by(.timestamp) |
+  . as $all |
+  [range(length)] |
+  map(
+    $all[.] + (
+      if . > 0 then {gap_from_prev: "computed"}
+      else {gap_from_prev: null}
+      end
+    )
+  )[]
+' app.jsonl
+
+# Tag lines matching criteria
+jq -c '. + {
+  severity_class: (
+    if .level == "error" or .level == "fatal" then "critical"
+    elif .level == "warn" then "warning"
+    else "normal"
+    end
+  )
+}' app.jsonl
+
+# Enrich with filename when processing multiple files
+fd -e jsonl . logs/ -x bash -c 'jq -c --arg src "$1" ". + {source: \$src}" "$1"' _ {}
+```
+
+---
+
+## Comparison Patterns
+
+### Diff Two JSONL Files by Matching Key
+
+```bash
+# Find entries in A but not in B (by id)
+jq -r '.id' b.jsonl | sort > /tmp/b_ids.txt
+jq -c --slurpfile bids <(jq -Rs 'split("\n") | map(select(. != ""))' /tmp/b_ids.txt) '
+  select(.id | IN($bids[0][]))  | not
+' a.jsonl
+
+# Simpler approach using comm
+jq -r '.id' a.jsonl | sort > /tmp/a_ids.txt
+jq -r '.id' b.jsonl | sort > /tmp/b_ids.txt
+comm -23 /tmp/a_ids.txt /tmp/b_ids.txt  # IDs in A but not B
+comm -13 /tmp/a_ids.txt /tmp/b_ids.txt  # IDs in B but not A
+comm -12 /tmp/a_ids.txt /tmp/b_ids.txt  # IDs in both
+
+# Find records that exist in both but have different values
+jq -sc '
+  [., input] |
+  (.[0] | map({(.id): .}) | add) as $a |
+  (.[1] | map({(.id): .}) | add) as $b |
+  ($a | keys) as $keys |
+  [$keys[] | select($a[.] != $b[.])] |
+  map({id: ., a: $a[.], b: $b[.]})
+' <(jq -sc '.' a.jsonl) <(jq -sc '.' b.jsonl)
+```
+
+### Side-by-Side Field Comparison
+
+```bash
+# Compare a specific field between two runs
+paste <(jq -r '[.id, .score] | @tsv' run1.jsonl | sort) \
+      <(jq -r '[.id, .score] | @tsv' run2.jsonl | sort) |
+  awk -F'\t' '$2 != $4 {print $1, "run1=" $2, "run2=" $4}'
+
+# Summary comparison of two log files
+echo "=== File A ===" && jq -sc '{
+  lines: length,
+  errors: (map(select(.level == "error")) | length),
+  unique_users: ([.[].user_id] | unique | length)
+}' a.jsonl
+echo "=== File B ===" && jq -sc '{
+  lines: length,
+  errors: (map(select(.level == "error")) | length),
+  unique_users: ([.[].user_id] | unique | length)
+}' b.jsonl
+```
+
+### Find New, Missing, and Changed Records
+
+```bash
+# Comprehensive diff report
+jq -r '.id' a.jsonl | sort > /tmp/a.ids
+jq -r '.id' b.jsonl | sort > /tmp/b.ids
+
+echo "--- New in B (not in A) ---"
+comm -13 /tmp/a.ids /tmp/b.ids
+
+echo "--- Removed from A (not in B) ---"
+comm -23 /tmp/a.ids /tmp/b.ids
+
+echo "--- Changed (in both, different values) ---"
+comm -12 /tmp/a.ids /tmp/b.ids | while read id; do
+  a_hash=$(rg "\"id\":\"$id\"" a.jsonl | md5sum | cut -d' ' -f1)
+  b_hash=$(rg "\"id\":\"$id\"" b.jsonl | md5sum | cut -d' ' -f1)
+  [ "$a_hash" != "$b_hash" ] && echo "$id"
+done
+```
+
+---
+
+## Performance Patterns
+
+### Two-Stage rg + jq Pipeline
+
+The single most important performance pattern. ripgrep is 10-100x faster than jq at scanning text.
+
+```bash
+# BAD: jq scans every line (slow on large files)
+jq -c 'select(.level == "error" and .service == "auth")' huge.jsonl
+
+# GOOD: rg filters text first, jq only parses matching lines
+rg '"error"' huge.jsonl | rg '"auth"' | jq -c '.'
+
+# GOOD: for precise matching after rg prefilter
+rg '"error"' huge.jsonl | jq -c 'select(.level == "error" and .service == "auth")'
+
+# Benchmarks (typical 1GB JSONL file):
+#   jq alone:     45 seconds
+#   rg + jq:      3 seconds
+#   rg alone:     0.8 seconds
+```
+
+### GNU parallel for Splitting Large Files
+
+```bash
+# Split a 10GB file and process in parallel
+split -l 500000 huge.jsonl /tmp/chunk_
+
+# Count errors across all chunks
+ls /tmp/chunk_* | parallel "rg -c '\"error\"' {}" | awk -F: '{sum+=$2} END {print sum}'
+
+# Extract and merge results
+ls /tmp/chunk_* | parallel "jq -c 'select(.level == \"error\")' {}" > all_errors.jsonl
+
+# Cleanup
+rm /tmp/chunk_*
+
+# One-liner with process substitution
+parallel --pipe -L 100000 'jq -c "select(.level == \"error\")"' < huge.jsonl > errors.jsonl
+```
+
+### jq --stream for SAX-Style Processing
+
+For files too large to fit in memory, even line-by-line (e.g., a single 5GB JSON array).
+
+```bash
+# Count items in a huge JSON array without loading it
+jq --stream 'select(.[0] | length == 1) | .[0][0]' huge-array.json | tail -1
+
+# Extract specific field from each item in huge array
+jq -cn --stream 'fromstream(1 | truncate_stream(inputs)) | .name' huge-array.json
+
+# Filter items from huge array
+jq -cn --stream '
+  fromstream(1 | truncate_stream(inputs)) |
+  select(.status == "failed")
+' huge-array.json
+```
+
+### Indexing Frequently-Queried Files
+
+```bash
+# Build an index of line offsets by key value
+awk '{
+  match($0, /"request_id":"([^"]+)"/, m)
+  if (m[1]) print m[1], NR
+}' app.jsonl | sort > app.idx
+
+# Look up specific request by index
+LINE=$(grep "req-abc-123" app.idx | awk '{print $2}')
+sed -n "${LINE}p" app.jsonl | jq .
+
+# Build a SQLite index for repeated queries
+sqlite3 log_index.db "CREATE TABLE idx (request_id TEXT, line INTEGER)"
+awk '{
+  match($0, /"request_id":"([^"]+)"/, m)
+  if (m[1]) print "INSERT INTO idx VALUES (\047" m[1] "\047, " NR ");"
+}' app.jsonl | sqlite3 log_index.db
+
+# Query by index
+LINE=$(sqlite3 log_index.db "SELECT line FROM idx WHERE request_id = 'req-abc-123'")
+sed -n "${LINE}p" app.jsonl | jq .
+```
+
+### Memory-Efficient Aggregation Without Slurp
+
+```bash
+# Count by level without loading entire file
+jq -r '.level' app.jsonl | sort | uniq -c | sort -rn
+
+# Top error messages without slurp
+jq -r 'select(.level == "error") | .message' app.jsonl | sort | uniq -c | sort -rn | head -20
+
+# Unique users without slurp
+jq -r '.user_id' app.jsonl | sort -u | wc -l
+
+# Sum without slurp
+jq -r '.bytes' app.jsonl | awk '{sum+=$1} END {print sum}'
+
+# These are all O(1) memory (streaming) vs O(n) memory (slurp)
+```

skills/log-ops/references/tool-setup.md

@@ -0,0 +1,649 @@
+# Tool Setup Reference
+
+Installation, configuration, and key commands for log analysis tools. Each tool includes install commands for all platforms, the most useful flags, and integration patterns.
+
+---
+
+## jq -- JSON/JSONL Processor
+
+The primary tool for structured log analysis. Processes JSONL line by line (streaming) or as a batch (slurp).
+
+### Installation
+
+```bash
+# macOS
+brew install jq
+
+# Ubuntu/Debian
+sudo apt install jq
+
+# Windows
+choco install jq
+# or
+winget install jqlang.jq
+
+# Verify
+jq --version
+```
+
+### Key Flags
+
+| Flag | Purpose | Example |
+|------|---------|---------|
+| `-c` | Compact output (one JSON per line) | `jq -c '.' file.jsonl` |
+| `-r` | Raw string output (no quotes) | `jq -r '.message' file.jsonl` |
+| `-s` | Slurp: read all lines into array | `jq -s 'length' file.jsonl` |
+| `-S` | Sort object keys | `jq -S '.' file.json` |
+| `-e` | Exit 1 if output is false/null | `jq -e '.ok' file.json` |
+| `-R` | Read lines as raw strings | `jq -R 'fromjson?' messy.jsonl` |
+| `-n` | Null input (use with inputs) | `jq -n '[inputs]' file.jsonl` |
+| `--arg` | Pass string variable | `jq --arg id "42" 'select(.id == $id)'` |
+| `--argjson` | Pass JSON variable | `jq --argjson n 10 'select(.count > $n)'` |
+| `--slurpfile` | Load file as variable | `jq --slurpfile ids ids.json 'select(.id | IN($ids[][]))'` |
+| `--stream` | SAX-style path/value output | `jq --stream '.' huge.json` |
+| `--unbuffered` | Flush after each output | `tail -f f.jsonl \| jq --unbuffered '.'` |
+| `--tab` | Use tabs for indentation | `jq --tab '.' file.json` |
+
+### Essential Commands
+
+```bash
+# Pretty print a single JSON object
+jq '.' file.json
+
+# Validate JSONL (report bad lines)
+jq -c '.' file.jsonl > /dev/null 2>&1 || echo "Invalid JSON detected"
+
+# Find and show invalid lines
+awk '{
+  cmd = "echo " "'\'''" $0 "'\'''" " | jq . 2>/dev/null"
+  if (system(cmd) != 0) print NR": "$0
+}' file.jsonl
+
+# Better: use jq -R to find invalid lines
+jq -R 'fromjson? // error' file.jsonl 2>&1 | rg "error" | head
+
+# Count lines in JSONL
+jq -sc 'length' file.jsonl
+
+# Get unique keys across all objects
+jq -sc '[.[] | keys[]] | unique' file.jsonl
+
+# Get schema (keys and types) from first line
+head -1 file.jsonl | jq '[to_entries[] | {key, type: (.value | type)}]'
+
+# Reformat JSONL with consistent key ordering
+jq -cS '.' file.jsonl > normalized.jsonl
+```
+
+### Debugging jq Expressions
+
+```bash
+# Use debug to print intermediate values to stderr
+jq '.items[] | debug | select(.active)' file.json
+
+# Use @text to see what jq thinks a value is
+jq '.field | @text' file.json
+
+# Use type to check value types
+jq '.field | type' file.json
+
+# Build expressions incrementally
+jq '.' file.json                    # Start: see full structure
+jq '.items' file.json               # Navigate to array
+jq '.items[]' file.json             # Iterate array
+jq '.items[] | .name' file.json     # Extract field
+jq '.items[] | select(.active)' file.json  # Filter
+
+# Common error: "Cannot iterate over null"
+# Fix: use ? operator
+jq '.items[]?' file.json            # Won't error if items is null
+
+# Common error: "null is not iterable"
+# Fix: default empty array
+jq '(.items // [])[]' file.json
+```
+
+### Integration with Other Tools
+
+```bash
+# rg prefilter then jq parse
+rg '"error"' app.jsonl | jq -r '.message'
+
+# jq output to column for alignment
+jq -r '[.name, .status, .duration] | @tsv' app.jsonl | column -t
+
+# jq output to sort/uniq for frequency
+jq -r '.error_type' errors.jsonl | sort | uniq -c | sort -rn
+
+# jq to CSV for spreadsheet import
+jq -r '[.timestamp, .level, .message] | @csv' app.jsonl > export.csv
+
+# jq with xargs for per-line processing
+jq -r '.file_path' manifest.jsonl | xargs wc -l
+```
+
+---
+
+## lnav -- Log File Navigator
+
+Interactive terminal-based log viewer with SQL support, automatic format detection, timeline view, and filtering. Ideal for exploratory analysis.
+
+### Installation
+
+```bash
+# macOS
+brew install lnav
+
+# Ubuntu/Debian
+sudo apt install lnav
+
+# Windows (via Chocolatey)
+choco install lnav
+
+# From source
+curl -LO https://github.com/tstack/lnav/releases/download/v0.12.2/lnav-0.12.2-linux-musl-x86_64.zip
+unzip lnav-0.12.2-linux-musl-x86_64.zip
+sudo cp lnav-0.12.2/lnav /usr/local/bin/
+
+# Verify
+lnav -V
+```
+
+### Key Features
+
+| Feature | Access | Description |
+|---------|--------|-------------|
+| Auto-detect format | Automatic | Recognizes syslog, Apache, nginx, JSON, and many more |
+| SQL queries | `:` then SQL | Run SQL against log data |
+| Filter in/out | `i` / `o` | Interactive include/exclude filters |
+| Bookmarks | `m` | Mark lines for later reference |
+| Timeline | `t` | Show time histogram |
+| Pretty print | `p` | Toggle pretty-printing JSON |
+| Headless mode | `-n -c "..."` | Non-interactive command execution |
+| Compressed files | Automatic | Handles .gz, .bz2, .xz transparently |
+
+### Essential Commands
+
+```bash
+# Open log file(s)
+lnav app.log
+lnav /var/log/syslog /var/log/auth.log   # multiple files, merged by timestamp
+
+# Open JSONL logs
+lnav app.jsonl
+
+# Open compressed logs
+lnav app.log.gz
+
+# Open all logs in a directory
+lnav /var/log/myapp/
+
+# Headless mode: run query and output results
+lnav -n -c ";SELECT count(*) FROM logline WHERE log_level = 'error'" app.log
+
+# Headless mode: filter and export
+lnav -n -c ";SELECT log_time, log_body FROM logline WHERE log_level = 'error'" \
+  -c ":write-csv-to errors.csv" app.log
+
+# Headless mode: get stats
+lnav -n -c ";SELECT log_level, count(*) as cnt FROM logline GROUP BY log_level ORDER BY cnt DESC" app.log
+```
+
+### SQL Mode Recipes
+
+```sql
+-- Error count by hour
+SELECT strftime('%Y-%m-%d %H', log_time) as hour, count(*) as errors
+FROM logline WHERE log_level = 'error'
+GROUP BY hour ORDER BY hour;
+
+-- Top error messages
+SELECT log_body, count(*) as cnt
+FROM logline WHERE log_level = 'error'
+GROUP BY log_body ORDER BY cnt DESC LIMIT 10;
+
+-- Time between events
+SELECT log_time, log_body,
+  julianday(log_time) - julianday(lag(log_time) OVER (ORDER BY log_time)) as gap_days
+FROM logline WHERE log_level = 'error';
+
+-- Log volume over time
+SELECT strftime('%Y-%m-%d %H:%M', log_time) as minute, count(*) as lines
+FROM logline
+GROUP BY minute ORDER BY minute;
+```
+
+### Custom Log Formats
+
+```json
+// ~/.lnav/formats/installed/myapp.json
+{
+  "myapp_log": {
+    "title": "My Application Log",
+    "regex": {
+      "std": {
+        "pattern": "^(?<timestamp>\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2})\\s+\\[(?<level>\\w+)\\]\\s+(?<body>.*)"
+      }
+    },
+    "timestamp-format": ["%Y-%m-%dT%H:%M:%S"],
+    "level": {
+      "error": "ERROR",
+      "warning": "WARN",
+      "info": "INFO",
+      "debug": "DEBUG"
+    }
+  }
+}
+```
+
+### Interactive Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `/` | Search forward (regex) |
+| `n` / `N` | Next/previous search match |
+| `i` | Toggle filter: show only matching lines |
+| `o` | Toggle filter: hide matching lines |
+| `TAB` | Switch between views (log, text, help) |
+| `t` | Toggle timeline histogram |
+| `m` | Set bookmark on current line |
+| `u` / `U` | Next/previous bookmark |
+| `z` / `Z` | Zoom in/out on timeline |
+| `p` | Toggle pretty-print for JSON |
+| `e` / `E` | Next/previous error |
+| `w` / `W` | Next/previous warning |
+| `:` | Enter command mode |
+| `;` | Enter SQL query mode |
+
+---
+
+## angle-grinder (agrind) -- Log Pipeline Aggregation
+
+Pipeline-based aggregation tool designed for log analysis. Think SQL-like queries in a streaming pipeline syntax.
+
+### Installation
+
+```bash
+# Via cargo (all platforms)
+cargo install ag
+
+# macOS
+brew install angle-grinder
+
+# Verify
+agrind --version
+```
+
+### Pipeline Syntax
+
+```
+<input_pattern> | <operator1> | <operator2> | ...
+```
+
+### Essential Commands
+
+```bash
+# Count log levels
+cat app.log | agrind '* | parse "* [*] *" as ts, level, msg | count by level'
+
+# Top URLs
+cat access.log | agrind '* | parse "* * * * * * *" as ip, _, _, ts, method, url, status | count by url | sort by _count desc | head 10'
+
+# Average response time by endpoint
+cat access.log | agrind '* | parse "* *ms" as prefix, duration | avg of duration by prefix'
+
+# Error frequency over time
+cat app.log | agrind '* | parse "*T*:*:* [ERROR]*" as date, hour, min, sec, msg | count by hour'
+
+# Filter then aggregate
+cat app.log | agrind '* | where level == "error" | count by msg | sort by _count desc'
+
+# JSON log fields
+cat app.jsonl | agrind '* | json | where level == "error" | count by message'
+```
+
+### Operators Reference
+
+| Operator | Purpose | Example |
+|----------|---------|---------|
+| `parse` | Extract fields with pattern | `parse "* [*] *" as a, b, c` |
+| `json` | Parse JSON log lines | `json` |
+| `where` | Filter rows | `where level == "error"` |
+| `count` | Count (optionally by group) | `count by level` |
+| `sum` | Sum a field | `sum of bytes` |
+| `avg` | Average a field | `avg of duration` |
+| `min` / `max` | Min/max of field | `min of response_time` |
+| `sort` | Sort results | `sort by _count desc` |
+| `head` | Limit results | `head 10` |
+| `uniq` | Unique values | `uniq by user_id` |
+| `percentile` | Percentile calc | `p50 of duration, p99 of duration` |
+
+---
+
+## rg (ripgrep) -- Fast Pattern Search
+
+Already covered extensively in file-search skill. Here are log-specific flags and patterns.
+
+### Log-Specific Flags
+
+| Flag | Purpose | Example |
+|------|---------|---------|
+| `-c` | Count matches per file | `rg -c "ERROR" /var/log/*.log` |
+| `-l` | List files with matches | `rg -l "timeout" /var/log/` |
+| `-L` | List files without matches | `rg -L "healthy" /var/log/` |
+| `--stats` | Show match statistics | `rg --stats "error" app.log` |
+| `-A N` | Show N lines after match | `rg -A5 "Exception" app.log` |
+| `-B N` | Show N lines before match | `rg -B3 "FATAL" app.log` |
+| `-C N` | Show N lines context | `rg -C5 "crash" app.log` |
+| `-U` | Multiline matching | `rg -U "Error.*\n.*at " app.log` |
+| `--json` | JSON output format | `rg --json "error" app.log` |
+| `-a` | Search binary files | `rg -a "pattern" binary.log` |
+| `--line-buffered` | Flush per line (for tail) | `tail -f app.log \| rg --line-buffered "error"` |
+| `-F` | Fixed string (no regex) | `rg -F "stack[0]" app.log` |
+| `-f FILE` | Patterns from file | `rg -f patterns.txt app.log` |
+| `-v` | Invert match | `rg -v "DEBUG" app.log` |
+
+### Log Search Recipes
+
+```bash
+# Find errors across all log files recursively
+rg "ERROR|FATAL|CRITICAL" /var/log/
+
+# Count errors per file, sorted
+rg -c "ERROR" /var/log/ 2>/dev/null | sort -t: -k2 -rn
+
+# Find stack traces (multiline)
+rg -U "Exception.*\n(\s+at .*\n)+" app.log
+
+# Extract timestamps of errors
+rg "ERROR" app.log | rg -o "^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}"
+
+# Search compressed log files
+rg -z "error" app.log.gz
+
+# Search JSONL for specific field value (text-level, fast but approximate)
+rg '"level":"error"' app.jsonl
+
+# Search JSONL for value in specific key (avoid matching wrong key)
+rg '"user_id":"user-42"' app.jsonl
+
+# Negative lookahead: errors that are NOT timeouts
+rg "ERROR(?!.*timeout)" app.log
+
+# Time-bounded search (extract lines between two timestamps)
+rg "2026-03-08T1[4-5]:" app.log
+```
+
+### rg JSON Output Mode
+
+```bash
+# Get structured output from rg (useful for programmatic processing)
+rg --json "error" app.log | jq -c 'select(.type == "match") | {file: .data.path.text, line: .data.line_number, text: .data.lines.text}'
+
+# Count matches with file info
+rg --json "error" app.log | jq -c 'select(.type == "summary") | .data.stats'
+```
+
+---
+
+## awk -- Column-Based Log Processing
+
+Pre-installed on all Unix systems. Best for space/tab delimited logs with consistent column structure.
+
+### Common Recipes
+
+```bash
+# Apache/nginx combined log format columns:
+# $1=IP $2=ident $3=user $4=date $5=time $6=tz $7=method $8=path $9=proto $10=status $11=size
+
+# Status code distribution
+awk '{print $9}' access.log | sort | uniq -c | sort -rn
+
+# Requests per IP
+awk '{print $1}' access.log | sort | uniq -c | sort -rn | head -20
+
+# 5xx errors with paths
+awk '$9 >= 500 {print $1, $9, $7}' access.log
+
+# Average response size
+awk '{sum += $10; n++} END {printf "Avg: %.0f bytes\n", sum/n}' access.log
+
+# Requests per minute
+awk '{print substr($4, 2, 17)}' access.log | sort | uniq -c | tail -20
+
+# Bandwidth by path
+awk '{bytes[$7] += $10} END {for (p in bytes) printf "%10d %s\n", bytes[p], p}' access.log | sort -rn | head -20
+
+# Custom delimiter (e.g., pipe-separated)
+awk -F'|' '{print $3, $5}' custom.log
+
+# Time-range filter (syslog format)
+awk '/^Mar  8 14:/ {print}' syslog
+
+# Calculate time difference between first and last line
+awk 'NR==1 {first=$1" "$2} END {last=$1" "$2; print "From:", first, "To:", last}' app.log
+```
+
+### awk for Key-Value Logs
+
+```bash
+# Parse key=value format (logfmt)
+awk '{
+  for (i=1; i<=NF; i++) {
+    split($i, kv, "=")
+    if (kv[1] == "duration") sum += kv[2]; n++
+  }
+} END {print "avg_duration=" sum/n}' app.log
+
+# Extract specific key from logfmt
+awk '{
+  for (i=1; i<=NF; i++) {
+    split($i, kv, "=")
+    if (kv[1] == "status" && kv[2] >= 500) print $0
+  }
+}' app.log
+```
+
+---
+
+## GNU parallel -- Parallel Log Processing
+
+Splits work across CPU cores for processing large log files.
+
+### Installation
+
+```bash
+# macOS
+brew install parallel
+
+# Ubuntu/Debian
+sudo apt install parallel
+
+# Verify
+parallel --version
+```
+
+### Essential Commands
+
+```bash
+# Process multiple log files in parallel
+ls /var/log/app-*.jsonl | parallel "jq -c 'select(.level == \"error\")' {} > {.}_errors.jsonl"
+
+# Split large file and process chunks in parallel
+split -l 200000 huge.jsonl /tmp/chunk_
+ls /tmp/chunk_* | parallel "jq -r '.message' {} | sort | uniq -c" | sort -rn | head -20
+
+# Parallel grep across many files
+fd -e jsonl . /var/log/ | parallel "rg -c '\"error\"' {} 2>/dev/null" | sort -t: -k2 -rn
+
+# Pipe-based parallelism (no temp files)
+parallel --pipe -L 50000 "jq -c 'select(.level == \"error\")'" < huge.jsonl > errors.jsonl
+
+# Parallel with progress bar
+ls /var/log/app-*.jsonl | parallel --bar "jq -sc 'length' {}" | awk '{sum+=$1} END {print sum, "total lines"}'
+
+# Number of jobs (default: CPU cores)
+ls *.jsonl | parallel -j 4 "jq -c 'select(.status >= 500)' {}"
+```
+
+### Combining with split
+
+```bash
+# Full workflow: split, process in parallel, merge results
+FILE=huge.jsonl
+CHUNKS=/tmp/log_chunks
+mkdir -p "$CHUNKS"
+
+# Split
+split -l 100000 "$FILE" "$CHUNKS/chunk_"
+
+# Process in parallel
+ls "$CHUNKS"/chunk_* | parallel "jq -r 'select(.level == \"error\") | .message' {}" |
+  sort | uniq -c | sort -rn > error_summary.txt
+
+# Cleanup
+rm -rf "$CHUNKS"
+```
+
+---
+
+## Miller (mlr) -- CSV/TSV Log Analysis
+
+Like awk, sed, and jq combined but specifically for structured record data (CSV, TSV, JSON).
+
+### Installation
+
+```bash
+# macOS
+brew install miller
+
+# Ubuntu/Debian
+sudo apt install miller
+
+# Windows
+choco install miller
+
+# Verify
+mlr --version
+```
+
+### Essential Commands
+
+```bash
+# View CSV with headers
+mlr --csv head -n 10 access_log.csv
+
+# Filter rows
+mlr --csv filter '$status >= 400' access_log.csv
+
+# Sort by column
+mlr --csv sort-by -nr duration access_log.csv
+
+# Statistics
+mlr --csv stats1 -a min,max,mean,p95 -f duration access_log.csv
+
+# Group by with stats
+mlr --csv stats1 -a count,mean -f duration -g endpoint access_log.csv
+
+# Convert formats
+mlr --c2j cat access_log.csv          # CSV to JSON
+mlr --c2t cat access_log.csv          # CSV to TSV (table)
+mlr --j2c cat access_log.json         # JSON to CSV
+mlr --c2p cat access_log.csv          # CSV to pretty-print table
+
+# Top-N by group
+mlr --csv top -n 5 -f duration -g endpoint access_log.csv
+
+# Add computed fields
+mlr --csv put '$error = ($status >= 400 ? "yes" : "no")' access_log.csv
+
+# Decimate (sample every Nth row)
+mlr --csv sample -k 100 huge_log.csv
+
+# Uniq count
+mlr --csv count-distinct -f status access_log.csv
+
+# Histogram
+mlr --csv decimate -g status -n 1 access_log.csv | mlr --csv count-distinct -f status
+
+# Join two CSV files
+mlr --csv join -j user_id -f users.csv then sort-by user_id access_log.csv
+```
+
+### TSV from jq to mlr Pipeline
+
+```bash
+# Extract JSONL to TSV, then use mlr for analysis
+jq -r '[.timestamp, .level, .duration_ms, .path] | @tsv' app.jsonl > /tmp/extracted.tsv
+mlr --tsvlite --from /tmp/extracted.tsv \
+  label timestamp,level,duration_ms,path then \
+  filter '$level == "error"' then \
+  stats1 -a count,mean -f duration_ms -g path then \
+  sort-by -nr count
+```
+
+---
+
+## Tool Integration Cheat Sheet
+
+### Combining Tools
+
+```bash
+# fd + rg + jq: find files, prefilter, extract
+fd -e jsonl . logs/ | xargs rg -l '"error"' | xargs jq -c 'select(.level == "error") | {ts: .timestamp, msg: .message}'
+
+# rg + jq + column: search, extract, format
+rg '"timeout"' app.jsonl | jq -r '[.timestamp, .service, .message] | @tsv' | column -t
+
+# jq + sort + uniq: aggregate without slurp
+jq -r '.error_type' errors.jsonl | sort | uniq -c | sort -rn
+
+# tail + rg + jq: live monitoring with extraction
+tail -f app.jsonl | rg --line-buffered '"error"' | jq --unbuffered -r '[.timestamp, .message] | @tsv'
+
+# fd + parallel + jq: parallel extraction across many files
+fd -e jsonl . logs/ | parallel "jq -c 'select(.level == \"error\")' {}" > all_errors.jsonl
+
+# jq + mlr: structured extraction then statistical analysis
+jq -r '[.path, .duration_ms, .status] | @csv' app.jsonl | \
+  mlr --csv label path,duration,status then \
+  stats1 -a p50,p95,p99 -f duration -g path then \
+  sort-by -nr p95
+
+# lnav + headless SQL: non-interactive queries
+lnav -n -c ";SELECT log_level, count(*) FROM logline GROUP BY log_level" app.log
+```
+
+### Decision Guide: Which Combination?
+
+```
+Task: Explore unknown log file
+  --> lnav (interactive, auto-detects format)
+
+Task: Quick search for pattern
+  --> rg "pattern" file.log
+
+Task: Extract fields from JSONL
+  --> jq -r '[.field1, .field2] | @tsv' file.jsonl
+
+Task: Count/aggregate JSONL (<100MB)
+  --> jq -sc 'group_by(.x) | map(...)' file.jsonl
+
+Task: Count/aggregate JSONL (>100MB)
+  --> jq -r '.field' file.jsonl | sort | uniq -c | sort -rn
+
+Task: Search large JSONL then extract
+  --> rg "pattern" file.jsonl | jq -r '.field'
+
+Task: CSV/TSV log statistics
+  --> mlr --csv stats1 -a mean,p95 -f duration file.csv
+
+Task: Process many log files in parallel
+  --> fd -e jsonl . dir/ | parallel "jq ..."
+
+Task: Pipeline aggregation on text logs
+  --> cat file.log | agrind '* | parse ... | count by ...'
+
+Task: Live monitoring with filtering
+  --> tail -f file.jsonl | rg --line-buffered "x" | jq --unbuffered '.'
+```

skills/migrate-ops/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: migrate-ops
+description: "Framework and language migration patterns - version upgrades, breaking changes, dependency audit, safe rollback. Use for: migrate, migration, upgrade, version bump, breaking changes, deprecation, dependency audit, npm audit, pip-audit, codemod, jscodeshift, rector, rollback, semver, changelog, framework upgrade, language upgrade, React 19, Vue 3, Next.js App Router, Laravel 11, Angular, Python 3.12, Node 22, TypeScript 5, Go 1.22, Rust 2024, PHP 8.4."
+allowed-tools: "Read Edit Write Bash Glob Grep Agent"
+related-skills: [testing-ops, debug-ops, git-workflow, refactor-ops]
+---
+
+# Migrate Operations
+
+Comprehensive migration skill covering framework upgrades, language version bumps, dependency auditing, breaking change detection, codemods, and rollback strategies.
+
+## Migration Strategy Decision Tree
+
+```
+What kind of migration are you performing?
+│
+├─ Small library update (patch/minor version)
+│  └─ In-place upgrade
+│     Update dependency, run tests, deploy
+│
+├─ Major framework version (React 18→19, Vue 2→3, Laravel 10→11)
+│  │
+│  ├─ Codebase < 50k LOC, good test coverage (>70%)
+│  │  └─ Big Bang Migration
+│  │     Upgrade everything at once in a feature branch
+│  │     Pros: clean cutover, no dual-version complexity
+│  │     Cons: high risk, long branch life, merge conflicts
+│  │
+│  ├─ Codebase > 50k LOC, partial test coverage
+│  │  └─ Incremental Migration
+│  │     Upgrade module by module, use compatibility layers
+│  │     Pros: lower risk per step, continuous delivery
+│  │     Cons: dual-version code, longer total duration
+│  │
+│  ├─ Monolith → microservice or complete architecture shift
+│  │  └─ Strangler Fig Pattern
+│  │     Route new features to new system, migrate old features gradually
+│  │     Pros: zero-downtime, reversible, production-validated
+│  │     Cons: routing complexity, data sync challenges
+│  │
+│  └─ High-risk data pipeline or financial system
+│     └─ Parallel Run
+│        Run old and new systems simultaneously, compare outputs
+│        Pros: highest confidence, catch subtle differences
+│        Cons: double infrastructure cost, comparison logic
+│
+└─ Language version upgrade (Python 3.9→3.12, Node 18→22)
+   └─ In-place upgrade with CI matrix
+      Test against both old and new versions in CI
+      Drop old version support once all tests pass
+```
+
+## Framework Upgrade Decision Tree
+
+```
+Which framework are you upgrading?
+│
+├─ React 18 → 19
+│  ├─ Check: Remove forwardRef wrappers (ref is now a regular prop)
+│  ├─ Check: Replace <Context.Provider> with <Context>
+│  ├─ Check: Adopt useActionState / useFormStatus for forms
+│  ├─ Check: Replace manual memoization if using React Compiler
+│  ├─ Codemod: npx codemod@latest react/19/migration-recipe
+│  └─ Load: ./references/framework-upgrades.md
+│
+├─ Next.js Pages Router → App Router
+│  ├─ Check: Move pages/ to app/ with new file conventions
+│  ├─ Check: Replace getServerSideProps/getStaticProps with async components
+│  ├─ Check: Convert _app.tsx and _document.tsx to layout.tsx
+│  ├─ Check: Update data fetching to use fetch() with caching options
+│  ├─ Codemod: npx @next/codemod@latest
+│  └─ Load: ./references/framework-upgrades.md
+│
+├─ Vue 2 → 3
+│  ├─ Check: Replace Options API with Composition API (optional but recommended)
+│  ├─ Check: Replace Vuex with Pinia
+│  ├─ Check: Replace event bus with mitt or provide/inject
+│  ├─ Check: Update v-model syntax (modelValue prop)
+│  ├─ Tool: Migration build (@vue/compat) for incremental migration
+│  └─ Load: ./references/framework-upgrades.md
+│
+├─ Laravel 10 → 11
+│  ├─ Check: Adopt slim application skeleton
+│  ├─ Check: Update config file structure (consolidated configs)
+│  ├─ Check: Review per-second scheduling changes
+│  ├─ Check: Update Dumpable trait usage
+│  ├─ Tool: laravel shift (automated upgrade service)
+│  └─ Load: ./references/framework-upgrades.md
+│
+├─ Angular (any major version)
+│  ├─ Check: Run ng update for guided migration
+│  ├─ Check: Review Angular Update Guide (update.angular.io)
+│  ├─ Tool: ng update @angular/core @angular/cli
+│  └─ Load: ./references/framework-upgrades.md
+│
+└─ Django (any major version)
+   ├─ Check: Run python -Wd manage.py test for deprecation warnings
+   ├─ Check: Review Django release notes for removals
+   ├─ Tool: django-upgrade (automatic fixer)
+   └─ Load: ./references/framework-upgrades.md
+```
+
+## Dependency Audit Workflow
+
+```
+Ecosystem?
+│
+├─ JavaScript / Node.js
+│  ├─ npm audit / npm audit fix
+│  ├─ npx audit-ci --moderate (CI integration)
+│  └─ Socket.dev for supply chain analysis
+│
+├─ Python
+│  ├─ pip-audit
+│  ├─ safety check
+│  └─ pip-audit --fix (auto-update vulnerable packages)
+│
+├─ Rust
+│  ├─ cargo audit
+│  └─ cargo deny check advisories
+│
+├─ Go
+│  ├─ govulncheck ./...
+│  └─ go list -m -u all (list available updates)
+│
+├─ PHP
+│  ├─ composer audit
+│  └─ composer outdated --direct
+│
+└─ Multi-ecosystem
+   └─ Trivy, Snyk, or Dependabot across all
+```
+
+## Pre-Migration Checklist
+
+```
+[ ] Test coverage measured and documented (target: >70% for critical paths)
+[ ] CI pipeline green on current version
+[ ] All dependencies up to date (or pinned with rationale)
+[ ] Database backup taken (if applicable)
+[ ] Git state clean — migration branch created from latest main
+[ ] Rollback plan documented and tested
+[ ] Breaking change list reviewed from upstream changelog
+[ ] Team notified of migration window
+[ ] Feature flags in place for gradual rollout (if applicable)
+[ ] Monitoring and alerting configured for regression detection
+[ ] Performance baseline captured (response times, memory, CPU)
+[ ] Lock file committed (package-lock.json, yarn.lock, Cargo.lock, etc.)
+```
+
+## Breaking Change Detection Patterns
+
+```
+How do you detect breaking changes?
+│
+├─ Semver Analysis
+│  ├─ Major version bump → breaking changes guaranteed
+│  ├─ Check CHANGELOG.md or BREAKING_CHANGES.md in repo
+│  └─ npm: npx npm-check-updates --target major
+│
+├─ Changelog Parsing
+│  ├─ Search for: "BREAKING", "removed", "deprecated", "renamed"
+│  ├─ GitHub: compare releases page between versions
+│  └─ Read migration guide if one exists
+│
+├─ Compiler / Runtime Warnings
+│  ├─ Enable all deprecation warnings before upgrading
+│  ├─ Python: python -Wd (turn deprecation warnings to errors)
+│  ├─ Node: node --throw-deprecation
+│  └─ TypeScript: strict mode catches type-level breaks
+│
+├─ Codemods (automated detection + fix)
+│  ├─ jscodeshift — JavaScript/TypeScript AST transforms
+│  ├─ ast-grep — language-agnostic structural search/replace
+│  ├─ rector — PHP automated refactoring
+│  ├─ gofmt / gofumpt — Go formatting changes
+│  └─ 2to3 — Python 2 to 3 (legacy)
+│
+└─ Type Checking
+   ├─ TypeScript: tsc --noEmit catches API shape changes
+   ├─ Python: mypy / pyright after upgrade
+   └─ Go: go vet ./... after upgrade
+```
+
+## Codemod Quick Reference
+
+| Ecosystem | Tool | Command | Use Case |
+|-----------|------|---------|----------|
+| **JS/TS** | jscodeshift | `npx jscodeshift -t transform.ts src/` | Custom AST transforms |
+| **JS/TS** | ast-grep | `sg --pattern 'old($$$)' --rewrite 'new($$$)'` | Structural find/replace |
+| **React** | react-codemod | `npx codemod@latest react/19/migration-recipe` | React version upgrades |
+| **Next.js** | next-codemod | `npx @next/codemod@latest` | Next.js version upgrades |
+| **Vue** | vue-codemod | `npx @vue/codemod src/` | Vue 2 to 3 transforms |
+| **PHP** | Rector | `vendor/bin/rector process src` | PHP version + framework upgrades |
+| **Python** | pyupgrade | `pyupgrade --py312-plus *.py` | Python version syntax upgrades |
+| **Python** | django-upgrade | `django-upgrade --target-version 5.0 *.py` | Django version upgrades |
+| **Go** | gofmt | `gofmt -w .` | Go formatting updates |
+| **Go** | gofix | `go fix ./...` | Go API changes |
+| **Rust** | cargo fix | `cargo fix --edition` | Rust edition migration |
+| **Multi** | ast-grep | `sg scan --rule rules.yml` | Any language with custom rules |
+
+## Rollback Strategy Decision Tree
+
+```
+Migration failed or caused issues — how to roll back?
+│
+├─ Code-only change, no data migration
+│  ├─ Small number of commits
+│  │  └─ Git Revert
+│  │     git revert --no-commit HEAD~N..HEAD && git commit
+│  │     Pros: clean history, safe for shared branches
+│  │     Cons: merge conflicts if code has diverged
+│  │
+│  └─ Entire feature branch
+│     └─ Revert merge commit
+│        git revert -m 1 <merge-commit-sha>
+│
+├─ Feature flag controlled
+│  └─ Toggle flag off
+│     Instant rollback, no deployment needed
+│     Keep old code path until new path is proven
+│
+├─ Database schema changed
+│  ├─ Reversible migration exists
+│  │  └─ Run down migration
+│  │     rails db:rollback / php artisan migrate:rollback / alembic downgrade
+│  │
+│  └─ Irreversible migration (dropped column, changed type)
+│     └─ Restore from backup + replay write-ahead log
+│        This is why you take backups BEFORE migration
+│
+└─ Infrastructure / deployment
+   ├─ Blue-Green deployment
+   │  └─ Switch traffic back to blue (old) environment
+   │
+   ├─ Canary deployment
+   │  └─ Route 100% traffic back to stable version
+   │
+   └─ Container orchestration (K8s)
+      └─ kubectl rollout undo deployment/app
+```
+
+## Common Gotchas
+
+| Gotcha | Why It Happens | Prevention |
+|--------|---------------|------------|
+| Upgrading multiple major versions at once | Each major version may have sequential breaking changes that compound | Upgrade one major version at a time, verify, then proceed |
+| Lock file not committed before migration | Cannot reproduce pre-migration dependency state | Always commit lock files; take a snapshot branch before starting |
+| Running codemods without committing first | Cannot diff what the codemod changed vs your manual changes | Commit clean state, run codemod, commit codemod changes separately |
+| Ignoring deprecation warnings in current version | Deprecated APIs are removed in next major version | Fix all deprecation warnings BEFORE upgrading |
+| Testing only happy paths after migration | Edge cases and error paths are most likely to break | Run full test suite plus manual exploratory testing |
+| Not checking transitive dependencies | A direct dep upgrade may pull in incompatible transitive deps | Use `npm ls`, `pip show`, `cargo tree` to inspect dependency tree |
+| Assuming codemods catch everything | Codemods handle common patterns, not all patterns | Review codemod output manually; check for skipped files |
+| Skipping the migration guide | Framework authors document known pitfalls and workarounds | Read the official migration guide end-to-end before starting |
+| Migrating in a long-lived branch | Main branch diverges, causing painful merge conflicts | Use feature flags for incremental migration on main |
+| Not updating CI to test both versions | CI passes on old version but new version has failures | Add matrix testing for both versions during transition |
+| Database migration without backup | Irreversible schema changes with no recovery path | Always backup before migration; test rollback procedure |
+| Forgetting to update Docker/CI base images | Code upgraded but runtime is still old version | Update Dockerfile FROM, CI config, and deployment manifests |
+
+## Reference Files
+
+| File | Contents | Lines |
+|------|----------|-------|
+| `references/framework-upgrades.md` | React 18→19, Next.js Pages→App Router, Vue 2→3, Laravel 10→11, Angular, Django upgrade paths | ~700 |
+| `references/language-upgrades.md` | Python 3.9→3.13, Node 18→22, TypeScript 4→5, Go 1.20→1.23, Rust 2021→2024, PHP 8.1→8.4 | ~600 |
+| `references/dependency-management.md` | Audit tools, update strategies, lock files, monorepo deps, supply chain security | ~550 |
+
+## See Also
+
+| Skill | When to Combine |
+|-------|----------------|
+| `testing-ops` | Ensuring test coverage before migration, writing regression tests after |
+| `debug-ops` | Diagnosing failures introduced by migration, bisecting breaking commits |
+| `git-workflow` | Branch strategy for migration, git bisect to find breaking change |
+| `refactor-ops` | Code transformations that often accompany version upgrades |
+| `ci-cd-ops` | Updating CI pipelines to test against new versions, matrix builds |
+| `container-orchestration` | Updating base images, Dockerfile changes for new runtime versions |
+| `security-ops` | Vulnerability remediation that triggers dependency upgrades |

skills/migrate-ops/references/dependency-management.md

@@ -0,0 +1,704 @@
+# Dependency Management
+
+Comprehensive guide to auditing, updating, and securing dependencies across ecosystems.
+
+---
+
+## Audit Tools by Ecosystem
+
+### JavaScript / Node.js
+
+```bash
+# Built-in npm audit
+npm audit                      # Show vulnerabilities
+npm audit fix                  # Auto-fix where possible
+npm audit fix --force          # Fix with major version bumps (risky)
+npm audit --json               # JSON output for CI parsing
+
+# npm audit in CI (fail on moderate+)
+npx audit-ci --moderate        # Fail CI on moderate or higher
+
+# Socket.dev (supply chain analysis)
+# Detects: typosquatting, install scripts, obfuscated code
+npx socket:npm info <package>
+
+# Check for outdated packages
+npm outdated                   # Show outdated direct deps
+npx npm-check-updates          # Interactive update tool
+npx npm-check-updates -u       # Update package.json
+
+# Yarn
+yarn audit
+yarn upgrade-interactive
+
+# pnpm
+pnpm audit
+pnpm update --interactive
+```
+
+### Python
+
+```bash
+# pip-audit (recommended)
+pip install pip-audit
+pip-audit                      # Scan installed packages
+pip-audit -r requirements.txt  # Scan requirements file
+pip-audit --fix                # Auto-update vulnerable packages
+pip-audit -f json              # JSON output for CI
+
+# Safety (alternative)
+pip install safety
+safety check                   # Scan installed packages
+safety check -r requirements.txt
+
+# Check outdated
+pip list --outdated
+
+# uv (fast alternative)
+uv pip list --outdated
+uv pip audit                   # If available in your uv version
+```
+
+### Rust
+
+```bash
+# cargo-audit
+cargo install cargo-audit
+cargo audit                    # Check for known vulnerabilities
+cargo audit fix                # Auto-apply fixes (where possible)
+
+# cargo-deny (comprehensive policy enforcement)
+cargo install cargo-deny
+cargo deny check advisories    # Security advisories
+cargo deny check bans          # Banned crate checks
+cargo deny check licenses      # License compliance
+cargo deny check sources       # Source restrictions
+
+# Check outdated
+cargo outdated                 # Requires cargo-outdated
+cargo update --dry-run         # Show what would update
+```
+
+### Go
+
+```bash
+# govulncheck (official Go vulnerability checker)
+go install golang.org/x/vuln/cmd/govulncheck@latest
+govulncheck ./...              # Scan project
+govulncheck -mode binary app   # Scan compiled binary
+
+# Check for updates
+go list -m -u all              # List all modules with available updates
+go get -u ./...                # Update all dependencies
+go mod tidy                    # Clean up go.sum
+
+# Nancy (Sonatype vulnerability scanner)
+go list -m -json all | nancy sleuth
+```
+
+### PHP
+
+```bash
+# Composer built-in audit
+composer audit                 # Check for known vulnerabilities
+composer audit --format=json   # JSON output for CI
+
+# Check outdated
+composer outdated              # All outdated
+composer outdated --direct     # Only direct dependencies
+
+# Symfony security checker
+composer require --dev sensiolabs/security-checker
+vendor/bin/security-checker security:check
+```
+
+### Ruby
+
+```bash
+# bundler-audit
+gem install bundler-audit
+bundle audit check             # Scan Gemfile.lock
+bundle audit update            # Update vulnerability database
+
+# Check outdated
+bundle outdated
+```
+
+### Multi-Ecosystem
+
+```bash
+# Trivy (containers, filesystems, git repos)
+trivy fs .                     # Scan current directory
+trivy image myapp:latest       # Scan container image
+trivy repo https://github.com/org/repo
+
+# Snyk
+snyk test                      # Test for vulnerabilities
+snyk monitor                   # Monitor for new vulnerabilities
+
+# OSV-Scanner (Google)
+osv-scanner -r .               # Recursive scan
+osv-scanner --lockfile=package-lock.json
+```
+
+---
+
+## Dependency Update Strategies
+
+### Automated Update Services
+
+| Service | Ecosystems | Key Features |
+|---------|-----------|-------------|
+| **Dependabot** | npm, pip, Cargo, Go, Composer, Bundler, Docker, GitHub Actions | GitHub-native, grouped updates, auto-merge rules |
+| **Renovate** | 50+ managers | Highly configurable, monorepo support, custom rules, self-hosted option |
+| **Snyk** | npm, pip, Go, Java, .NET, Ruby | Security-focused, fix PRs, runtime monitoring |
+
+### Dependabot Configuration
+
+```yaml
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 10
+    groups:
+      dev-dependencies:
+        dependency-type: development
+      minor-and-patch:
+        update-types: [minor, patch]
+    ignore:
+      - dependency-name: "aws-sdk"
+        update-types: ["version-update:semver-major"]
+
+  - package-ecosystem: docker
+    directory: "/"
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+```
+
+### Renovate Configuration
+
+```json
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended",
+    "group:allNonMajor",
+    ":automergeMinor",
+    ":automergePatch"
+  ],
+  "packageRules": [
+    {
+      "matchUpdateTypes": ["major"],
+      "automerge": false,
+      "labels": ["breaking-change"]
+    },
+    {
+      "matchDepTypes": ["devDependencies"],
+      "automerge": true
+    }
+  ],
+  "schedule": ["before 7am on Monday"]
+}
+```
+
+### Manual Update Workflow
+
+```
+When to update manually:
+│
+├─ Major version bump
+│  1. Read CHANGELOG.md / release notes
+│  2. Check for breaking changes
+│  3. Check if codemods exist
+│  4. Create feature branch
+│  5. Update dependency
+│  6. Run tests
+│  7. Fix breaking changes
+│  8. Run full CI pipeline
+│  9. Review diff carefully
+│  10. Merge when green
+│
+├─ Security patch (critical)
+│  1. Verify advisory affects your usage
+│  2. Update to patched version
+│  3. Run tests
+│  4. Deploy immediately
+│
+└─ Minor / patch version
+   1. Update dependency
+   2. Run tests
+   3. Spot-check changelog for surprises
+   4. Merge
+```
+
+---
+
+## Lock File Management
+
+### When to Regenerate Lock Files
+
+```
+Should you regenerate the lock file?
+│
+├─ Lock file has merge conflicts
+│  └─ YES: Delete lock file, reinstall, commit
+│     npm: rm package-lock.json && npm install
+│     yarn: rm yarn.lock && yarn install
+│     pnpm: rm pnpm-lock.yaml && pnpm install
+│     pip: rm requirements.txt && pip freeze > requirements.txt
+│     cargo: rm Cargo.lock && cargo generate-lockfile
+│
+├─ Dependency resolution is broken
+│  └─ YES: Delete lock file, clean cache, reinstall
+│     npm: rm -rf node_modules package-lock.json && npm cache clean --force && npm install
+│     pip: pip cache purge && pip install -r requirements.txt
+│
+├─ Routine update
+│  └─ NO: Use update commands that modify lock file in place
+│     npm update / yarn upgrade / pnpm update
+│     cargo update
+│
+└─ CI builds are inconsistent
+   └─ Check: Is lock file committed? If not, commit it.
+      Applications: ALWAYS commit lock files
+      Libraries: Commit lock files (for CI reproducibility)
+```
+
+### Lock File Conflict Resolution
+
+```bash
+# npm
+git checkout --theirs package-lock.json  # accept incoming
+npm install                              # regenerate properly
+
+# yarn
+git checkout --theirs yarn.lock
+yarn install
+
+# pnpm
+git checkout --theirs pnpm-lock.yaml
+pnpm install
+
+# Cargo
+git checkout --theirs Cargo.lock
+cargo update
+
+# Go
+git checkout --theirs go.sum
+go mod tidy
+
+# Composer
+git checkout --theirs composer.lock
+composer update --lock
+```
+
+---
+
+## Major Version Upgrade Workflow
+
+Detailed workflow for upgrading a dependency by one or more major versions.
+
+### Step 1: Research
+
+```bash
+# Read the changelog
+# GitHub: check Releases page
+# npm: npm info <package> changelog
+# Or find CHANGELOG.md / CHANGES.md / HISTORY.md in repo
+
+# Check breaking changes
+# Search for: "BREAKING", "removed", "renamed", "changed"
+# Look for migration guide
+
+# Check your usage of affected APIs
+rg "importedFunction|removedAPI" src/
+```
+
+### Step 2: Check Compatibility
+
+```bash
+# npm: check peer dependency requirements
+npm info <package>@latest peerDependencies
+
+# Check if other deps are compatible
+npm ls <package>  # see who depends on it
+
+# Python: check classifiers and python_requires
+pip show <package> | rg -i "requires"
+
+# Go: check go.mod requirements of dependency
+go mod graph | rg <module>
+```
+
+### Step 3: Update
+
+```bash
+# Create a branch
+git checkout -b upgrade/<package>-v<version>
+
+# npm
+npm install <package>@latest
+
+# pip
+pip install <package>==<version>
+
+# cargo
+cargo update -p <crate> --precise <version>
+
+# go
+go get <module>@v<version>
+go mod tidy
+
+# composer
+composer require <package>:<version>
+```
+
+### Step 4: Fix and Test
+
+```bash
+# Run type checker first (catches API shape changes)
+npx tsc --noEmit        # TypeScript
+mypy .                   # Python
+go vet ./...             # Go
+
+# Run tests
+npm test                 # Node.js
+pytest                   # Python
+cargo test               # Rust
+go test ./...            # Go
+php artisan test         # Laravel
+
+# Run linter
+npm run lint
+ruff check .
+cargo clippy
+golangci-lint run
+```
+
+### Step 5: Verify
+
+```bash
+# Build for production
+npm run build
+cargo build --release
+go build ./...
+
+# Run integration/e2e tests if available
+npm run test:e2e
+pytest tests/integration/
+```
+
+---
+
+## Monorepo Dependency Management
+
+### npm/pnpm/yarn Workspaces
+
+```bash
+# List workspace packages
+npm ls --all --workspaces
+
+# Update a dependency across all workspaces
+npm update <package> --workspaces
+
+# Install a dependency in a specific workspace
+npm install <package> --workspace=packages/core
+
+# Check for inconsistent versions across workspaces
+npx syncpack list-mismatches
+
+# Fix inconsistent versions
+npx syncpack fix-mismatches
+```
+
+### Shared Version Strategy
+
+```
+Monorepo version strategy:
+│
+├─ Single version policy (recommended for most teams)
+│  All packages use the same version of shared dependencies
+│  Enforced with: syncpack, manypkg, or Renovate grouping
+│  Pros: consistent behavior, simpler debugging
+│  Cons: all packages must be compatible with same version
+│
+├─ Independent versions
+│  Each package manages its own dependency versions
+│  Pros: flexibility, independent upgrade cycles
+│  Cons: version conflicts, larger node_modules, harder debugging
+│
+└─ Hybrid
+   Pin shared infrastructure deps (React, TypeScript)
+   Allow independent versions for leaf dependencies
+```
+
+### Turborepo / Nx Considerations
+
+```bash
+# Turborepo: ensure dependency changes trigger correct rebuilds
+# turbo.json should include package.json in inputs
+
+# Nx: use nx migrate for framework updates
+npx nx migrate latest
+npx nx migrate --run-migrations
+```
+
+---
+
+## Vendoring vs Lock Files
+
+### Decision Tree
+
+```
+Should you vendor dependencies?
+│
+├─ Deploying to air-gapped environment
+│  └─ YES: Vendor everything
+│
+├─ Registry availability is critical
+│  └─ YES: Vendor to protect against registry outages
+│
+├─ Reproducible builds without network access
+│  └─ YES: Vendor dependencies
+│
+├─ Open source library
+│  └─ NO: Use lock files, vendoring bloats the repo
+│
+├─ Standard web application
+│  └─ NO: Lock files are sufficient
+│
+└─ Go modules
+   └─ CONSIDER: Go vendor is well-supported
+      go mod vendor  # creates vendor/ directory
+      go build -mod=vendor
+```
+
+### Vendoring by Ecosystem
+
+```bash
+# Go
+go mod vendor
+# Build with: go build -mod=vendor ./...
+
+# Python (pip download)
+pip download -r requirements.txt -d vendor/
+# Install from: pip install --no-index --find-links=vendor/ -r requirements.txt
+
+# Node.js (not common, but possible)
+# Use npm pack to create tarballs
+# Or use pnpm with node_modules layout
+
+# Rust
+# Use cargo-vendor
+cargo vendor
+# Configure .cargo/config.toml to use vendored sources
+```
+
+---
+
+## License Compliance Checking
+
+### Tools
+
+```bash
+# Node.js
+npx license-checker --summary
+npx license-checker --failOn "GPL-3.0;AGPL-3.0"
+npx license-checker --production  # only production deps
+
+# Python
+pip install pip-licenses
+pip-licenses --format=table
+pip-licenses --fail-on="GPLv3;AGPL-3.0"
+
+# Rust
+cargo deny check licenses
+
+# Go
+go install github.com/google/go-licenses@latest
+go-licenses check ./...
+go-licenses report ./...
+
+# Multi-ecosystem
+# FOSSA: https://fossa.com
+# Snyk: snyk test --license
+```
+
+### License Compatibility Matrix
+
+| Your License | Compatible Dependencies | Incompatible |
+|-------------|------------------------|-------------|
+| MIT | MIT, BSD, ISC, Apache-2.0, Unlicense | - |
+| Apache-2.0 | MIT, BSD, ISC, Apache-2.0, Unlicense | GPL-2.0 (debated) |
+| GPL-3.0 | MIT, BSD, ISC, Apache-2.0, GPL-2.0, LGPL, AGPL | Proprietary |
+| Proprietary | MIT, BSD, ISC, Apache-2.0, Unlicense | GPL, AGPL, LGPL (static) |
+
+### Cargo Deny License Config
+
+```toml
+# deny.toml
+[licenses]
+allow = [
+    "MIT",
+    "Apache-2.0",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "ISC",
+    "Unicode-3.0",
+]
+deny = [
+    "AGPL-3.0",
+]
+confidence-threshold = 0.8
+```
+
+---
+
+## Supply Chain Security
+
+### npm Provenance
+
+```bash
+# Verify package provenance (npm 9.5+)
+npm audit signatures
+
+# Publish with provenance (in GitHub Actions)
+npm publish --provenance
+
+# Check a specific package
+npm view <package> --json | jq '.dist.attestations'
+```
+
+### Sigstore / cosign
+
+```bash
+# Verify container image signatures
+cosign verify --key cosign.pub myregistry/myimage:tag
+
+# Sign a container image
+cosign sign --key cosign.key myregistry/myimage:tag
+
+# Verify in CI
+cosign verify --certificate-identity user@example.com \
+  --certificate-oidc-issuer https://accounts.google.com \
+  myregistry/myimage:tag
+```
+
+### cargo-vet (Rust)
+
+```bash
+# Initialize cargo-vet
+cargo vet init
+
+# Certify a crate after review
+cargo vet certify <crate> <version>
+
+# Import trusted audits from other organizations
+cargo vet trust <organization>
+
+# Check all dependencies are vetted
+cargo vet
+```
+
+### Supply Chain Best Practices
+
+```
+Supply chain security checklist:
+│
+├─ [ ] Lock files committed and reviewed in PRs
+├─ [ ] Dependabot or Renovate configured for automated updates
+├─ [ ] npm audit / pip-audit / cargo audit in CI pipeline
+├─ [ ] npm audit signatures verified (if using npm)
+├─ [ ] Avoid running arbitrary install scripts (npm ignore-scripts)
+├─ [ ] Pin GitHub Actions to SHA, not tag
+│      Bad:  uses: actions/checkout@v4
+│      Good: uses: actions/checkout@b4ffde65f46...
+├─ [ ] Review new dependencies before adding
+│      Check: download count, maintenance activity, known issues
+├─ [ ] Use private registry or proxy for sensitive environments
+├─ [ ] Container images signed and verified
+├─ [ ] SBOM (Software Bill of Materials) generated for releases
+│      Tools: syft, cyclonedx-cli, npm sbom
+└─ [ ] Socket.dev or similar for install-time behavior analysis
+```
+
+### SBOM Generation
+
+```bash
+# Syft (Anchore)
+syft dir:. -o spdx-json > sbom.json
+syft myimage:tag -o cyclonedx-json > sbom.json
+
+# npm (built-in)
+npm sbom --sbom-format cyclonedx
+
+# CycloneDX
+# Python
+pip install cyclonedx-bom
+cyclonedx-py environment -o sbom.json
+
+# Go
+go install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@latest
+cyclonedx-gomod mod -output sbom.json
+
+# Rust
+cargo install cargo-cyclonedx
+cargo cyclonedx --format json
+```
+
+---
+
+## Dependency Update CI Integration
+
+### GitHub Actions Example
+
+```yaml
+name: Dependency Audit
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: '0 8 * * 1'  # Weekly Monday 8am
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: npm audit
+        run: npm audit --audit-level=moderate
+
+      - name: License check
+        run: npx license-checker --failOn "GPL-3.0;AGPL-3.0" --production
+
+      - name: Check for outdated deps
+        run: npm outdated || true  # informational, don't fail
+```
+
+### Pre-commit Hook
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit or via pre-commit framework
+
+# Check for new dependencies without lock file update
+if git diff --cached --name-only | rg -q "package\.json"; then
+  if ! git diff --cached --name-only | rg -q "package-lock\.json"; then
+    echo "ERROR: package.json changed but package-lock.json was not updated"
+    echo "Run: npm install"
+    exit 1
+  fi
+fi
+```

skills/migrate-ops/references/framework-upgrades.md

@@ -0,0 +1,597 @@
+# Framework Upgrade Paths
+
+Detailed upgrade procedures for major framework version transitions.
+
+---
+
+## React 18 to 19
+
+### Pre-Upgrade Checklist
+
+```
+[ ] Running React 18.3.x (last 18.x with deprecation warnings)
+[ ] All deprecation warnings resolved
+[ ] No usage of legacy string refs
+[ ] No usage of legacy context (contextTypes)
+[ ] No usage of defaultProps on function components
+[ ] No usage of propTypes at runtime
+[ ] Test suite passing on 18.3.x
+[ ] TypeScript 5.x or later (for type changes)
+```
+
+### Step-by-Step Process
+
+1. **Upgrade to React 18.3.x first** -- this version surfaces deprecation warnings for all APIs removed in 19.
+2. **Fix all deprecation warnings** before proceeding.
+3. **Run the official codemod:**
+   ```bash
+   npx codemod@latest react/19/migration-recipe --target src/
+   ```
+4. **Update package.json:**
+   ```bash
+   npm install react@19 react-dom@19
+   npm install -D @types/react@19 @types/react-dom@19
+   ```
+5. **Update react-dom entry point:**
+   ```tsx
+   // Before (React 18)
+   import { createRoot } from 'react-dom/client';
+   // After (React 19) -- same API, but check for removed APIs below
+   ```
+6. **Run tests and fix remaining issues.**
+
+### Breaking Changes
+
+| Removed API | Replacement |
+|------------|-------------|
+| `forwardRef` | Pass `ref` as a regular prop |
+| `<Context.Provider>` | Use `<Context>` directly as provider |
+| `defaultProps` on function components | Use JS default parameters |
+| `propTypes` runtime checking | Use TypeScript or Flow |
+| `react-test-renderer` | Use `@testing-library/react` |
+| `ReactDOM.render` | Use `createRoot` (already required in 18) |
+| `ReactDOM.hydrate` | Use `hydrateRoot` (already required in 18) |
+| `unmountComponentAtNode` | Use `root.unmount()` |
+| `ReactDOM.findDOMNode` | Use refs |
+
+### New APIs to Adopt
+
+```tsx
+// use() hook -- read promises and context in render
+import { use } from 'react';
+
+function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
+  const user = use(userPromise);
+  return <h1>{user.name}</h1>;
+}
+
+// useActionState -- form action with state
+import { useActionState } from 'react';
+
+function LoginForm() {
+  const [state, formAction, isPending] = useActionState(
+    async (prev: State, formData: FormData) => {
+      const result = await login(formData);
+      return result;
+    },
+    { error: null }
+  );
+  return <form action={formAction}>...</form>;
+}
+
+// useOptimistic -- optimistic updates
+import { useOptimistic } from 'react';
+
+function TodoList({ todos }: { todos: Todo[] }) {
+  const [optimisticTodos, addOptimistic] = useOptimistic(
+    todos,
+    (state, newTodo: Todo) => [...state, newTodo]
+  );
+  // ...
+}
+
+// ref as prop -- no more forwardRef
+function Input({ ref, ...props }: { ref?: React.Ref<HTMLInputElement> }) {
+  return <input ref={ref} {...props} />;
+}
+
+// Context as provider
+const ThemeContext = createContext('light');
+// Before: <ThemeContext.Provider value="dark">
+// After:
+<ThemeContext value="dark">
+  <App />
+</ThemeContext>
+```
+
+### Verification Steps
+
+```bash
+# Run type checking
+npx tsc --noEmit
+
+# Run tests
+npm test
+
+# Search for removed APIs that codemods may have missed
+rg "forwardRef" src/
+rg "Context\.Provider" src/
+rg "defaultProps" src/ --glob "*.tsx"
+rg "propTypes" src/ --glob "*.tsx"
+rg "findDOMNode" src/
+rg "react-test-renderer" package.json
+```
+
+---
+
+## Next.js Pages Router to App Router
+
+### Pre-Upgrade Checklist
+
+```
+[ ] Running latest Next.js 14.x or 15.x
+[ ] Understood Server vs Client Component model
+[ ] Identified pages that need client-side interactivity
+[ ] Reviewed data fetching strategy (no more getServerSideProps/getStaticProps)
+[ ] Identified API routes that need migration
+[ ] Middleware already using edge runtime (if applicable)
+```
+
+### Step-by-Step Process
+
+1. **Create `app/` directory** alongside existing `pages/`.
+2. **Create `app/layout.tsx`** (replaces `_app.tsx` and `_document.tsx`):
+   ```tsx
+   export default function RootLayout({ children }: { children: React.ReactNode }) {
+     return (
+       <html lang="en">
+         <body>{children}</body>
+       </html>
+     );
+   }
+   ```
+3. **Migrate pages one at a time** -- both routers work simultaneously.
+4. **Convert data fetching:**
+   ```tsx
+   // Before (Pages Router)
+   export async function getServerSideProps() {
+     const data = await fetchData();
+     return { props: { data } };
+   }
+   export default function Page({ data }) { ... }
+
+   // After (App Router)
+   export default async function Page() {
+     const data = await fetchData(); // direct async component
+     return <div>{data}</div>;
+   }
+   ```
+5. **Convert dynamic routes:**
+   ```
+   pages/posts/[id].tsx  →  app/posts/[id]/page.tsx
+   pages/[...slug].tsx   →  app/[...slug]/page.tsx
+   ```
+6. **Run the official codemod:**
+   ```bash
+   npx @next/codemod@latest
+   ```
+
+### File Convention Changes
+
+| Pages Router | App Router | Purpose |
+|-------------|-----------|---------|
+| `pages/index.tsx` | `app/page.tsx` | Home page |
+| `pages/about.tsx` | `app/about/page.tsx` | Static page |
+| `pages/posts/[id].tsx` | `app/posts/[id]/page.tsx` | Dynamic page |
+| `pages/_app.tsx` | `app/layout.tsx` | Root layout |
+| `pages/_document.tsx` | `app/layout.tsx` | HTML document |
+| `pages/_error.tsx` | `app/error.tsx` | Error boundary |
+| `pages/404.tsx` | `app/not-found.tsx` | Not found page |
+| `pages/api/hello.ts` | `app/api/hello/route.ts` | API route |
+| N/A | `app/loading.tsx` | Loading UI (new) |
+| N/A | `app/template.tsx` | Re-mounted layout (new) |
+
+### Data Fetching Migration
+
+| Pages Router | App Router |
+|-------------|-----------|
+| `getServerSideProps` | `async` Server Component (fetches on every request) |
+| `getStaticProps` | `async` Server Component + `fetch` with `cache: 'force-cache'` |
+| `getStaticPaths` | `generateStaticParams()` |
+| `getInitialProps` | Remove entirely -- use Server Components |
+| `useRouter().query` | `useSearchParams()` (client) or `searchParams` prop (server) |
+
+### Common Breaking Changes
+
+- `useRouter` from `next/navigation` not `next/router`
+- `pathname` no longer includes query parameters
+- `Link` no longer requires `<a>` child
+- CSS Modules class names may differ
+- `Image` component default behavior changes
+- Metadata API replaces `<Head>` component
+- Route handlers replace API routes (different request/response model)
+
+### Verification Steps
+
+```bash
+# Check for Pages Router imports in migrated files
+rg "from 'next/router'" app/
+rg "getServerSideProps|getStaticProps|getInitialProps" app/
+rg "next/head" app/
+
+# Verify all routes work
+npm run build  # catches most issues at build time
+npm run dev    # test interactive behavior
+```
+
+---
+
+## Vue 2 to 3
+
+### Pre-Upgrade Checklist
+
+```
+[ ] Identified all breaking syntax changes (v-model, filters, events)
+[ ] Listed third-party Vue 2 plugins that need Vue 3 equivalents
+[ ] Decided on migration approach: migration build (@vue/compat) vs direct
+[ ] Decided on state management: Vuex → Pinia migration
+[ ] Test suite passing on Vue 2
+```
+
+### Step-by-Step Process (Using Migration Build)
+
+1. **Upgrade to Vue 2.7** first (backports Composition API, `<script setup>`).
+2. **Start adopting Composition API** in Vue 2.7 where convenient.
+3. **Switch to Vue 3 + @vue/compat:**
+   ```bash
+   npm install vue@3 @vue/compat
+   ```
+4. **Configure compat mode** in bundler (Vite or Webpack):
+   ```js
+   // vite.config.js
+   export default {
+     resolve: {
+       alias: { vue: '@vue/compat' }
+     }
+   };
+   ```
+5. **Fix compatibility warnings** one category at a time.
+6. **Remove `@vue/compat`** once all warnings are resolved.
+
+### Breaking Changes
+
+| Vue 2 | Vue 3 | Notes |
+|-------|-------|-------|
+| `v-model` (default) | `v-model` uses `modelValue` prop + `update:modelValue` event | Custom `model` option removed |
+| `v-bind.sync` | `v-model:propName` | `.sync` modifier removed |
+| Filters `{{ value \| filter }}` | Methods or computed | Filters removed entirely |
+| `$on`, `$off`, `$once` | External library (mitt) | Event bus pattern removed |
+| `Vue.component()` global | `app.component()` | Global API restructured |
+| `Vue.use()` | `app.use()` | Plugin installation |
+| `Vue.mixin()` | `app.mixin()` or Composition API | Global mixins |
+| `Vue.filter()` | N/A | Filters removed |
+| `this.$set` / `Vue.set` | Direct assignment | Reactivity system rewritten (Proxy-based) |
+| `this.$delete` / `Vue.delete` | `delete obj.prop` | Proxy handles this |
+| `$listeners` | Merged into `$attrs` | Separate `$listeners` removed |
+| `$children` | Template refs | Direct child access removed |
+| `<transition>` class names | `v-enter-from` / `v-leave-from` | `-active` suffix retained |
+
+### Vuex to Pinia Migration
+
+```ts
+// Vuex (old)
+const store = createStore({
+  state: { count: 0 },
+  mutations: { increment(state) { state.count++; } },
+  actions: { asyncIncrement({ commit }) { commit('increment'); } },
+  getters: { doubleCount: (state) => state.count * 2 }
+});
+
+// Pinia (new)
+export const useCounterStore = defineStore('counter', () => {
+  const count = ref(0);
+  const doubleCount = computed(() => count.value * 2);
+  function increment() { count.value++; }
+  async function asyncIncrement() { increment(); }
+  return { count, doubleCount, increment, asyncIncrement };
+});
+```
+
+### Available Codemods
+
+```bash
+# Vue official codemod
+npx @vue/codemod src/
+
+# Specific transforms
+npx @vue/codemod src/ --transform vue-class-component-v8
+npx @vue/codemod src/ --transform new-global-api
+npx @vue/codemod src/ --transform vue-router-v4
+```
+
+### Verification Steps
+
+```bash
+# Search for Vue 2 patterns
+rg "\$on\(|\.sync|Vue\.component|Vue\.use|Vue\.mixin" src/
+rg "this\.\$set|this\.\$delete|this\.\$children" src/
+rg "filters:" src/ --glob "*.vue"
+rg "v-bind\.sync" src/ --glob "*.vue"
+
+# Build and test
+npm run build
+npm test
+```
+
+---
+
+## Laravel 10 to 11
+
+### Pre-Upgrade Checklist
+
+```
+[ ] Running PHP 8.2+ (Laravel 11 requires PHP 8.2 minimum)
+[ ] All tests passing on Laravel 10
+[ ] Reviewed Laravel 11 release notes
+[ ] Identified custom service providers that need updates
+[ ] Checked third-party package Laravel 11 compatibility
+```
+
+### Step-by-Step Process
+
+1. **Use Laravel Shift** (recommended, paid automated service):
+   ```
+   https://laravelshift.com
+   ```
+2. **Or manual upgrade -- update composer.json:**
+   ```json
+   {
+     "require": {
+       "laravel/framework": "^11.0"
+     }
+   }
+   ```
+3. **Run composer update:**
+   ```bash
+   composer update
+   ```
+4. **Apply skeleton changes** (Laravel 11 uses a slimmer skeleton):
+   - `bootstrap/app.php` is simplified
+   - Many config files removed from `config/` (use defaults)
+   - Service providers consolidated
+   - Middleware moved to `bootstrap/app.php`
+   - `app/Http/Kernel.php` removed
+5. **Fix deprecation warnings and test.**
+
+### Breaking Changes
+
+| Laravel 10 | Laravel 11 | Notes |
+|-----------|-----------|-------|
+| `app/Http/Kernel.php` | `bootstrap/app.php` | Middleware registration moved |
+| Multiple service providers | Single `AppServiceProvider` | Consolidated providers |
+| Full `config/` directory | Minimal config (publish as needed) | `php artisan config:publish` to restore |
+| Console `Kernel.php` | `routes/console.php` with closures | Schedule defined in `routes/console.php` |
+| Exception handler class | `bootstrap/app.php` withExceptions() | Exception handling consolidated |
+| `$schedule->command()->everyMinute()` | `->everySecond()` now available | Per-second scheduling added |
+| Explicit casts property | `casts()` method on model | Method-based casting |
+
+### New Features to Adopt
+
+```php
+// Per-second scheduling
+Schedule::command('check:pulse')->everySecond();
+
+// Dumpable trait
+use Illuminate\Support\Traits\Dumpable;
+
+class MyService {
+    use Dumpable;
+    // Now supports ->dd() and ->dump() chaining
+}
+
+// Method-based casts
+protected function casts(): array {
+    return [
+        'options' => AsArrayObject::class,
+        'created_at' => 'datetime:Y-m-d',
+    ];
+}
+
+// Simplified bootstrap/app.php
+return Application::configure(basePath: dirname(__DIR__))
+    ->withRouting(
+        web: __DIR__.'/../routes/web.php',
+        api: __DIR__.'/../routes/api.php',
+    )
+    ->withMiddleware(function (Middleware $middleware) {
+        $middleware->web(append: [CustomMiddleware::class]);
+    })
+    ->withExceptions(function (Exceptions $exceptions) {
+        $exceptions->report(function (SomeException $e) {
+            // custom reporting
+        });
+    })
+    ->create();
+```
+
+### Verification Steps
+
+```bash
+# Check for removed patterns
+rg "class Kernel extends HttpKernel" app/
+rg "class Handler extends ExceptionHandler" app/
+
+# Run tests
+php artisan test
+
+# Check config
+php artisan config:show
+
+# Verify routes
+php artisan route:list
+```
+
+---
+
+## Angular Version Upgrades
+
+### Pre-Upgrade Checklist
+
+```
+[ ] Check Angular Update Guide: https://update.angular.io
+[ ] Running the latest patch of current major version
+[ ] All tests passing
+[ ] No deprecated APIs in use (check ng build warnings)
+[ ] Third-party libraries checked for target version compatibility
+```
+
+### Step-by-Step Process
+
+1. **Check the update guide** for your specific version jump:
+   ```
+   https://update.angular.io/?from=16.0&to=17.0
+   ```
+2. **Run ng update** for core packages:
+   ```bash
+   ng update @angular/core @angular/cli
+   ```
+3. **Run ng update** for additional Angular packages:
+   ```bash
+   ng update @angular/material  # if using Material
+   ng update @angular/router    # if needed
+   ```
+4. **Review and apply schematics** that ng update runs automatically.
+5. **Fix any remaining issues** and run tests.
+
+### Recent Major Changes by Version
+
+| Version | Key Changes |
+|---------|-------------|
+| **14** | Standalone components, typed forms, inject() function |
+| **15** | Standalone APIs stable, directive composition, image optimization |
+| **16** | Signals (developer preview), required inputs, esbuild builder |
+| **17** | Signals stable, deferrable views, built-in control flow, esbuild default |
+| **18** | Zoneless change detection (experimental), Material 3, fallback content |
+| **19** | Standalone by default, linked signals, resource API, incremental hydration |
+
+### Common Pitfalls
+
+- **RxJS version**: Angular often requires specific RxJS versions. Check compatibility.
+- **TypeScript version**: Each Angular major requires a specific TS range.
+- **Zone.js**: Being phased out in favor of signals. Plan accordingly.
+- **Module vs Standalone**: Newer versions push toward standalone components.
+
+### Verification Steps
+
+```bash
+ng build --configuration=production
+ng test
+ng e2e
+
+# Check for deprecation warnings in build output
+ng build 2>&1 | rg -i "deprecated|warning"
+```
+
+---
+
+## Django Version Upgrades
+
+### Pre-Upgrade Checklist
+
+```
+[ ] Running the latest patch of current major version
+[ ] All deprecation warnings resolved
+[ ] Tests passing with python -Wd (warnings as errors)
+[ ] Third-party packages checked for target version support
+[ ] Database migrations up to date
+```
+
+### Step-by-Step Process
+
+1. **Enable deprecation warnings:**
+   ```bash
+   python -Wd manage.py test
+   ```
+2. **Fix all deprecation warnings** on current version.
+3. **Read release notes** for target version:
+   ```
+   https://docs.djangoproject.com/en/5.0/releases/
+   ```
+4. **Update Django:**
+   ```bash
+   pip install Django==5.0
+   ```
+5. **Run django-upgrade codemod:**
+   ```bash
+   pip install django-upgrade
+   django-upgrade --target-version 5.0 $(fd -e py)
+   ```
+6. **Run tests and fix issues.**
+
+### Recent Major Changes by Version
+
+| Version | Key Changes |
+|---------|-------------|
+| **4.0** | Redis cache backend, `scrypt` hasher, template-based form rendering |
+| **4.1** | Async ORM, `async` view support, validation of model constraints |
+| **4.2** | Psycopg 3, `STORAGES` setting, custom file storage |
+| **5.0** | Facet filters in admin, simplified templates, database-computed default |
+| **5.1** | LoginRequiredMiddleware, connection pool for PostgreSQL |
+
+### Available Codemods
+
+```bash
+# django-upgrade: automated fixes
+pip install django-upgrade
+django-upgrade --target-version 5.0 **/*.py
+
+# Specific transforms handled:
+# - url() to path() in urlconfs
+# - @admin.register decorator
+# - HttpResponse charset parameter
+# - Deprecated model field arguments
+```
+
+### Verification Steps
+
+```bash
+# Full test suite with warnings
+python -Wd manage.py test
+
+# Check for deprecated imports
+rg "from django.utils.encoding import force_text" .
+rg "from django.conf.urls import url" .
+rg "from django.utils.translation import ugettext" .
+
+# Verify migrations
+python manage.py makemigrations --check
+python manage.py migrate --run-syncdb
+
+# Check system
+python manage.py check --deploy
+```
+
+---
+
+## Cross-Framework Migration Checklist
+
+Regardless of which framework you are upgrading, follow this universal checklist after the migration is complete:
+
+```
+Post-Migration Verification
+│
+├─ [ ] All tests pass (unit, integration, e2e)
+├─ [ ] Build succeeds in production mode
+├─ [ ] No deprecation warnings in build output
+├─ [ ] Bundle size compared to pre-migration baseline
+├─ [ ] Performance benchmarks compared to pre-migration baseline
+├─ [ ] Error monitoring shows no new error types
+├─ [ ] All pages/routes load correctly (smoke test)
+├─ [ ] Forms and user interactions work
+├─ [ ] Authentication and authorization work
+├─ [ ] Third-party integrations verified
+├─ [ ] CI/CD pipeline updated for new version
+├─ [ ] Docker/deployment images updated
+├─ [ ] Documentation updated (README, setup guide)
+└─ [ ] Team notified of completed migration
+```

skills/migrate-ops/references/language-upgrades.md

@@ -0,0 +1,608 @@
+# Language Version Upgrades
+
+Detailed upgrade paths for major programming language version transitions.
+
+---
+
+## Python 3.9 to 3.13
+
+### Python 3.10 (from 3.9)
+
+**Key Features Gained:**
+- Structural pattern matching (`match`/`case`)
+- Parenthesized context managers
+- Better error messages with precise line indicators
+- `typing.TypeAlias` for explicit type aliases
+- `zip()` gets `strict` parameter
+- `bisect` and `statistics` module improvements
+
+**Breaking Changes:**
+- `distutils` deprecated (use `setuptools` instead)
+- `loop` parameter removed from most `asyncio` high-level APIs
+- `int` has a new `bit_count()` method (name collision risk)
+
+**Migration Commands:**
+```bash
+# Update pyproject.toml / setup.cfg
+python-requires = ">=3.10"
+
+# Run pyupgrade for syntax modernization
+pip install pyupgrade
+pyupgrade --py310-plus $(fd -e py)
+
+# Check for distutils usage
+rg "from distutils" .
+rg "import distutils" .
+```
+
+### Python 3.11 (from 3.10)
+
+**Key Features Gained:**
+- Exception groups and `except*` syntax
+- `tomllib` in standard library (TOML parsing)
+- Task groups in asyncio (`asyncio.TaskGroup`)
+- Fine-grained error locations in tracebacks
+- 10-60% faster CPython (Faster CPython project)
+- `Self` type in `typing` module
+- `StrEnum` class
+
+**Breaking Changes:**
+- `asyncio.coroutine` decorator removed
+- `unittest.TestCase.addModuleCleanup` behavior change
+- `locale.getdefaultlocale()` deprecated
+- `smtpd` module removed (use `aiosmtpd`)
+
+**Migration Commands:**
+```bash
+pyupgrade --py311-plus $(fd -e py)
+
+# Replace manual TOML parsing
+rg "import toml\b" .        # replace with: import tomllib
+rg "toml\.loads?" .          # replace with: tomllib.loads / tomllib.load
+
+# Check for removed modules
+rg "import smtpd" .
+rg "asyncio\.coroutine" .
+```
+
+### Python 3.12 (from 3.11)
+
+**Key Features Gained:**
+- Type parameter syntax (`class Stack[T]:`, `def first[T](l: list[T]) -> T:`)
+- `type` statement for type aliases (`type Vector = list[float]`)
+- F-string improvements (nested quotes, backslashes, comments)
+- Per-interpreter GIL (subinterpreters)
+- `pathlib.Path.walk()` method
+- Improved `asyncio.TaskGroup` semantics
+- Buffer protocol accessible from Python (`__buffer__`)
+
+**Breaking Changes:**
+- `distutils` package removed entirely (was deprecated in 3.10)
+- `imp` module removed (use `importlib`)
+- `locale.getdefaultlocale()` removed
+- `unittest` method aliases removed (`assertEquals` etc.)
+- `asyncio` legacy API removals
+- `pkgutil.find_loader()` / `get_loader()` removed
+- `sqlite3` default adapters and converters no longer registered by default
+- `os.popen()` and `os.spawn*()` deprecated
+- Wstr representation removed from C API
+
+**Migration Commands:**
+```bash
+pyupgrade --py312-plus $(fd -e py)
+
+# Check for removed modules
+rg "import imp\b" .          # replace with importlib
+rg "from imp " .
+rg "import distutils" .      # must use setuptools
+rg "from distutils" .
+
+# Check for removed unittest aliases
+rg "assertEquals|assertNotEquals|assertRegexpMatches" .
+
+# Adopt new type syntax (optional but recommended)
+# Old: T = TypeVar('T')
+# New: def func[T](x: T) -> T:
+```
+
+### Python 3.13 (from 3.12)
+
+**Key Features Gained:**
+- Free-threaded mode (experimental, `--disable-gil` build)
+- Improved interactive interpreter (REPL with colors, multiline editing)
+- `locals()` returns copy with defined semantics
+- Improved error messages (color, suggestions)
+- `dbm.sqlite3` as default dbm backend
+- `argparse` deprecations enforced
+- JIT compiler (experimental, `--enable-experimental-jit` build)
+
+**Breaking Changes:**
+- `aifc`, `audioop`, `cgi`, `cgitb`, `chunk`, `crypt`, `imghdr`, `mailcap`, `msilib`, `nis`, `nntplib`, `ossaudiodev`, `pipes`, `sndhdr`, `spwd`, `sunau`, `telnetlib`, `uu`, `xdrlib` modules removed
+- `pathlib.PurePath.is_relative_to()` and `relative_to()` semantics change
+- `typing.io` and `typing.re` namespaces removed
+- `locale.resetlocale()` removed
+- C API changes affecting extension modules
+
+**Migration Commands:**
+```bash
+# Check for removed stdlib modules
+rg "import (aifc|audioop|cgi|cgitb|chunk|crypt|imghdr|mailcap|nis|nntplib|ossaudiodev|pipes|sndhdr|spwd|sunau|telnetlib|uu|xdrlib)" .
+
+# For cgi module replacement
+rg "import cgi" .       # replace with: from urllib.parse import parse_qs
+rg "cgi.FieldStorage" . # replace with: manual multipart parsing or framework
+
+# Check for typing namespace changes
+rg "typing\.io\." .
+rg "typing\.re\." .
+
+# Test free-threaded mode (experimental)
+python3.13t script.py  # if built with --disable-gil
+```
+
+### Python Version Upgrade Summary
+
+| From → To | Key Action | Biggest Risk |
+|-----------|-----------|--------------|
+| 3.9 → 3.10 | Fix `distutils` usage, adopt pattern matching | `asyncio` loop parameter removal |
+| 3.10 → 3.11 | Replace `toml` with `tomllib`, enjoy speed boost | `smtpd` removal |
+| 3.11 → 3.12 | Remove `distutils`/`imp`, adopt type syntax | `distutils` full removal, sqlite3 adapter changes |
+| 3.12 → 3.13 | Remove deprecated stdlib modules | Large number of removed stdlib modules |
+
+---
+
+## Node.js 18 to 22
+
+### Node.js 20 (from 18)
+
+**Key Features Gained:**
+- Permission model (`--experimental-permission`)
+- Stable test runner (`node:test`)
+- `.env` file support (`--env-file=.env`)
+- V8 11.3 (improved performance)
+- `import.meta.resolve()` unflagged
+- Single executable applications (SEA)
+- `URL.canParse()` static method
+- `ArrayBuffer.transfer()` and `resizable` option
+- `WebSocket` client (experimental)
+
+**Breaking Changes:**
+- `url.parse()` may throw on invalid URLs (stricter parsing)
+- `fs.read()` parameter validation stricter
+- Custom ESM loader hooks (`load`, `resolve`) are off-thread
+- `http.IncomingMessage` connected socket timeout default change
+
+**Migration Commands:**
+```bash
+# Update nvm / fnm
+nvm install 20
+nvm use 20
+
+# Or update Docker
+# FROM node:20-alpine
+
+# Check for url.parse usage (may need URL constructor)
+rg "url\.parse\(" .
+
+# Adopt built-in test runner (optional)
+# Replace: jest/mocha test files
+# With: import { test, describe } from 'node:test';
+
+# Use .env file support
+node --env-file=.env app.js
+```
+
+### Node.js 22 (from 20)
+
+**Key Features Gained:**
+- `require()` for ESM modules (experimental `--experimental-require-module`)
+- WebSocket client stable
+- Built-in watch mode stable (`node --watch`)
+- `glob` and `globSync` in `node:fs`
+- V8 12.4 (Maglev compiler, `Array.fromAsync`)
+- `node:sqlite` built-in module (experimental)
+- `--run` flag for package.json scripts
+- Task runner integration
+- `AbortSignal.any()`
+- Stable permission model
+
+**Breaking Changes:**
+- `node:http` stricter header validation
+- `node:buffer` Blob changes
+- Minimum glibc 2.28 on Linux
+- `node:child_process` IPC serialization changes
+- `node:dns` default resolver changes
+
+**Migration Commands:**
+```bash
+nvm install 22
+nvm use 22
+
+# Or update Docker
+# FROM node:22-alpine
+
+# Check for incompatible native modules
+npm rebuild
+
+# Test ESM/CJS interop if using mixed modules
+node --experimental-require-module app.js
+
+# Adopt built-in features
+# Replace: glob package → node:fs { glob, globSync }
+# Replace: ws package → built-in WebSocket (for client usage)
+# Replace: chokidar/nodemon → node --watch
+```
+
+### Node.js Version Upgrade Summary
+
+| From → To | Key Action | Biggest Risk |
+|-----------|-----------|--------------|
+| 18 → 20 | Rebuild native modules, test URL parsing | Stricter URL validation, loader hooks off-thread |
+| 20 → 22 | Rebuild native modules, check glibc version | Native module compatibility, header validation |
+
+---
+
+## TypeScript 4.x to 5.x
+
+### TypeScript 5.0 (from 4.9)
+
+**Key Features Gained:**
+- ECMAScript decorators (stage 3 standard)
+- `const` type parameters
+- `--moduleResolution bundler`
+- `extends` on multiple config files
+- All `enum`s become union `enum`s
+- `--verbatimModuleSyntax` (replaces `isolatedModules`)
+- Speed and size improvements (TS migrated to modules internally)
+- `satisfies` operator (introduced in 4.9, now mature)
+
+**Breaking Changes:**
+- `--target ES3` removed
+- `--out` removed (use `--outFile`)
+- `--noImplicitUseStrict` removed
+- `--suppressExcessPropertyErrors` removed
+- `--suppressImplicitAnyIndexErrors` removed
+- `--prepend` in project references removed
+- Runtime behavior of decorators changed (now ECMAScript standard)
+- `--moduleResolution node` renamed to `node10`
+- `--module` value changes
+
+**Migration Commands:**
+```bash
+npm install -D typescript@5
+
+# Check for removed compiler options in tsconfig.json
+rg '"target":\s*"ES3"' tsconfig.json
+rg '"out":' tsconfig.json
+rg '"suppressExcessPropertyErrors"' tsconfig.json
+
+# If using legacy decorators, keep experimentalDecorators flag
+# If adopting new decorators, remove experimentalDecorators
+
+# Adopt bundler module resolution
+# tsconfig.json: "moduleResolution": "bundler"
+```
+
+### TypeScript 5.1-5.7 Highlights
+
+| Version | Key Feature |
+|---------|-------------|
+| **5.1** | Easier implicit return for `undefined`, unrelated getter/setter types |
+| **5.2** | `using` declarations (explicit resource management), decorator metadata |
+| **5.3** | `import` attribute support, `resolution-mode` in all module modes |
+| **5.4** | `NoInfer<T>` utility type, `Object.groupBy` / `Map.groupBy` types |
+| **5.5** | Inferred type predicates, regex syntax checking, `isolatedDeclarations` |
+| **5.6** | Iterator helper methods, `--noUncheckedSideEffectImports` |
+| **5.7** | `--rewriteRelativeImportExtensions`, `--target es2024` |
+
+### Migration Strategy
+
+```
+TypeScript version upgrade approach:
+│
+├─ Minor version (5.x → 5.y)
+│  └─ Generally safe, just update and fix new errors
+│     npm install -D typescript@5.y
+│     npx tsc --noEmit
+│
+└─ Major version (4.x → 5.x)
+   ├─ 1. Update tsconfig.json (remove deleted options)
+   ├─ 2. Install typescript@5
+   ├─ 3. Run tsc --noEmit, fix errors
+   ├─ 4. Decide on decorator strategy (legacy vs ECMAScript)
+   └─ 5. Consider adopting moduleResolution: "bundler"
+```
+
+---
+
+## Go 1.20 to 1.23
+
+### Go 1.21 (from 1.20)
+
+**Key Features Gained:**
+- `log/slog` structured logging (standard library)
+- `slices` and `maps` packages in standard library
+- `min()` and `max()` built-in functions
+- `clear()` built-in for maps and slices
+- PGO (Profile-Guided Optimization) generally available
+- `go.mod` toolchain directive
+- Forward compatibility (`GOTOOLCHAIN` environment variable)
+
+**Breaking Changes:**
+- `go.mod` now tracks toolchain version
+- Panic on `nil` pointer dereference in more cases
+- `net/http` minor behavior changes
+
+**Migration Commands:**
+```bash
+# Update go.mod
+go mod edit -go=1.21
+go mod tidy
+
+# Adopt slog for structured logging
+rg "log\.Printf|log\.Println" .  # candidates for slog migration
+
+# Replace sort.Slice with slices.SortFunc
+rg "sort\.Slice\b" .  # consider slices.SortFunc
+```
+
+### Go 1.22 (from 1.21)
+
+**Key Features Gained:**
+- `for range` over integers (`for i := range 10`)
+- Enhanced `net/http` routing (method + path patterns)
+- Loop variable fix (each iteration gets its own variable)
+- `math/rand/v2` package
+- `go/version` package
+- `slices.Concat`
+
+**Breaking Changes:**
+- Loop variable semantics change (each iteration gets a copy -- fixes the classic goroutine-in-loop bug)
+- `math/rand` global functions deterministic without seed
+
+**Migration Commands:**
+```bash
+go mod edit -go=1.22
+go mod tidy
+
+# The loop variable change is backward compatible but may fix hidden bugs
+# Review goroutine closures in loops that relied on shared variable
+
+# Adopt enhanced routing
+# Old: mux.HandleFunc("/users", handler) + manual method check
+# New: mux.HandleFunc("GET /users/{id}", handler)
+rg "r\.Method ==" .  # candidates for enhanced routing
+```
+
+### Go 1.23 (from 1.22)
+
+**Key Features Gained:**
+- Iterators (`iter.Seq`, `iter.Seq2`) and `range over func`
+- `unique` package (interning/canonicalization)
+- `structs` package (struct layout control)
+- Timer/Ticker changes (garbage collected when unreferenced)
+- `slices` and `maps` moved from `golang.org/x/exp` to standard library
+- OpenTelemetry-compatible `log/slog` handlers
+
+**Breaking Changes:**
+- `time.Timer` and `time.Ticker` behavior change (channels drained on Stop/Reset)
+- `os/exec` `LookPath` behavior on Windows (security fix)
+
+**Migration Commands:**
+```bash
+go mod edit -go=1.23
+go mod tidy
+
+# Replace x/exp/slices and x/exp/maps with standard library versions
+rg "golang.org/x/exp/slices" .
+rg "golang.org/x/exp/maps" .
+# Replace with: "slices" and "maps"
+
+# Check Timer/Ticker usage
+rg "\.Stop\(\)" . --glob "*.go"  # Review timer stop behavior
+rg "\.Reset\(" . --glob "*.go"   # Review timer reset behavior
+```
+
+### Go Version Upgrade Summary
+
+| From → To | Key Action | Biggest Risk |
+|-----------|-----------|--------------|
+| 1.20 → 1.21 | Update go.mod toolchain, adopt slog | Toolchain directive in go.mod |
+| 1.21 → 1.22 | Enjoy loop variable fix, adopt enhanced routing | Loop variable semantics (usually fixes bugs) |
+| 1.22 → 1.23 | Replace x/exp packages, adopt iterators | Timer/Ticker behavior change |
+
+---
+
+## Rust Edition 2021 to 2024
+
+### Key Features in Edition 2024
+
+- **RPITIT** (Return Position Impl Trait in Traits): use `-> impl Trait` in trait definitions
+- **Async fn in traits**: `async fn` directly in trait definitions (no need for `async-trait` crate)
+- **`let` chains**: `if let Some(x) = a && let Some(y) = b { ... }`
+- **`gen` blocks** (experimental): generator-based iterators
+- **Lifetime capture rules**: all in-scope lifetimes captured by default in `-> impl Trait`
+- **`unsafe_op_in_unsafe_fn`** lint: must use `unsafe {}` blocks inside `unsafe fn`
+- **Precise capturing** with `use<>` syntax
+- **`#[diagnostic]` attribute** namespace for custom diagnostics
+- **Reserving `gen` keyword** for generators
+- **Temporary lifetime extension** changes in `match` and `if let`
+
+### Breaking Changes
+
+| Change | Impact | Fix |
+|--------|--------|-----|
+| `unsafe_op_in_unsafe_fn` is deny by default | `unsafe fn` bodies need explicit `unsafe {}` blocks | Wrap unsafe operations in `unsafe {}` |
+| Lifetime capture rules change | `-> impl Trait` captures all in-scope lifetimes | Use `use<'a>` for precise control |
+| `gen` is a reserved keyword | Cannot use `gen` as identifier | Rename `gen` variables/functions |
+| `never` type fallback changes | `!` type fallback now `!` instead of `()` | May affect type inference in rare cases |
+| Temporary lifetime changes | Temporaries in `match` scrutinee have shorter lifetime | Store temporaries in `let` bindings |
+| `unsafe extern` blocks | `extern` items implicitly unsafe to reference | Add `safe` keyword to safe extern items |
+| Disallow references to `static mut` | `&STATIC_MUT` is forbidden | Use `addr_of!()` / `addr_of_mut!()` |
+
+### Migration Commands
+
+```bash
+# Automatic edition migration
+cargo fix --edition
+
+# Update Cargo.toml
+# edition = "2024"
+
+# Fix unsafe_op_in_unsafe_fn warnings
+cargo clippy --fix -- -W unsafe_op_in_unsafe_fn
+
+# Check for gen keyword conflicts
+rg "\bgen\b" src/ --glob "*.rs"
+
+# Remove async-trait crate if adopting native async traits
+rg "async.trait" Cargo.toml
+rg "#\[async_trait\]" src/
+```
+
+### Verification Steps
+
+```bash
+cargo build
+cargo test
+cargo clippy -- -D warnings
+cargo doc --no-deps  # check documentation builds
+```
+
+---
+
+## PHP 8.1 to 8.4
+
+### PHP 8.2 (from 8.1)
+
+**Key Features Gained:**
+- Readonly classes
+- Disjunctive Normal Form (DNF) types
+- `null`, `false`, `true` as standalone types
+- Constants in traits
+- Enum improvements
+- Random extension (`\Random\Randomizer`)
+- `SensitiveParameter` attribute
+- Fibers improvements
+
+**Breaking Changes:**
+- Dynamic properties deprecated (use `#[AllowDynamicProperties]` or `__get`/`__set`)
+- Implicit nullable parameter declarations deprecated
+- `${var}` string interpolation deprecated (use `{$var}`)
+- `utf8_encode` / `utf8_decode` deprecated
+- Various internal class changes
+
+**Migration Commands:**
+```bash
+# Rector automated fixes
+composer require rector/rector --dev
+vendor/bin/rector process src --set php82
+
+# Check for dynamic properties
+rg "->(\w+)\s*=" src/ --glob "*.php"  # review for undeclared properties
+
+# Check deprecated string interpolation
+rg '"\$\{' src/ --glob "*.php"
+```
+
+### PHP 8.3 (from 8.2)
+
+**Key Features Gained:**
+- Typed class constants
+- `json_validate()` function
+- `#[\Override]` attribute
+- Deep cloning of readonly properties in `__clone()`
+- Dynamic class constant fetch (`$class::{$constant}`)
+- `Randomizer::getBytesFromString()`
+- `mb_str_pad()` function
+- Improved `unserialize()` error handling
+
+**Breaking Changes:**
+- `array_sum()` and `array_product()` behavior changes
+- `proc_get_status()` multiple calls return same result
+- `range()` type checking stricter
+- `number_format()` behavior change with negative zero
+
+**Migration Commands:**
+```bash
+vendor/bin/rector process src --set php83
+
+# Adopt #[Override] attribute on methods
+# This catches parent method renames at compile time
+
+# Adopt typed constants
+# Old: const STATUS = 'active';
+# New: const string STATUS = 'active';
+
+# Use json_validate() instead of json_decode() for validation
+rg "json_decode.*json_last_error" src/ --glob "*.php"
+```
+
+### PHP 8.4 (from 8.3)
+
+**Key Features Gained:**
+- Property hooks (get/set)
+- Asymmetric visibility (`public private(set)`)
+- `#[\Deprecated]` attribute
+- `new` without parentheses in chained expressions
+- HTML5 DOM parser (`\Dom\HTMLDocument`)
+- Lazy objects (`ReflectionClass::newLazyProxy()`)
+- `array_find()`, `array_find_key()`, `array_any()`, `array_all()`
+- `Multibyte` functions for `trim`, `ltrim`, `rtrim`
+- `request_parse_body()` for non-POST requests
+
+**Breaking Changes:**
+- Implicitly nullable parameter types trigger deprecation notice
+- `E_STRICT` constant deprecated
+- `session_set_save_handler()` with `open`/`close` etc. deprecated
+- `strtolower()` and `strtoupper()` locale-insensitive
+- Various DOM API changes for HTML5 compliance
+
+**Migration Commands:**
+```bash
+vendor/bin/rector process src --set php84
+
+# Adopt property hooks (optional but recommended)
+# Old:
+# private string $name;
+# public function getName(): string { return $this->name; }
+# public function setName(string $name): void { $this->name = $name; }
+# New:
+# public string $name {
+#     get => $this->name;
+#     set(string $value) => $this->name = strtolower($value);
+# }
+
+# Adopt asymmetric visibility
+# public private(set) string $name;
+
+# Check for implicit nullable types
+rg "function \w+\([^)]*\w+ \$\w+ = null" src/ --glob "*.php"
+```
+
+### PHP Version Upgrade Summary
+
+| From → To | Key Action | Biggest Risk |
+|-----------|-----------|--------------|
+| 8.1 → 8.2 | Fix dynamic properties, deprecation warnings | Dynamic properties deprecated |
+| 8.2 → 8.3 | Adopt typed constants, #[Override] | array_sum/array_product behavior |
+| 8.3 → 8.4 | Adopt property hooks, asymmetric visibility | Implicit nullable deprecation |
+
+---
+
+## Cross-Language Upgrade Checklist
+
+Regardless of which language you are upgrading:
+
+```
+[ ] CI matrix includes both old and new versions during transition
+[ ] Linter/formatter updated to support new syntax
+[ ] IDE / editor language server updated
+[ ] Docker base images updated
+[ ] Deployment pipeline runtime version updated
+[ ] New language features documented in team style guide
+[ ] Deprecated API usage eliminated before upgrade
+[ ] All tests pass on new version
+[ ] Performance benchmarks compared pre/post upgrade
+[ ] Third-party dependencies verified compatible
+```

skills/perf-ops/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: perf-ops
+description: "Performance profiling and optimization - CPU, memory, bundle analysis, load testing, flamegraphs. Use for: performance, profiling, flamegraph, pprof, py-spy, clinic.js, memray, heaptrack, bundle size, webpack analyzer, load testing, k6, artillery, vegeta, locust, benchmark, hyperfine, criterion, slow query, EXPLAIN ANALYZE, N+1, caching, optimization, latency, throughput, p99, memory leak, CPU spike, bottleneck."
+allowed-tools: "Read Edit Write Bash Glob Grep Agent"
+related-skills: [debug-ops, monitoring-ops, testing-ops, code-stats]
+---
+
+# Performance Operations
+
+Cross-language performance profiling, optimization patterns, and load testing methodology.
+
+## Performance Issue Decision Tree
+
+```
+What symptom are you observing?
+│
+├─ High CPU usage
+│  ├─ Sustained 100% on one core
+│  │  └─ CPU-bound: hot loop, regex backtracking, tight computation
+│  │     → Profile with flamegraph (py-spy, pprof, clinic flame, samply)
+│  ├─ Sustained 100% across all cores
+│  │  └─ Parallelism gone wrong: fork bomb, unbounded workers, spin locks
+│  │     → Check process count, thread count, lock contention
+│  └─ Periodic spikes
+│     └─ GC pressure, cron job, batch processing, cache stampede
+│        → Correlate with GC logs, scheduled tasks, traffic patterns
+│
+├─ High memory usage
+│  ├─ Growing over time (never decreasing)
+│  │  └─ Memory leak: unclosed resources, growing caches, event listener accumulation
+│  │     → Heap snapshots over time, compare retained objects
+│  ├─ Sudden large allocation
+│  │  └─ Unbounded buffer, loading full dataset into memory, large file read
+│  │     → Check allocation sizes, switch to streaming
+│  └─ High but stable
+│     └─ May be normal: in-memory cache, preloaded data, memory-mapped files
+│        → Verify with expected working set size
+│
+├─ Slow responses / high latency
+│  ├─ All endpoints slow
+│  │  └─ Systemic: resource exhaustion, GC pauses, DNS issues, TLS overhead
+│  │     → Check resource utilization, GC metrics, network path
+│  ├─ Specific endpoint slow
+│  │  └─ Query-specific: N+1 queries, missing index, unoptimized algorithm
+│  │     → EXPLAIN ANALYZE, query logging, endpoint profiling
+│  └─ Intermittently slow (p99 spikes)
+│     └─ Contention: lock wait, connection pool exhaustion, noisy neighbor
+│        → Check lock metrics, pool sizes, correlated traffic
+│
+├─ Low throughput
+│  ├─ CPU not saturated
+│  │  └─ I/O bound: disk wait, network latency, blocking calls in async code
+│  │     → Check iowait, network RTT, ensure async throughout
+│  ├─ CPU saturated
+│  │  └─ Compute bound: need algorithmic improvement or horizontal scaling
+│  │     → Profile hot paths, optimize or scale out
+│  └─ Queues backing up
+│     └─ Consumer too slow: batch size, consumer count, downstream bottleneck
+│        → Increase consumers, optimize processing, check downstream
+│
+├─ Large bundle size (frontend)
+│  ├─ Main bundle too large
+│  │  └─ Missing code splitting, tree shaking not working, barrel file imports
+│  │     → Bundle analyzer, check import patterns, add dynamic imports
+│  ├─ Duplicate dependencies
+│  │  └─ Multiple versions of same library bundled
+│  │     → Dedupe, check peer dependencies, use resolutions
+│  └─ Large assets
+│     └─ Unoptimized images, embedded fonts, inline data URIs
+│        → Image optimization, font subsetting, external assets
+│
+└─ Slow database queries
+   ├─ Single slow query
+   │  └─ Missing index, suboptimal join order, full table scan
+   │     → EXPLAIN ANALYZE, add index, rewrite query
+   ├─ Many small queries (N+1)
+   │  └─ ORM lazy loading, loop with individual queries
+   │     → Eager loading, batch queries, dataloader pattern
+   └─ Lock contention
+      └─ Long transactions, row-level locks, table locks
+         → Shorten transactions, check isolation level, advisory locks
+```
+
+## Profiling Tool Selection Matrix
+
+| Problem | Node.js | Python | Go | Rust | Browser |
+|---------|---------|--------|----|------|---------|
+| **CPU hotspots** | clinic flame, 0x | py-spy, scalene | pprof (CPU) | cargo-flamegraph, samply | DevTools Performance |
+| **Memory leaks** | clinic doctor, heap snapshot | memray, tracemalloc | pprof (heap) | DHAT, heaptrack | DevTools Memory |
+| **Memory allocation** | --heap-prof | memray, scalene | pprof (allocs) | DHAT | DevTools Allocation |
+| **Async bottlenecks** | clinic bubbleprof | asyncio debug mode | pprof (goroutine) | tokio-console | DevTools Performance |
+| **I/O profiling** | clinic doctor | strace, py-spy | pprof (block) | strace, perf | Network tab |
+| **GC pressure** | --trace-gc | gc.set_debug | GODEBUG=gctrace=1 | N/A (no GC) | Performance timeline |
+| **Lock contention** | N/A | py-spy (threading) | pprof (mutex) | parking_lot stats | N/A |
+| **Startup time** | --cpu-prof | python -X importtime | go build -v | cargo build --timings | Lighthouse |
+
+## CPU Profiling Quick Reference
+
+### Flamegraph Basics
+
+```
+Reading a flamegraph:
+- X-axis: proportion of total samples (wider = more time)
+- Y-axis: call stack depth (bottom = entry point, top = leaf)
+- Color: random (not meaningful) in most tools
+- Look for: wide plateaus at the top (hot functions)
+- Ignore: narrow towers (called often but fast)
+
+Key actions:
+1. Find the widest bars at the TOP of the graph
+2. Trace down to see what calls them
+3. Focus optimization on the widest top-level functions
+4. Re-profile after each change to verify improvement
+```
+
+### Tool Quick Start
+
+| Tool | Language | Command | Output |
+|------|----------|---------|--------|
+| **py-spy** | Python | `py-spy record -o profile.svg -- python app.py` | SVG flamegraph |
+| **py-spy top** | Python | `py-spy top --pid PID` | Live top-like view |
+| **pprof** | Go | `go tool pprof -http :8080 http://localhost:6060/debug/pprof/profile?seconds=30` | Interactive web UI |
+| **clinic flame** | Node.js | `clinic flame -- node app.js` | HTML flamegraph |
+| **0x** | Node.js | `0x app.js` | SVG flamegraph |
+| **cargo-flamegraph** | Rust | `cargo flamegraph --bin myapp` | SVG flamegraph |
+| **samply** | Rust/C/C++ | `samply record ./target/release/myapp` | Firefox Profiler UI |
+| **perf** | Linux (any) | `perf record -g ./myapp && perf script \| inferno-flamegraph > out.svg` | SVG flamegraph |
+
+## Memory Profiling Quick Reference
+
+| Tool | Language | Command | What It Shows |
+|------|----------|---------|---------------|
+| **memray** | Python | `memray run script.py && memray flamegraph output.bin` | Allocation flamegraph, leak detection |
+| **tracemalloc** | Python | `tracemalloc.start(); snapshot = tracemalloc.take_snapshot()` | Top allocators, allocation traceback |
+| **scalene** | Python | `scalene script.py` | CPU + memory + GPU in one profiler |
+| **heaptrack** | C/C++/Rust | `heaptrack ./myapp && heaptrack_gui heaptrack.myapp.*.zst` | Allocation timeline, flamegraph, leak candidates |
+| **DHAT** | Rust | `valgrind --tool=dhat ./target/debug/myapp` | Allocation sites, short-lived allocs |
+| **pprof (heap)** | Go | `go tool pprof http://localhost:6060/debug/pprof/heap` | Live heap, allocation counts |
+| **Chrome heap** | JS/Browser | DevTools → Memory → Take heap snapshot | Object retention, detached DOM |
+| **clinic doctor** | Node.js | `clinic doctor -- node app.js` | Memory + CPU + event loop diagnosis |
+
+## Bundle Analysis Quick Reference
+
+| Tool | Bundler | Command | Output |
+|------|---------|---------|--------|
+| **webpack-bundle-analyzer** | Webpack | `npx webpack-bundle-analyzer stats.json` | Interactive treemap |
+| **source-map-explorer** | Any | `npx source-map-explorer bundle.js` | Treemap from source maps |
+| **rollup-plugin-visualizer** | Rollup/Vite | Add plugin, build | HTML treemap |
+| **vite-bundle-visualizer** | Vite | `npx vite-bundle-visualizer` | Treemap visualization |
+| **bundlephobia** | npm | `npx bundlephobia <package>` | Package size analysis |
+| **size-limit** | Any | Configure in package.json, run in CI | Size budget enforcement |
+
+### Bundle Size Reduction Checklist
+
+```
+[ ] Dynamic imports for routes and heavy components
+[ ] Tree shaking working (check for side effects in package.json)
+[ ] No barrel file re-exports pulling in entire modules
+[ ] Lodash: use lodash-es or individual imports (lodash/debounce)
+[ ] Moment.js replaced with date-fns or dayjs
+[ ] Images optimized (WebP/AVIF, responsive sizes, lazy loading)
+[ ] Fonts subsetted to used characters
+[ ] Gzip/Brotli compression enabled on server
+[ ] Source maps excluded from production bundle size
+[ ] CSS purged of unused styles (PurgeCSS, Tailwind JIT)
+```
+
+## Database Performance Quick Reference
+
+### EXPLAIN ANALYZE Interpretation
+
+```
+Key metrics in EXPLAIN ANALYZE output:
+│
+├─ Seq Scan          → Full table scan (often bad for large tables)
+│  └─ Fix: Add index on filter columns
+├─ Index Scan        → Using index (good)
+├─ Bitmap Index Scan → Multiple index conditions combined (good)
+├─ Nested Loop       → OK for small inner table, bad for large joins
+│  └─ Fix: Add index on join column, consider Hash Join
+├─ Hash Join         → Good for large equi-joins
+├─ Sort              → Check if index can provide order
+│  └─ Fix: Add index matching ORDER BY
+├─ actual time       → First row..last row in milliseconds
+├─ rows              → Actual rows vs planned (estimate accuracy)
+└─ buffers           → shared hit (cache) vs read (disk I/O)
+```
+
+### N+1 Detection
+
+```
+Symptoms:
+- Many identical queries with different WHERE values
+- Response time scales linearly with result count
+- Query log shows repeated patterns
+
+Detection:
+- Django: django-debug-toolbar, nplusone
+- Rails: Bullet gem
+- SQLAlchemy: sqlalchemy.echo=True, look for repeated patterns
+- General: enable slow query log, count queries per request
+
+Fix:
+- Eager loading (JOIN, prefetch, include)
+- Batch queries (WHERE id IN (...))
+- DataLoader pattern (batch + cache per request)
+```
+
+## Load Testing Quick Reference
+
+| Tool | Language | Strengths | Command |
+|------|----------|-----------|---------|
+| **k6** | Go (JS scripts) | Scripted scenarios, thresholds, cloud | `k6 run script.js` |
+| **artillery** | Node.js | YAML config, plugins, Playwright | `artillery run config.yml` |
+| **vegeta** | Go | CLI piping, constant rate | `echo "GET http://localhost" \| vegeta attack \| vegeta report` |
+| **wrk** | C | Lightweight, Lua scripts | `wrk -t4 -c100 -d30s http://localhost` |
+| **autocannon** | Node.js | Programmatic, pipelining | `autocannon -c 100 -d 30 http://localhost` |
+| **locust** | Python | Python classes, distributed | `locust -f locustfile.py` |
+
+### Load Test Types
+
+```
+Test Type Selection:
+│
+├─ Smoke Test
+│  └─ Minimal load (1-2 VUs) to verify system works
+│     Duration: 1-5 minutes
+│
+├─ Load Test
+│  └─ Expected production load
+│     Duration: 15-60 minutes
+│     Goal: Verify SLOs are met under normal conditions
+│
+├─ Stress Test
+│  └─ Beyond expected load, find breaking point
+│     Ramp up until errors or unacceptable latency
+│     Goal: Know the system's limits
+│
+├─ Spike Test
+│  └─ Sudden burst of traffic
+│     Instant jump to high load, then drop
+│     Goal: Test auto-scaling, queue behavior
+│
+├─ Soak Test (Endurance)
+│  └─ Moderate load for extended period (hours)
+│     Goal: Find memory leaks, resource exhaustion, GC issues
+│
+└─ Breakpoint Test
+   └─ Continuously ramp up until failure
+      Goal: Find maximum capacity
+```
+
+## Benchmarking Quick Reference
+
+| Tool | Domain | Command | Notes |
+|------|--------|---------|-------|
+| **hyperfine** | CLI commands | `hyperfine 'cmd1' 'cmd2'` | Warm-up, statistical analysis, export |
+| **criterion** | Rust | `cargo bench` (with criterion dep) | Statistical, HTML reports, regression detection |
+| **testing.B** | Go | `go test -bench=. -benchmem` | Built-in, memory allocs, sub-benchmarks |
+| **pytest-benchmark** | Python | `pytest --benchmark-only` | Statistical, histograms, comparison |
+| **vitest bench** | JS/TS | `vitest bench` | Built-in to Vitest, Tinybench engine |
+| **Benchmark.js** | JS | Programmatic setup | Statistical analysis, ops/sec |
+
+### Benchmarking Best Practices
+
+```
+[ ] Warm up before measuring (JIT compilation, cache population)
+[ ] Run multiple iterations (minimum 10, prefer 100+)
+[ ] Report statistical summary (mean, median, stddev, min, max)
+[ ] Control for system noise (close other apps, pin CPU frequency)
+[ ] Compare against baseline (previous version, alternative impl)
+[ ] Measure what matters (end-to-end, not micro-operations in isolation)
+[ ] Profile before benchmarking (know WHAT to benchmark)
+[ ] Document environment (hardware, OS, runtime version, flags)
+```
+
+## Optimization Patterns Quick Reference
+
+| Pattern | When to Use | Example |
+|---------|-------------|---------|
+| **Caching** | Repeated expensive computations or I/O | Redis, in-memory LRU, CDN, memoization |
+| **Lazy loading** | Resources not needed immediately | Dynamic imports, virtual scrolling, pagination |
+| **Connection pooling** | Frequent DB/HTTP connections | PgBouncer, HikariCP, urllib3 pool |
+| **Batch operations** | Many small operations on same resource | Bulk INSERT, DataLoader, batch API calls |
+| **Pagination** | Large result sets | Cursor-based (not offset) for large datasets |
+| **Compression** | Network transfer of text data | Brotli > gzip for static, gzip for dynamic |
+| **Streaming** | Processing large files or datasets | Line-by-line, chunk processing, async iterators |
+| **Precomputation** | Predictable expensive calculations | Materialized views, build-time generation |
+| **Denormalization** | Read-heavy with expensive joins | Duplicate data for read performance |
+| **Index optimization** | Slow queries on large tables | Composite indexes matching query patterns |
+
+## Common Gotchas
+
+| Gotcha | Why It Hurts | Fix |
+|--------|-------------|-----|
+| Premature optimization | Wastes time on non-bottlenecks, adds complexity | Profile first, optimize the measured hot path |
+| Micro-benchmarks misleading | JIT, caching, branch prediction differ from real workload | Benchmark realistic workloads, validate with production metrics |
+| Profiling overhead | Profiler itself skews results (observer effect) | Use sampling profilers (py-spy, pprof) not tracing profilers |
+| Cache invalidation | Stale data served, inconsistent state across nodes | TTL + event-based invalidation, cache-aside pattern |
+| Optimizing cold path | Spending effort on rarely-executed code | Focus on hot paths identified by profiling |
+| Ignoring tail latency | p50 looks great but p99 is 10x worse | Measure and optimize p95/p99, not just averages |
+| N+1 queries hidden by ORM | Each page load fires hundreds of queries | Enable query logging, use eager loading |
+| Compression on small payloads | Overhead exceeds savings for payloads <150 bytes | Only compress above minimum size threshold |
+| Connection pool too large | Each connection uses memory, causes lock contention | Size pool to CPU cores x 2-3, not hundreds |
+| Missing async in I/O path | One blocking call serializes all concurrent requests | Audit entire request path for blocking calls |
+| Benchmarking debug builds | Debug builds 10-100x slower, misleading results | Always benchmark release/optimized builds |
+| Over-indexing database | Write performance degrades, storage bloats | Only index columns in WHERE, JOIN, ORDER BY clauses |
+
+## Reference Files
+
+| File | Contents | Lines |
+|------|----------|-------|
+| `references/cpu-memory-profiling.md` | Flamegraph interpretation, Node.js/Python/Go/Rust/Browser profiling, memory leak detection | ~700 |
+| `references/load-testing.md` | k6, Artillery, vegeta, wrk, Locust, load testing methodology, CI integration | ~600 |
+| `references/optimization-patterns.md` | Caching, database, frontend, API, concurrency, memory, algorithm optimization | ~550 |
+
+## See Also
+
+| Skill | When to Combine |
+|-------|----------------|
+| `debug-ops` | Debugging performance regressions, root cause analysis for slowdowns |
+| `monitoring-ops` | Production metrics, alerting on latency/throughput, dashboards |
+| `testing-ops` | Performance regression tests in CI, benchmark suites |
+| `code-stats` | Identify complex code that may be performance-sensitive |
+| `postgres-ops` | PostgreSQL-specific query optimization, indexing, EXPLAIN |
+| `container-orchestration` | Resource limits, pod scaling, container performance |

skills/perf-ops/references/cpu-memory-profiling.md

@@ -0,0 +1,774 @@
+# CPU & Memory Profiling
+
+Comprehensive profiling guide across languages and runtimes.
+
+## Flamegraph Reading Guide
+
+### Anatomy of a Flamegraph
+
+```
+A flamegraph is a visualization of stack traces collected by a sampling profiler.
+
+   ┌─────────────────────────────────────────────────────┐
+   │              expensiveComputation()                 │  ← Leaf (top): where CPU time is spent
+   ├───────────────────────┬─────────────────────────────┤
+   │   processItem()       │      validateInput()        │  ← Callees of handleRequest
+   ├───────────────────────┴─────────────────────────────┤
+   │                  handleRequest()                    │  ← Called by main
+   ├─────────────────────────────────────────────────────┤
+   │                      main()                         │  ← Root (bottom): entry point
+   └─────────────────────────────────────────────────────┘
+
+Reading rules:
+- Width = proportion of total samples (wider = more CPU time)
+- Height = stack depth (bottom = caller, top = callee)
+- Colors = typically random or language-based (not meaningful)
+- Left-to-right order = alphabetical (not temporal)
+
+What to look for:
+1. WIDE bars at the TOP → functions consuming the most CPU directly
+2. WIDE bars in the MIDDLE → functions whose callees consume most CPU
+3. Narrow tall towers → deep call stacks but fast (usually fine)
+4. Flat plateaus → single function dominating CPU time
+```
+
+### Top-Down vs Bottom-Up Analysis
+
+```
+Top-Down (Caller → Callee):
+- Start from root (main), follow widest paths down
+- Good for: understanding call hierarchy, finding which code path is slow
+- Question answered: "What is my application doing?"
+
+Bottom-Up (Callee → Caller):
+- Start from leaf functions, trace up to callers
+- Good for: finding hot functions regardless of who calls them
+- Question answered: "Which functions use the most CPU?"
+
+Differential Flamegraphs:
+- Compare two profiles (before/after change, baseline/regression)
+- Red = regression (more samples), Blue = improvement (fewer samples)
+- Generate: flamegraph.pl --negate > diff.svg
+- Tools: speedscope, Firefox Profiler, pprof diff
+```
+
+### Common Flamegraph Patterns
+
+```
+Pattern: GC Pressure
+- Look for: wide GC/runtime.gc bars, frequent small allocations
+- Fix: reduce allocations, use object pools, pre-allocate buffers
+
+Pattern: Lock Contention
+- Look for: wide mutex/lock/wait bars in multiple goroutines/threads
+- Fix: reduce critical section size, use lock-free data structures
+
+Pattern: Regex Backtracking
+- Look for: wide regex engine bars (re.match, regexp.exec)
+- Fix: anchor patterns, use possessive quantifiers, compile once
+
+Pattern: Serialization Overhead
+- Look for: wide JSON.parse/encode/marshal bars
+- Fix: schema-based serialization (protobuf, msgpack), streaming
+
+Pattern: Syscall Heavy
+- Look for: wide read/write/sendto/recvfrom system call bars
+- Fix: buffered I/O, batch operations, io_uring (Linux)
+```
+
+## Node.js Profiling
+
+### clinic.js Suite
+
+```bash
+# Install clinic.js globally
+npm install -g clinic
+
+# Doctor: automated diagnosis (CPU, memory, I/O, event loop)
+clinic doctor -- node app.js
+# Exercise your application, then Ctrl+C
+# Opens HTML report with diagnosis and recommendations
+
+# Flame: CPU flamegraph
+clinic flame -- node app.js
+# Exercise, Ctrl+C → interactive flamegraph
+
+# BubbleProf: async operation visualization
+clinic bubbleprof -- node app.js
+# Shows async operations, delays, and dependencies
+# Great for finding async bottlenecks invisible to CPU profilers
+```
+
+### 0x: Lightweight Flamegraphs
+
+```bash
+# Install and profile
+npm install -g 0x
+0x app.js
+# Exercise, Ctrl+C → opens flamegraph in browser
+
+# Profile with specific flags
+0x --collect-only app.js     # Collect stacks, don't generate graph
+0x --visualize-only PID.0x   # Generate graph from collected data
+0x -o flamegraph.html app.js # Specify output file
+```
+
+### Built-in V8 Profiling
+
+```bash
+# CPU profile (generates .cpuprofile)
+node --cpu-prof --cpu-prof-interval=100 app.js
+# Load in Chrome DevTools → Performance tab → Load profile
+
+# Heap profile (generates .heapprofile)
+node --heap-prof app.js
+# Load in Chrome DevTools → Memory tab
+
+# V8 trace optimization decisions
+node --trace-opt --trace-deopt app.js 2>&1 | grep -E "(OPTIMIZED|DEOPTIMIZED)"
+# Shows which functions V8 optimizes and deoptimizes
+
+# GC tracing
+node --trace-gc app.js
+# Output: [GC] type, duration, heap before/after
+
+# Allocation tracking
+node --trace-gc --trace-gc-verbose app.js
+```
+
+### Chrome DevTools CPU Profiler
+
+```
+1. Open chrome://inspect (or node --inspect-brk app.js)
+2. Click "inspect" on your Node.js target
+3. Go to Performance tab
+4. Click Record (●)
+5. Perform the actions you want to profile
+6. Stop recording
+7. Analyze:
+   - Summary: pie chart of activity types
+   - Bottom-Up: hottest functions first
+   - Call Tree: top-down call hierarchy
+   - Event Log: chronological events
+
+Key columns:
+- Self Time: time in the function itself (not callees)
+- Total Time: time including all callees
+- Focus on high Self Time for optimization targets
+```
+
+### Node.js Memory Profiling
+
+```bash
+# Heap snapshot via Chrome DevTools
+node --inspect app.js
+# DevTools → Memory → Take heap snapshot
+
+# Programmatic heap snapshots
+# npm install heapdump
+# In code:
+# const heapdump = require('heapdump');
+# heapdump.writeSnapshot('/tmp/heap-' + Date.now() + '.heapsnapshot');
+
+# Process memory monitoring
+node -e "
+  setInterval(() => {
+    const mem = process.memoryUsage();
+    console.log(JSON.stringify({
+      rss_mb: (mem.rss / 1024 / 1024).toFixed(1),
+      heap_used_mb: (mem.heapUsed / 1024 / 1024).toFixed(1),
+      heap_total_mb: (mem.heapTotal / 1024 / 1024).toFixed(1),
+      external_mb: (mem.external / 1024 / 1024).toFixed(1)
+    }));
+  }, 5000);
+"
+
+# Event loop utilization (Node 14+)
+# const { monitorEventLoopDelay } = require('perf_hooks');
+# const h = monitorEventLoopDelay({ resolution: 20 });
+# h.enable();
+# setInterval(() => console.log('p99:', h.percentile(99) / 1e6, 'ms'), 5000);
+```
+
+## Python Profiling
+
+### py-spy: Sampling Profiler
+
+```bash
+# Install
+pip install py-spy
+
+# Record flamegraph (no code changes needed)
+py-spy record -o profile.svg -- python app.py
+py-spy record -o profile.svg --pid PID   # Attach to running process
+
+# Live top-like view
+py-spy top --pid PID
+py-spy top -- python app.py
+
+# Output format options
+py-spy record -o profile.json --format speedscope -- python app.py
+py-spy record -o profile.txt --format raw -- python app.py
+
+# Profile subprocesses too
+py-spy record --subprocesses -o profile.svg -- python app.py
+
+# Sample rate (default 100 Hz)
+py-spy record --rate 250 -o profile.svg -- python app.py
+
+# Include native (C extension) frames
+py-spy record --native -o profile.svg -- python app.py
+```
+
+### cProfile and line_profiler
+
+```python
+# cProfile: function-level profiling (built-in)
+import cProfile
+import pstats
+
+# Profile a function
+cProfile.run('my_function()', 'output.prof')
+
+# Analyze results
+stats = pstats.Stats('output.prof')
+stats.sort_stats('cumulative')  # or 'tottime' for self time
+stats.print_stats(20)  # top 20 functions
+
+# Command-line usage
+# python -m cProfile -s cumulative app.py
+# python -m cProfile -o output.prof app.py
+
+# line_profiler: line-by-line profiling
+# pip install line_profiler
+# Decorate functions with @profile
+# kernprof -l -v script.py
+```
+
+### scalene: CPU + Memory + GPU
+
+```bash
+# Install
+pip install scalene
+
+# Profile (no code changes needed)
+scalene script.py
+scalene --cpu --memory --gpu script.py
+
+# Output as JSON for programmatic analysis
+scalene --json --outfile profile.json script.py
+
+# Profile specific function
+scalene --profile-only my_module script.py
+
+# Web-based UI
+scalene --html --outfile profile.html script.py
+
+# What scalene shows:
+# - CPU time (Python vs native code)
+# - Memory allocation and deallocation per line
+# - GPU usage per line
+# - Copy volume (data copying overhead)
+```
+
+### memray: Memory Profiler
+
+```bash
+# Install
+pip install memray
+
+# Record memory allocations
+memray run script.py
+memray run --output output.bin script.py
+
+# Attach to running process
+memray attach PID
+
+# Generate reports
+memray flamegraph output.bin              # Allocation flamegraph
+memray table output.bin                   # Table of allocations
+memray tree output.bin                    # Tree of allocations
+memray summary output.bin                 # High-level summary
+memray stats output.bin                   # Allocation statistics
+
+# Live monitoring
+memray run --live script.py               # TUI live view
+memray run --live-remote --live-port 9001 script.py  # Remote live view
+
+# Detect memory leaks
+memray flamegraph --leaks output.bin      # Show only leaked memory
+memray table --leaks output.bin
+
+# Temporal flamegraph (allocation over time)
+memray flamegraph --temporal output.bin
+```
+
+### tracemalloc: Built-in Memory Tracking
+
+```python
+import tracemalloc
+
+# Start tracing
+tracemalloc.start(25)  # Store 25 frames of traceback
+
+# Take snapshots at different points
+snapshot1 = tracemalloc.take_snapshot()
+# ... run code ...
+snapshot2 = tracemalloc.take_snapshot()
+
+# Top allocators
+top_stats = snapshot2.statistics('lineno')  # or 'traceback', 'filename'
+for stat in top_stats[:10]:
+    print(stat)
+
+# Compare snapshots (find growth)
+diff = snapshot2.compare_to(snapshot1, 'lineno')
+for stat in diff[:10]:
+    print(stat)
+
+# Current memory usage
+current, peak = tracemalloc.get_traced_memory()
+print(f"Current: {current / 1024 / 1024:.1f} MB")
+print(f"Peak:    {peak / 1024 / 1024:.1f} MB")
+```
+
+### objgraph: Reference Chain Visualization
+
+```python
+import objgraph
+
+# Show most common types in memory
+objgraph.show_most_common_types(limit=20)
+
+# Show growth between two points
+objgraph.show_growth(limit=10)
+# ... do something ...
+objgraph.show_growth(limit=10)  # Shows only types that grew
+
+# Find reference chains keeping objects alive
+objgraph.show_backrefs(
+    objgraph.by_type('MyClass')[0],
+    max_depth=10,
+    filename='refs.png'
+)
+
+# Count instances of a type
+print(objgraph.count('dict'))
+print(objgraph.count('MyClass'))
+```
+
+## Go Profiling
+
+### pprof: Built-in Profiler
+
+```go
+// Enable pprof HTTP endpoint (add to your main.go)
+import _ "net/http/pprof"
+
+func main() {
+    go func() {
+        log.Println(http.ListenAndServe("localhost:6060", nil))
+    }()
+    // ... rest of application
+}
+
+// Or for non-HTTP applications, use runtime/pprof directly:
+import "runtime/pprof"
+
+f, _ := os.Create("cpu.prof")
+pprof.StartCPUProfile(f)
+defer pprof.StopCPUProfile()
+```
+
+```bash
+# CPU profile (30 seconds)
+go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
+
+# Interactive mode commands:
+# top          - top functions by CPU
+# top -cum     - top by cumulative time
+# list funcName - source-level annotation
+# web          - open graph in browser
+# svg          - export call graph as SVG
+
+# Web UI (recommended)
+go tool pprof -http :8080 http://localhost:6060/debug/pprof/profile?seconds=30
+# Opens browser with flamegraph, graph, source, top views
+
+# Heap profile (current allocations)
+go tool pprof http://localhost:6060/debug/pprof/heap
+
+# Heap profile options:
+# -inuse_space   (default) currently allocated bytes
+# -inuse_objects  currently allocated object count
+# -alloc_space    total bytes allocated (including freed)
+# -alloc_objects  total objects allocated (including freed)
+
+# Goroutine profile (debug hanging/leaking goroutines)
+go tool pprof http://localhost:6060/debug/pprof/goroutine
+
+# Block profile (time spent blocking on sync primitives)
+# Must enable: runtime.SetBlockProfileRate(1)
+go tool pprof http://localhost:6060/debug/pprof/block
+
+# Mutex profile (mutex contention)
+# Must enable: runtime.SetMutexProfileFraction(5)
+go tool pprof http://localhost:6060/debug/pprof/mutex
+
+# Compare two profiles (differential)
+go tool pprof -diff_base=base.prof current.prof
+```
+
+### Go Trace
+
+```bash
+# Capture execution trace
+curl -o trace.out http://localhost:6060/debug/pprof/trace?seconds=5
+go tool trace trace.out
+
+# Or in code:
+# f, _ := os.Create("trace.out")
+# trace.Start(f)
+# defer trace.Stop()
+
+# Trace viewer shows:
+# - Goroutine execution timeline
+# - Network blocking
+# - Syscall blocking
+# - Scheduler latency
+# - GC events
+```
+
+### Go Escape Analysis
+
+```bash
+# See what escapes to heap (allocations you may not expect)
+go build -gcflags '-m' ./...
+
+# More verbose
+go build -gcflags '-m -m' ./...
+
+# Common escape reasons:
+# "moved to heap: x" - variable allocated on heap instead of stack
+# "leaking param: x" - parameter escapes the function
+# "x escapes to heap" - compiler cannot prove x doesn't outlive the stack frame
+
+# Fix: reduce pointer usage, return values instead of pointers for small types,
+# use sync.Pool for frequently allocated objects
+```
+
+### GC Tuning
+
+```bash
+# GC trace logging
+GODEBUG=gctrace=1 ./myapp
+
+# Output format:
+# gc N @T% G%: wall_time+cpu_time ms clock, H->H->H MB, S MB goal, P P
+# N = GC number, T = time since start, G = fraction of CPU in GC
+# H = heap before -> after -> live, S = heap goal
+
+# Set GC target percentage (default 100 = GC when heap doubles)
+GOGC=200 ./myapp  # Less frequent GC, more memory usage
+GOGC=50 ./myapp   # More frequent GC, less memory usage
+
+# Memory limit (Go 1.19+)
+GOMEMLIMIT=1GiB ./myapp  # Hard memory limit
+```
+
+## Rust Profiling
+
+### cargo-flamegraph
+
+```bash
+# Install
+cargo install flamegraph
+
+# Generate flamegraph (release build recommended)
+cargo flamegraph --bin myapp
+cargo flamegraph --bin myapp -- --arg1 --arg2  # With arguments
+cargo flamegraph --bench my_benchmark         # Profile benchmarks
+
+# Linux: may need to set perf permissions
+echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid
+# Or run with sudo
+
+# Output: flamegraph.svg in current directory
+```
+
+### samply: Modern Profiler
+
+```bash
+# Install
+cargo install samply
+
+# Profile (opens Firefox Profiler UI)
+samply record ./target/release/myapp
+samply record ./target/release/myapp -- --arg1
+
+# samply advantages:
+# - Uses Firefox Profiler UI (excellent visualization)
+# - Shows both CPU and memory
+# - Per-thread timeline view
+# - Source code annotation
+# - No code changes needed
+```
+
+### DHAT: Dynamic Heap Analysis
+
+```bash
+# Requires nightly Rust or Valgrind
+# With Valgrind:
+valgrind --tool=dhat ./target/debug/myapp
+# Opens dhat-viewer in browser
+
+# DHAT shows:
+# - Total bytes allocated
+# - Maximum bytes live at any point
+# - Total blocks allocated
+# - Access patterns (reads/writes per block)
+# - Short-lived allocations (allocated and freed quickly)
+# - Allocation sites with full backtraces
+```
+
+### heaptrack for Rust
+
+```bash
+# Install (Linux)
+# sudo apt install heaptrack heaptrack-gui
+
+# Profile
+heaptrack ./target/release/myapp
+
+# Analyze
+heaptrack_gui heaptrack.myapp.*.zst
+
+# heaptrack shows:
+# - Allocation timeline
+# - Allocation flamegraph
+# - Peak memory consumers
+# - Temporary allocation hotspots
+# - Potential memory leaks (allocated, never freed)
+```
+
+### Rust-Specific Optimization Patterns
+
+```rust
+// Avoid unnecessary allocations
+
+// BAD: allocates a new String every call
+fn process(name: &str) -> String {
+    format!("Hello, {}!", name)
+}
+
+// GOOD: take ownership when needed, borrow otherwise
+fn process(name: &str) -> Cow<'_, str> {
+    if name.is_empty() {
+        Cow::Borrowed("Hello, stranger!")
+    } else {
+        Cow::Owned(format!("Hello, {}!", name))
+    }
+}
+
+// Use SmallVec for usually-small collections
+// use smallvec::SmallVec;
+// let mut v: SmallVec<[i32; 8]> = SmallVec::new();  // stack-allocated up to 8
+
+// Use iterators instead of collecting
+// BAD
+let filtered: Vec<_> = items.iter().filter(|x| x > &5).collect();
+let sum: i32 = filtered.iter().sum();
+
+// GOOD: no intermediate allocation
+let sum: i32 = items.iter().filter(|x| *x > &5).sum();
+
+// Pre-allocate when size is known
+let mut v = Vec::with_capacity(1000);  // One allocation
+for i in 0..1000 {
+    v.push(i);  // No reallocation
+}
+```
+
+## Browser Profiling
+
+### Chrome DevTools Performance Tab
+
+```
+Recording a performance profile:
+1. Open DevTools (F12) → Performance tab
+2. Click Record (●) or Ctrl+E
+3. Perform the action to profile
+4. Stop recording
+5. Analyze the timeline
+
+Key areas:
+├─ Network: request waterfall (blocking, TTFB, download)
+├─ Frames: FPS chart (green = 60fps, red = dropped frames)
+├─ Timings: FCP, LCP, DCL markers
+├─ Main: flame chart of main thread activity
+│  ├─ Yellow = JavaScript execution
+│  ├─ Purple = Layout/Rendering
+│  ├─ Green = Paint/Composite
+│  └─ Gray = System/Idle
+├─ Raster: paint operations
+└─ GPU: GPU activity
+
+Long Tasks (>50ms):
+- Flagged with red triangle in the timeline
+- Block the main thread, cause jank
+- Fix: break into smaller tasks with requestIdleCallback, setTimeout,
+  or scheduler.postTask
+```
+
+### Core Web Vitals
+
+```
+Metric          Target    Measures
+─────────────────────────────────────────────────────
+LCP             <2.5s     Largest Contentful Paint (perceived load)
+INP             <200ms    Interaction to Next Paint (responsiveness)
+CLS             <0.1      Cumulative Layout Shift (visual stability)
+
+Measurement tools:
+- Lighthouse: npx lighthouse https://example.com --view
+- web-vitals library: import { onLCP, onINP, onCLS } from 'web-vitals'
+- Chrome DevTools → Performance → Timings row
+- PageSpeed Insights: https://pagespeed.web.dev
+- CrUX Dashboard (real user data)
+```
+
+### React Profiler
+
+```
+React DevTools Profiler:
+1. Install React DevTools browser extension
+2. Open DevTools → Profiler tab
+3. Click Record
+4. Interact with your app
+5. Stop recording
+
+What it shows:
+- Commit-by-commit render timeline
+- Which components rendered and why
+- Render duration per component
+- Ranked chart (slowest components)
+
+Programmatic profiling:
+import { Profiler } from 'react';
+
+function onRender(id, phase, actualDuration, baseDuration, startTime, commitTime) {
+  console.log({ id, phase, actualDuration, baseDuration });
+}
+
+<Profiler id="MyComponent" onRender={onRender}>
+  <MyComponent />
+</Profiler>
+
+// phase: "mount" or "update"
+// actualDuration: time spent rendering (with memoization)
+// baseDuration: time without memoization (worst case)
+```
+
+## Memory Leak Detection Patterns
+
+### Universal Detection Strategy
+
+```
+Step 1: Confirm the leak exists
+├─ Monitor memory over time (RSS, heap)
+├─ Perform repeated action cycles (create/destroy)
+├─ Force GC between cycles
+└─ If memory grows without bound → leak confirmed
+
+Step 2: Identify the leak type
+├─ Growing collections (maps, arrays, caches without eviction)
+├─ Event listener accumulation (add without remove)
+├─ Closure captures (inner function holds reference to outer scope)
+├─ Unreleased resources (file handles, DB connections, sockets)
+├─ Circular references (in languages without cycle-collecting GC)
+├─ Global state accumulation (module-level variables growing)
+└─ Timer/interval not cleared (setInterval without clearInterval)
+
+Step 3: Locate the leak source
+├─ Take heap snapshots at different points
+├─ Compare snapshots (objects allocated between snap 1 and 2)
+├─ Sort by retained size
+├─ Follow retainer chains to find root reference
+└─ The "GC root → ... → leaked object" chain shows you what to fix
+```
+
+### Language-Specific Leak Patterns
+
+```
+JavaScript / Node.js:
+├─ Closures capturing large scope
+│  Fix: null out references, restructure to minimize capture
+├─ Event emitter listeners without removeListener
+│  Fix: AbortController, cleanup in componentWillUnmount / useEffect return
+├─ Global caches without LRU eviction
+│  Fix: Use lru-cache package, set maxSize
+├─ Detached DOM nodes
+│  Fix: Remove event listeners before removing elements
+└─ Unresolved Promises holding references
+   Fix: Add timeout, ensure rejection paths release resources
+
+Python:
+├─ __del__ preventing GC of cycles
+│  Fix: Use weakref, avoid __del__, use context managers
+├─ Module-level mutable defaults growing
+│  Fix: Reset between requests, use request-scoped storage
+├─ C extension objects not properly released
+│  Fix: Explicit cleanup, context managers
+└─ threading.local() without cleanup
+   Fix: Clean up in thread exit callback
+
+Go:
+├─ Goroutine leaks (blocked goroutines never collected)
+│  Fix: Always provide cancellation (context.WithCancel)
+├─ time.After in loops (each creates a timer)
+│  Fix: Use time.NewTimer with Reset
+├─ Slice header retaining large underlying array
+│  Fix: Copy needed elements to new slice
+└─ sync.Pool objects growing
+   Fix: Set reasonable object sizes, profile pool usage
+
+Rust:
+├─ Rc/Arc cycles
+│  Fix: Use Weak references to break cycles
+├─ Forgotten JoinHandle (task never joined/cancelled)
+│  Fix: Store and join/abort all spawned tasks
+└─ Unbounded channels
+   Fix: Use bounded channels, apply backpressure
+```
+
+### Leak Investigation Checklists
+
+```
+Node.js Leak Investigation:
+[ ] Enabled --max-old-space-size to catch OOM earlier
+[ ] Took 3+ heap snapshots at intervals
+[ ] Compared snapshots in Chrome DevTools (Objects allocated between)
+[ ] Sorted by Retained Size to find largest leaked objects
+[ ] Followed retainer chain from leaked object to GC root
+[ ] Checked event listener count: process._getActiveHandles().length
+[ ] Checked timer count: process._getActiveRequests().length
+[ ] Tested with clinic doctor for automated diagnosis
+
+Python Leak Investigation:
+[ ] Used tracemalloc to identify top allocation sites
+[ ] Compared snapshots to find growing allocations
+[ ] Used objgraph.show_growth() to find growing object types
+[ ] Used objgraph.show_backrefs() to find reference chains
+[ ] Checked gc.garbage for objects with __del__ preventing collection
+[ ] Used memray --leaks to identify unreleased memory
+[ ] Tested with gc.collect() to distinguish real leaks from delayed GC
+
+Go Leak Investigation:
+[ ] Checked goroutine count via pprof/goroutine
+[ ] Looked for goroutine profile growth over time
+[ ] Used runtime.NumGoroutine() in metrics
+[ ] Checked for blocked channel operations
+[ ] Verified all contexts have cancel called
+[ ] Used goleak in tests to catch goroutine leaks
+[ ] Compared heap profiles: pprof -diff_base
+```

skills/perf-ops/references/load-testing.md

@@ -0,0 +1,802 @@
+# Load Testing
+
+Comprehensive guide to load testing tools, methodology, and CI integration.
+
+## k6 (Grafana)
+
+### Script Structure
+
+```javascript
+// k6 script: load-test.js
+import http from 'k6/http';
+import { check, sleep, group } from 'k6';
+import { Rate, Trend, Counter } from 'k6/metrics';
+
+// Custom metrics
+const errorRate = new Rate('errors');
+const responseTime = new Trend('response_time');
+const requestCount = new Counter('total_requests');
+
+// Test configuration
+export const options = {
+  // Scenario-based configuration
+  scenarios: {
+    // Ramp up and sustain load
+    load_test: {
+      executor: 'ramping-vus',
+      startVUs: 0,
+      stages: [
+        { duration: '2m', target: 50 },   // Ramp up
+        { duration: '5m', target: 50 },   // Sustain
+        { duration: '2m', target: 0 },    // Ramp down
+      ],
+      gracefulRampDown: '30s',
+    },
+  },
+
+  // Thresholds (pass/fail criteria)
+  thresholds: {
+    http_req_duration: ['p(95)<500', 'p(99)<1000'],  // ms
+    http_req_failed: ['rate<0.01'],                   // <1% error rate
+    errors: ['rate<0.05'],                            // Custom metric
+  },
+};
+
+// Setup: runs once before test
+export function setup() {
+  const loginRes = http.post('https://api.example.com/login', {
+    username: 'testuser',
+    password: 'testpass',
+  });
+  return { token: loginRes.json('token') };
+}
+
+// Default function: runs for each VU iteration
+export default function (data) {
+  group('API endpoints', function () {
+    // GET request
+    const listRes = http.get('https://api.example.com/items', {
+      headers: { Authorization: `Bearer ${data.token}` },
+    });
+
+    check(listRes, {
+      'status is 200': (r) => r.status === 200,
+      'response time < 500ms': (r) => r.timings.duration < 500,
+      'has items': (r) => r.json('items').length > 0,
+    });
+
+    errorRate.add(listRes.status !== 200);
+    responseTime.add(listRes.timings.duration);
+    requestCount.add(1);
+
+    // POST request
+    const createRes = http.post(
+      'https://api.example.com/items',
+      JSON.stringify({ name: 'test item', value: Math.random() }),
+      {
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${data.token}`,
+        },
+      }
+    );
+
+    check(createRes, {
+      'created successfully': (r) => r.status === 201,
+    });
+
+    sleep(1); // Think time between requests
+  });
+}
+
+// Teardown: runs once after test
+export function teardown(data) {
+  http.post('https://api.example.com/cleanup', null, {
+    headers: { Authorization: `Bearer ${data.token}` },
+  });
+}
+```
+
+### k6 Executors
+
+```
+Executor selection:
+│
+├─ shared-iterations
+│  └─ Fixed total iterations split across VUs
+│     Use: "Run exactly N requests total"
+│
+├─ per-vu-iterations
+│  └─ Each VU runs exactly N iterations
+│     Use: "Each user does N actions"
+│
+├─ constant-vus
+│  └─ Fixed number of VUs for a duration
+│     Use: "Sustain N concurrent users"
+│
+├─ ramping-vus
+│  └─ VUs ramp up/down in stages
+│     Use: Standard load test pattern
+│
+├─ constant-arrival-rate
+│  └─ Fixed request rate regardless of response time
+│     Use: "Maintain exactly N RPS" (most realistic)
+│
+├─ ramping-arrival-rate
+│  └─ Request rate ramps up/down
+│     Use: "Find breaking point at increasing RPS"
+│
+└─ externally-controlled
+   └─ VUs controlled via k6 REST API
+      Use: Dynamic load adjustment during test
+```
+
+### k6 CLI Commands
+
+```bash
+# Run a test
+k6 run script.js
+
+# Run with overrides
+k6 run --vus 50 --duration 30s script.js
+k6 run --env BASE_URL=https://staging.example.com script.js
+
+# Output to various formats
+k6 run --out json=results.json script.js
+k6 run --out csv=results.csv script.js
+k6 run --out influxdb=http://localhost:8086/k6 script.js
+
+# Cloud execution (requires k6 cloud account)
+k6 cloud script.js
+
+# Convert HAR to k6 script
+k6 convert recording.har -O generated-script.js
+
+# Inspect script options without running
+k6 inspect script.js
+```
+
+### k6 Browser Testing
+
+```javascript
+import { browser } from 'k6/browser';
+
+export const options = {
+  scenarios: {
+    browser: {
+      executor: 'constant-vus',
+      vus: 1,
+      duration: '30s',
+      options: {
+        browser: {
+          type: 'chromium',
+        },
+      },
+    },
+  },
+};
+
+export default async function () {
+  const page = await browser.newPage();
+  try {
+    await page.goto('https://example.com');
+    await page.locator('input[name="username"]').fill('testuser');
+    await page.locator('input[name="password"]').fill('testpass');
+    await page.locator('button[type="submit"]').click();
+    await page.waitForNavigation();
+
+    // Measure Web Vitals
+    const lcp = await page.evaluate(() => {
+      return new Promise((resolve) => {
+        new PerformanceObserver((list) => {
+          const entries = list.getEntries();
+          resolve(entries[entries.length - 1].startTime);
+        }).observe({ type: 'largest-contentful-paint', buffered: true });
+      });
+    });
+    console.log(`LCP: ${lcp}ms`);
+  } finally {
+    await page.close();
+  }
+}
+```
+
+## Artillery
+
+### YAML Configuration
+
+```yaml
+# artillery-config.yml
+config:
+  target: "https://api.example.com"
+  phases:
+    - duration: 120    # 2 minutes
+      arrivalRate: 10  # 10 new users per second
+      name: "Warm-up"
+    - duration: 300    # 5 minutes
+      arrivalRate: 50  # 50 new users per second
+      name: "Sustained load"
+    - duration: 60
+      arrivalRate: 100
+      name: "Spike"
+
+  # Plugins
+  plugins:
+    expect: {}        # Response validation
+    metrics-by-endpoint: {} # Per-endpoint metrics
+
+  # Default headers
+  defaults:
+    headers:
+      Content-Type: "application/json"
+
+  # Variables
+  variables:
+    baseUrl: "https://api.example.com"
+
+  # Connection settings
+  http:
+    timeout: 10        # seconds
+    pool: 100          # connection pool size
+
+scenarios:
+  - name: "Browse and purchase"
+    weight: 70         # 70% of traffic
+    flow:
+      - get:
+          url: "/products"
+          expect:
+            - statusCode: 200
+            - hasProperty: "items"
+          capture:
+            - json: "$.items[0].id"
+              as: "productId"
+      - think: 3       # 3 second pause
+      - get:
+          url: "/products/{{ productId }}"
+          expect:
+            - statusCode: 200
+      - post:
+          url: "/cart"
+          json:
+            productId: "{{ productId }}"
+            quantity: 1
+          expect:
+            - statusCode: 201
+
+  - name: "Search"
+    weight: 30         # 30% of traffic
+    flow:
+      - get:
+          url: "/search?q={{ $randomString() }}"
+          expect:
+            - statusCode: 200
+```
+
+### Artillery CLI
+
+```bash
+# Run load test
+artillery run artillery-config.yml
+
+# Quick test (no config needed)
+artillery quick --count 100 --num 10 https://api.example.com
+
+# Generate HTML report
+artillery run --output report.json artillery-config.yml
+artillery report report.json
+
+# Run with environment-specific config
+artillery run -e staging artillery-config.yml
+
+# Run with Playwright (browser scenarios)
+artillery run --platform playwright artillery-browser.yml
+```
+
+## vegeta (Go)
+
+### Attack and Report
+
+```bash
+# Basic attack
+echo "GET http://localhost:8080/" | vegeta attack -duration=30s -rate=50/s | vegeta report
+
+# Multiple endpoints from file
+# targets.txt:
+# GET http://localhost:8080/api/users
+# GET http://localhost:8080/api/products
+# POST http://localhost:8080/api/orders
+# Content-Type: application/json
+# @body.json
+vegeta attack -targets=targets.txt -duration=60s -rate=100/s | vegeta report
+
+# Custom headers
+echo "GET http://localhost:8080/api/data" | \
+  vegeta attack -header "Authorization: Bearer TOKEN" -duration=30s | \
+  vegeta report
+
+# Output formats
+echo "GET http://localhost:8080/" | vegeta attack -duration=30s | vegeta report -type=text
+echo "GET http://localhost:8080/" | vegeta attack -duration=30s | vegeta report -type=json
+echo "GET http://localhost:8080/" | vegeta attack -duration=30s | vegeta report -type=hist[0,50ms,100ms,200ms,500ms,1s]
+
+# Generate latency plot (HDR histogram)
+echo "GET http://localhost:8080/" | vegeta attack -duration=60s | vegeta plot > plot.html
+
+# Encode results for later analysis
+echo "GET http://localhost:8080/" | vegeta attack -duration=60s | vegeta encode > results.json
+
+# Constant rate vs max rate
+echo "GET http://localhost:8080/" | vegeta attack -rate=0 -max-workers=100 -duration=30s | vegeta report
+# -rate=0 means "as fast as possible" with max-workers limit
+```
+
+### vegeta Report Interpretation
+
+```
+Requests      [total, rate, throughput]  3000, 100.03, 99.87
+Duration      [total, attack, wait]     30.04s, 29.99s, 49.54ms
+Latencies     [min, mean, 50, 90, 95, 99, max]  12.5ms, 48.2ms, 42.1ms, 85.3ms, 120.5ms, 250.1ms, 1.2s
+Bytes In      [total, mean]             1500000, 500.00
+Bytes Out     [total, mean]             0, 0.00
+Success       [ratio]                   99.5%
+Status Codes  [code:count]              200:2985  500:15
+
+Key metrics:
+- p50 (median): typical user experience
+- p95: 95% of users experience this or better
+- p99: tail latency (worst 1%)
+- Success ratio: anything below 99% needs investigation
+- Throughput vs rate: throughput < rate means server can't keep up
+```
+
+## wrk / wrk2
+
+### wrk: Lightweight HTTP Benchmarking
+
+```bash
+# Basic usage
+wrk -t4 -c100 -d30s http://localhost:8080/
+# -t4: 4 threads
+# -c100: 100 connections
+# -d30s: 30 second duration
+
+# With Lua script
+wrk -t4 -c100 -d30s -s script.lua http://localhost:8080/
+
+# wrk2 (constant throughput mode)
+wrk2 -t4 -c100 -d30s -R2000 http://localhost:8080/
+# -R2000: target 2000 requests/second
+```
+
+### wrk Lua Scripts
+
+```lua
+-- post-request.lua: POST with JSON body
+wrk.method = "POST"
+wrk.body   = '{"username":"test","password":"test"}'
+wrk.headers["Content-Type"] = "application/json"
+
+-- dynamic-request.lua: different paths per request
+counter = 0
+request = function()
+  counter = counter + 1
+  local path = "/api/items/" .. (counter % 1000)
+  return wrk.format("GET", path)
+end
+
+-- response.lua: validate responses
+response = function(status, headers, body)
+  if status ~= 200 then
+    wrk.thread:stop()
+  end
+end
+
+-- report.lua: custom reporting
+done = function(summary, latency, requests)
+  io.write("Latency distribution:\n")
+  for _, p in pairs({ 50, 90, 95, 99, 99.9 }) do
+    n = latency:percentile(p)
+    io.write(string.format("%g%%\t%d ms\n", p, n / 1000))
+  end
+end
+```
+
+## Locust (Python)
+
+### User Classes and Tasks
+
+```python
+# locustfile.py
+from locust import HttpUser, task, between, events
+from locust import LoadTestShape
+import json
+
+class WebsiteUser(HttpUser):
+    # Wait between requests (simulates think time)
+    wait_time = between(1, 5)
+
+    # Run once per user on start
+    def on_start(self):
+        response = self.client.post("/login", json={
+            "username": "testuser",
+            "password": "testpass"
+        })
+        self.token = response.json()["token"]
+        self.client.headers.update({
+            "Authorization": f"Bearer {self.token}"
+        })
+
+    @task(3)  # Weight: 3x more likely than weight-1 tasks
+    def browse_items(self):
+        with self.client.get("/api/items", catch_response=True) as response:
+            if response.status_code == 200:
+                items = response.json()["items"]
+                if len(items) == 0:
+                    response.failure("No items returned")
+            else:
+                response.failure(f"Status {response.status_code}")
+
+    @task(1)
+    def create_item(self):
+        self.client.post("/api/items", json={
+            "name": f"item-{self.environment.runner.user_count}",
+            "value": 42
+        })
+
+    @task(2)
+    def search(self):
+        self.client.get("/api/search?q=test")
+
+    def on_stop(self):
+        self.client.post("/logout")
+
+
+class AdminUser(HttpUser):
+    """Separate user class with different behavior"""
+    wait_time = between(5, 15)
+    weight = 1  # 1 admin for every 10 regular users (if WebsiteUser weight=10)
+
+    @task
+    def check_dashboard(self):
+        self.client.get("/admin/dashboard")
+
+
+# Custom load shape
+class StagesShape(LoadTestShape):
+    """Ramp up, sustain, spike, recover"""
+    stages = [
+        {"duration": 60,  "users": 10,  "spawn_rate": 2},
+        {"duration": 300, "users": 50,  "spawn_rate": 5},
+        {"duration": 360, "users": 200, "spawn_rate": 50},  # Spike
+        {"duration": 420, "users": 50,  "spawn_rate": 10},  # Recover
+        {"duration": 480, "users": 0,   "spawn_rate": 10},  # Ramp down
+    ]
+
+    def tick(self):
+        run_time = self.get_run_time()
+        for stage in self.stages:
+            if run_time < stage["duration"]:
+                return (stage["users"], stage["spawn_rate"])
+        return None
+```
+
+### Locust CLI
+
+```bash
+# Run with web UI (default port 8089)
+locust -f locustfile.py --host https://api.example.com
+
+# Headless mode
+locust -f locustfile.py --host https://api.example.com \
+  --headless -u 100 -r 10 --run-time 5m
+# -u: total users, -r: spawn rate per second
+
+# Distributed mode
+# Master:
+locust -f locustfile.py --master
+# Workers (on each worker machine):
+locust -f locustfile.py --worker --master-host=MASTER_IP
+
+# CSV output
+locust -f locustfile.py --headless -u 50 -r 5 --run-time 5m \
+  --csv=results --csv-full-history
+
+# HTML report
+locust -f locustfile.py --headless -u 50 -r 5 --run-time 5m \
+  --html=report.html
+```
+
+## autocannon (Node.js)
+
+### CLI and Programmatic Usage
+
+```bash
+# Basic usage
+autocannon -c 100 -d 30 http://localhost:3000
+# -c: connections, -d: duration in seconds
+
+# With pipelining (multiple requests per connection)
+autocannon -c 100 -p 10 -d 30 http://localhost:3000
+
+# POST with body
+autocannon -c 50 -d 30 -m POST \
+  -H "Content-Type=application/json" \
+  -b '{"key":"value"}' \
+  http://localhost:3000/api/data
+
+# HAR file input
+autocannon -c 100 -d 30 --har requests.har http://localhost:3000
+```
+
+```javascript
+// Programmatic usage
+const autocannon = require('autocannon');
+
+const result = await autocannon({
+  url: 'http://localhost:3000',
+  connections: 100,
+  duration: 30,
+  pipelining: 10,
+  headers: {
+    'Authorization': 'Bearer TOKEN',
+  },
+  requests: [
+    { method: 'GET', path: '/api/items' },
+    { method: 'POST', path: '/api/items', body: JSON.stringify({ name: 'test' }) },
+  ],
+});
+
+console.log('Avg latency:', result.latency.average, 'ms');
+console.log('Req/sec:', result.requests.average);
+console.log('Throughput:', result.throughput.average, 'bytes/sec');
+```
+
+## Load Testing Methodology
+
+### Test Planning
+
+```
+Before running load tests:
+│
+├─ Define objectives
+│  ├─ What SLOs must be met? (p95 < 200ms, 99.9% availability)
+│  ├─ What is expected peak traffic? (from analytics/projections)
+│  └─ What scenarios matter? (browse, search, checkout, API calls)
+│
+├─ Prepare environment
+│  ├─ Use production-like infrastructure (same specs, same config)
+│  ├─ Use realistic data volumes (not empty database)
+│  ├─ Isolate from production traffic
+│  └─ Ensure monitoring is in place (APM, metrics, logs)
+│
+├─ Create realistic scenarios
+│  ├─ Model real user behavior (browse → search → add to cart → checkout)
+│  ├─ Include think time between actions
+│  ├─ Mix of read and write operations
+│  ├─ Vary request payloads
+│  └─ Include authentication flows
+│
+└─ Establish baselines
+   ├─ Run smoke test first (verify test works at low load)
+   ├─ Record baseline metrics at known-good load
+   └─ Compare subsequent tests against baseline
+```
+
+### Test Execution Patterns
+
+```
+Ramp-Up Test:
+Users ▲
+  100 │          ┌──────────────────┐
+      │        ╱│                  │╲
+   50 │      ╱  │     Sustain      │  ╲
+      │    ╱    │                  │    ╲
+    0 │──╱─────┼──────────────────┼─────╲──
+      └────────────────────────────────────→ Time
+      0    2m       5m             7m   9m
+
+Spike Test:
+Users ▲
+  500 │         ╱╲
+      │        ╱  ╲
+  100 │───────╱    ╲───────────
+      │
+    0 │─────────────────────────→ Time
+
+Soak Test:
+Users ▲
+  100 │  ┌──────────────────────────────┐
+      │  │          4-12 hours          │
+    0 │──┘                              └──
+      └────────────────────────────────────→ Time
+
+Breakpoint Test:
+Users ▲
+  ??? │                              ╱ ← System breaks here
+      │                           ╱
+      │                        ╱
+      │                     ╱
+      │                  ╱
+    0 │───────────────╱───────────────→ Time
+      Continuously increasing until failure
+```
+
+### Results Interpretation
+
+```
+Key metrics to analyze:
+│
+├─ Latency
+│  ├─ p50 (median): typical user experience
+│  ├─ p95: most users' worst experience
+│  ├─ p99: tail latency (1 in 100 requests)
+│  ├─ p99.9: extreme tail (important at scale)
+│  └─ Compare: p99/p50 ratio > 10x suggests systemic issue
+│
+├─ Throughput
+│  ├─ Requests per second (RPS)
+│  ├─ Compare achieved vs target rate
+│  ├─ If achieved < target: server saturated
+│  └─ Watch for throughput plateau (max capacity reached)
+│
+├─ Error Rate
+│  ├─ HTTP 5xx errors: server failures
+│  ├─ HTTP 429 errors: rate limiting
+│  ├─ Timeouts: resource exhaustion
+│  ├─ Connection refused: port/socket exhaustion
+│  └─ Target: <0.1% under normal load
+│
+├─ Resource Utilization
+│  ├─ CPU: >80% sustained = at capacity
+│  ├─ Memory: growing = leak, high = needs more RAM
+│  ├─ Disk I/O: iowait >20% = I/O bottleneck
+│  ├─ Network: check bandwidth, connection count
+│  └─ Connection pools: active/waiting/idle ratios
+│
+└─ Saturation Point
+   ├─ Where latency starts increasing non-linearly
+   ├─ Where error rate begins climbing
+   ├─ Where throughput plateaus despite more load
+   └─ This is your system's practical capacity
+```
+
+### Common Findings and Fixes
+
+| Finding | Symptom | Root Cause | Fix |
+|---------|---------|------------|-----|
+| Latency spike at load | p99 jumps at N users | Connection pool exhaustion | Increase pool size, optimize queries |
+| Throughput plateau | RPS flat despite more VUs | CPU saturation | Optimize hot paths, scale horizontally |
+| Error rate climbs gradually | 5xx increases with load | Memory leak under load | Fix leak, increase memory, add limits |
+| Timeout cascade | Many timeouts after first | No circuit breaker | Add circuit breaker, retry with backoff |
+| Uneven distribution | Some pods idle, some overloaded | Bad load balancing | Fix health checks, use least-connections |
+| GC pauses | Periodic latency spikes | Large heap, GC pressure | Reduce allocations, tune GC, smaller heap |
+| DNS resolution | Intermittent slow requests | DNS lookup on every request | Connection pooling, DNS caching |
+| TLS handshake overhead | High latency on first request | No connection reuse | Keep-alive, connection pooling |
+
+## CI Integration
+
+### Performance Budgets
+
+```yaml
+# k6 thresholds as CI gates
+export const options = {
+  thresholds: {
+    http_req_duration: [
+      { threshold: 'p(95)<500', abortOnFail: true },
+      { threshold: 'p(99)<1500', abortOnFail: true },
+    ],
+    http_req_failed: [
+      { threshold: 'rate<0.01', abortOnFail: true },
+    ],
+    checks: [
+      { threshold: 'rate>0.99', abortOnFail: true },
+    ],
+  },
+};
+```
+
+### GitHub Actions Example
+
+```yaml
+# .github/workflows/load-test.yml
+name: Load Test
+on:
+  pull_request:
+    paths: ['src/**', 'package.json']
+
+jobs:
+  load-test:
+    runs-on: ubuntu-latest
+    services:
+      app:
+        image: myapp:${{ github.sha }}
+        ports:
+          - 8080:8080
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install k6
+        run: |
+          sudo gpg -k
+          sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D68
+          echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
+          sudo apt-get update
+          sudo apt-get install k6
+
+      - name: Run load test
+        run: k6 run --out json=results.json tests/load/api-test.js
+
+      - name: Compare with baseline
+        run: |
+          # Extract p95 from results
+          P95=$(jq -r '.data.metrics.http_req_duration.values["p(95)"]' results.json)
+          BASELINE=450  # ms
+          if (( $(echo "$P95 > $BASELINE" | bc -l) )); then
+            echo "::error::p95 latency regression: ${P95}ms > ${BASELINE}ms baseline"
+            exit 1
+          fi
+
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: load-test-results
+          path: results.json
+```
+
+### Baseline Comparison Strategy
+
+```
+Performance regression detection:
+│
+├─ Establish baseline
+│  ├─ Run load test on main branch after each merge
+│  ├─ Store results in a time-series DB or artifact storage
+│  └─ Track p50, p95, p99, throughput, error rate
+│
+├─ PR comparison
+│  ├─ Run same test on PR branch
+│  ├─ Compare against baseline
+│  ├─ Alert if metrics degrade beyond threshold
+│  └─ Common thresholds: >10% p95 increase, >5% throughput decrease
+│
+├─ Statistical significance
+│  ├─ Run test multiple times (3-5x) to account for noise
+│  ├─ Use statistical tests (t-test) to confirm regression
+│  └─ Avoid false positives from system noise
+│
+└─ Trend tracking
+   ├─ Plot metrics over time across releases
+   ├─ Catch gradual degradation that per-PR tests miss
+   └─ Set alerts for multi-week trends
+```
+
+### Test Data Management
+
+```
+Realistic test data:
+│
+├─ Data volume
+│  ├─ Match production data volume (or representative subset)
+│  ├─ Empty DB gives misleadingly good results
+│  └─ Index effectiveness depends on data distribution
+│
+├─ Data variety
+│  ├─ Use parameterized inputs (not same request every time)
+│  ├─ Vary payload sizes
+│  ├─ Include edge cases (long strings, Unicode, special chars)
+│  └─ Distribute IDs to avoid cache hot-spotting
+│
+├─ Data isolation
+│  ├─ Each test run should use clean or isolated data
+│  ├─ Tests that modify data should not affect next run
+│  ├─ Use database transactions/rollback or test-specific namespaces
+│  └─ Avoid accumulating data across test runs
+│
+└─ Data generation
+   ├─ k6: use SharedArray for CSV/JSON data files
+   ├─ Artillery: use CSV feeders, custom functions
+   ├─ Locust: use Python libraries (Faker) for realistic data
+   └─ General: pre-generate data, load before test
+```

skills/perf-ops/references/optimization-patterns.md

@@ -0,0 +1,646 @@
+# Optimization Patterns
+
+Proven performance optimization strategies across the stack.
+
+## Caching Strategies
+
+### Cache Selection Decision Tree
+
+```
+What are you caching?
+│
+├─ Computation result (same input → same output)
+│  ├─ In-process only
+│  │  └─ In-memory cache (LRU map, memoization)
+│  │     Eviction: LRU, LFU, TTL
+│  │     Tools: lru-cache (Node), functools.lru_cache (Python), sync.Map (Go)
+│  └─ Shared across processes/servers
+│     └─ Redis / Memcached
+│        TTL-based, key-value, sub-millisecond latency
+│
+├─ Database query result
+│  ├─ Rarely changes, expensive to compute
+│  │  └─ Materialized view (database-level cache)
+│  │     Refresh: on schedule, on trigger, on demand
+│  ├─ Changes with writes
+│  │  └─ Cache-aside pattern (read: cache → DB, write: DB → invalidate cache)
+│  └─ Read-heavy, tolerate slight staleness
+│     └─ Read replica + cache with TTL
+│
+├─ API response
+│  ├─ Same for all users
+│  │  └─ CDN cache (Cloudflare, CloudFront)
+│  │     Headers: Cache-Control, ETag, Last-Modified
+│  ├─ Varies by user but cacheable
+│  │  └─ Vary header + CDN or reverse proxy cache
+│  └─ Personalized but expensive
+│     └─ Server-side cache (Redis) with user-specific keys
+│
+├─ Static assets (JS, CSS, images)
+│  └─ CDN + long cache + content-hashed filenames
+│     Cache-Control: public, max-age=31536000, immutable
+│     Bust cache by changing filename (app.a1b2c3.js)
+│
+└─ HTML pages
+   ├─ Static content
+   │  └─ Pre-render at build time (SSG)
+   │     Cache-Control: public, max-age=3600
+   ├─ Mostly static, some dynamic
+   │  └─ Stale-while-revalidate
+   │     Cache-Control: public, max-age=60, stale-while-revalidate=3600
+   └─ Fully dynamic
+      └─ Short TTL or no-cache + ETag for conditional requests
+```
+
+### Cache Invalidation Patterns
+
+```
+Pattern: TTL (Time-To-Live)
+├─ Simplest approach: cache expires after N seconds
+├─ Pro: no coordination needed, self-healing
+├─ Con: stale data for up to TTL duration
+└─ Best for: session data, config, rate limits
+
+Pattern: Cache-Aside (Lazy Loading)
+├─ Read: check cache → miss → query DB → populate cache
+├─ Write: update DB → delete cache key (not update)
+├─ Pro: only caches what's actually requested
+├─ Con: first request after invalidation is slow (cache miss)
+└─ Best for: general purpose, most common pattern
+
+Pattern: Write-Through
+├─ Write: update cache AND DB in same operation
+├─ Pro: cache always consistent with DB
+├─ Con: write latency increases, caches unused data
+└─ Best for: read-heavy data that must be fresh
+
+Pattern: Write-Behind (Write-Back)
+├─ Write: update cache, async flush to DB
+├─ Pro: fast writes, batch DB operations
+├─ Con: data loss risk if cache crashes before flush
+└─ Best for: high-write-throughput, non-critical data (counters, analytics)
+
+Pattern: Event-Driven Invalidation
+├─ Publish event on data change, subscribers invalidate caches
+├─ Pro: low latency invalidation, decoupled
+├─ Con: eventual consistency, event delivery guarantees needed
+└─ Best for: microservices, distributed systems
+```
+
+### Cache Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| Cache without eviction | Memory grows unbounded | Set max size + LRU/LFU eviction |
+| Thundering herd | Cache expires, all requests hit DB simultaneously | Mutex/singleflight, stale-while-revalidate |
+| Cache stampede | Hot key expires under high load | Background refresh before expiry |
+| Inconsistent cache + DB | Update DB, crash before invalidating cache | Delete cache first (slightly stale reads), or use distributed transactions |
+| Caching errors | Error response cached, served to all users | Only cache successful responses, or cache with very short TTL |
+| Over-caching | Too many cache layers, hard to debug | Cache at one layer, usually closest to consumer |
+
+## Database Optimization
+
+### Indexing Strategy
+
+```
+Index selection decision tree:
+│
+├─ Query uses WHERE clause
+│  ├─ Single column filter
+│  │  └─ B-tree index on that column
+│  ├─ Multiple column filter (AND)
+│  │  └─ Composite index (most selective column first)
+│  │     CREATE INDEX idx ON table(col_a, col_b, col_c)
+│  │     Left-prefix rule: this index covers (a), (a,b), (a,b,c) queries
+│  └─ Text search (LIKE '%term%')
+│     └─ Full-text index (not B-tree, which only helps prefix LIKE 'term%')
+│
+├─ Query uses ORDER BY
+│  └─ Index matching ORDER BY columns avoids filesort
+│     Combine with WHERE columns: INDEX(where_col, order_col)
+│
+├─ Query uses JOIN
+│  └─ Index on join columns of the inner table
+│     ON a.id = b.a_id → index on b.a_id
+│
+├─ Query uses GROUP BY / DISTINCT
+│  └─ Index matching GROUP BY columns
+│
+└─ High cardinality vs low cardinality
+   ├─ High cardinality (many unique values): good index candidate
+   └─ Low cardinality (few unique values, e.g., boolean): partial index
+      CREATE INDEX idx ON orders(status) WHERE status = 'pending'
+```
+
+### Query Optimization Patterns
+
+```sql
+-- AVOID: SELECT * (fetches unnecessary columns)
+SELECT * FROM users WHERE id = 1;
+-- PREFER: select only needed columns
+SELECT id, name, email FROM users WHERE id = 1;
+
+-- AVOID: N+1 queries
+-- Python/ORM: for user in users: user.orders  (fires query per user)
+-- PREFER: eager loading
+-- SELECT * FROM users JOIN orders ON users.id = orders.user_id
+
+-- AVOID: OFFSET for pagination on large tables
+SELECT * FROM posts ORDER BY created_at DESC LIMIT 20 OFFSET 10000;
+-- PREFER: cursor-based pagination
+SELECT * FROM posts WHERE created_at < '2025-01-01' ORDER BY created_at DESC LIMIT 20;
+
+-- AVOID: functions on indexed columns in WHERE
+SELECT * FROM users WHERE LOWER(email) = 'user@example.com';
+-- PREFER: expression index or store normalized
+CREATE INDEX idx_email_lower ON users(LOWER(email));
+
+-- AVOID: implicit type conversion
+SELECT * FROM users WHERE id = '123';  -- string vs integer
+-- PREFER: correct types
+SELECT * FROM users WHERE id = 123;
+
+-- AVOID: correlated subqueries
+SELECT *, (SELECT COUNT(*) FROM orders WHERE orders.user_id = users.id) FROM users;
+-- PREFER: JOIN with GROUP BY
+SELECT users.*, COUNT(orders.id) FROM users LEFT JOIN orders ON users.id = orders.user_id GROUP BY users.id;
+```
+
+### Connection Pooling
+
+```
+Connection pool sizing:
+│
+├─ Too small
+│  └─ Requests queue waiting for connections
+│     Symptom: latency spikes, "connection pool exhausted" errors
+│
+├─ Too large
+│  └─ Database overwhelmed with connections
+│     Symptom: high memory usage on DB, mutex contention, slower queries
+│
+└─ Right size
+   └─ Formula: connections = (core_count * 2) + effective_spindle_count
+      For SSD: connections ≈ core_count * 2-3
+      For cloud DB (e.g., RDS): check instance limits
+
+Tools:
+- PostgreSQL: PgBouncer (transaction pooling, session pooling)
+- MySQL: ProxySQL
+- Java: HikariCP (fastest JVM pool)
+- Python: SQLAlchemy pool (pool_size, max_overflow, pool_timeout)
+- Node.js: built-in pool in pg, mysql2, knex
+- Go: database/sql built-in pool (SetMaxOpenConns, SetMaxIdleConns)
+```
+
+## Frontend Optimization
+
+### Code Splitting
+
+```
+When to split:
+│
+├─ Route-based splitting (most impactful)
+│  └─ Each page/route is a separate chunk
+│     React: React.lazy(() => import('./Page'))
+│     Next.js: automatic per-page
+│     Vue: defineAsyncComponent(() => import('./Page.vue'))
+│
+├─ Component-based splitting
+│  └─ Heavy components loaded on demand
+│     Modal dialogs, rich text editors, charts, maps
+│     <Suspense fallback={<Spinner />}><LazyComponent /></Suspense>
+│
+├─ Library-based splitting
+│  └─ Large libraries in separate chunks
+│     Moment.js, chart libraries, syntax highlighters
+│     // vite.config.js
+│     build: { rollupOptions: { output: {
+│       manualChunks: { vendor: ['react', 'react-dom'] }
+│     }}}
+│
+└─ Conditional feature splitting
+   └─ Features only some users need (admin panel, A/B tests)
+      const AdminPanel = lazy(() => import('./AdminPanel'))
+```
+
+### Image Optimization
+
+```
+Format selection:
+│
+├─ Photographs
+│  ├─ Best: AVIF (30-50% smaller than JPEG)
+│  ├─ Good: WebP (25-35% smaller than JPEG)
+│  └─ Fallback: JPEG (universal support)
+│
+├─ Graphics/logos with transparency
+│  ├─ Best: WebP or AVIF
+│  ├─ Good: PNG (lossless)
+│  └─ Simple graphics: SVG (scalable, tiny file size)
+│
+└─ Icons
+   └─ SVG sprites or icon fonts (not individual PNGs)
+
+Implementation:
+<picture>
+  <source srcset="image.avif" type="image/avif">
+  <source srcset="image.webp" type="image/webp">
+  <img src="image.jpg" alt="Description"
+       loading="lazy"
+       decoding="async"
+       width="800" height="600">
+</picture>
+
+Responsive images:
+<img srcset="small.jpg 400w, medium.jpg 800w, large.jpg 1200w"
+     sizes="(max-width: 600px) 400px, (max-width: 900px) 800px, 1200px"
+     src="medium.jpg" alt="Description">
+```
+
+### Critical Rendering Path
+
+```
+Optimization checklist:
+│
+├─ Critical CSS
+│  ├─ Inline above-the-fold CSS in <head>
+│  ├─ Defer non-critical CSS: <link rel="preload" as="style">
+│  └─ Tools: critical (npm package), Critters (webpack plugin)
+│
+├─ JavaScript loading
+│  ├─ <script defer>: download parallel, execute after HTML parse
+│  ├─ <script async>: download parallel, execute immediately (non-order)
+│  ├─ <script type="module">: deferred by default, strict mode
+│  └─ Move non-critical JS below the fold
+│
+├─ Resource hints
+│  ├─ <link rel="preconnect" href="https://api.example.com">
+│  │  Establish early connections to known origins
+│  ├─ <link rel="dns-prefetch" href="https://cdn.example.com">
+│  │  Resolve DNS early for third-party domains
+│  ├─ <link rel="preload" href="font.woff2" as="font" crossorigin>
+│  │  Preload critical resources (fonts, hero image, key CSS)
+│  └─ <link rel="prefetch" href="next-page.js">
+│     Prefetch resources for likely next navigation
+│
+├─ Font optimization
+│  ├─ font-display: swap (show fallback immediately)
+│  ├─ Subset fonts to used characters
+│  ├─ Preload critical fonts
+│  ├─ Use woff2 format (best compression)
+│  └─ Self-host instead of Google Fonts (one fewer connection)
+│
+└─ Layout stability (CLS)
+   ├─ Always set width/height on images and videos
+   ├─ Reserve space for ads and embeds
+   ├─ Use CSS aspect-ratio for responsive containers
+   └─ Avoid inserting content above existing content
+```
+
+## API Optimization
+
+### Response Optimization
+
+```
+Reducing payload size:
+│
+├─ Field selection (GraphQL-style)
+│  └─ GET /users/123?fields=id,name,email
+│     Only return requested fields
+│
+├─ Pagination
+│  ├─ Offset-based: ?page=3&limit=20
+│  │  Simple but slow for deep pages (OFFSET 10000)
+│  ├─ Cursor-based: ?after=cursor_abc&limit=20
+│  │  Fast at any depth, stable during inserts
+│  └─ Keyset: ?created_after=2025-01-01&limit=20
+│     Uses indexed column for efficient seeking
+│
+├─ Compression
+│  ├─ Brotli (br): best ratio for static content
+│  ├─ gzip: universal support, good for dynamic content
+│  ├─ Accept-Encoding: br, gzip
+│  └─ Skip compression for small payloads (<150 bytes)
+│
+├─ Batch endpoints
+│  └─ POST /batch with array of operations
+│     Reduces HTTP overhead, enables server-side optimization
+│
+└─ Caching headers
+   ├─ ETag + If-None-Match: 304 Not Modified (no body transfer)
+   ├─ Last-Modified + If-Modified-Since: same as ETag
+   └─ Cache-Control: max-age=60, stale-while-revalidate=600
+```
+
+### HTTP/2 and HTTP/3
+
+```
+HTTP/2 optimizations (changes from HTTP/1.1):
+│
+├─ Multiplexing: multiple requests on single connection
+│  └─ STOP: domain sharding (hurts with HTTP/2)
+│  └─ STOP: sprite sheets (individual files are fine)
+│  └─ STOP: concatenating CSS/JS into mega-bundles
+│
+├─ Server Push: server sends resources before client requests
+│  └─ Mostly deprecated: use <link rel="preload"> instead
+│
+├─ Header compression (HPACK)
+│  └─ Automatic, no action needed
+│
+└─ Stream prioritization
+   └─ Browsers handle automatically, server must support
+
+HTTP/3 (QUIC):
+├─ Faster connection setup (0-RTT)
+├─ No head-of-line blocking
+├─ Better on lossy networks (mobile)
+└─ Enable on CDN/reverse proxy (Cloudflare, nginx with quic module)
+```
+
+## Concurrency Optimization
+
+### Worker Pool Patterns
+
+```
+When to use worker pools:
+│
+├─ CPU-bound tasks
+│  ├─ Pool size = number of CPU cores
+│  ├─ Node.js: worker_threads
+│  ├─ Python: multiprocessing.Pool, ProcessPoolExecutor
+│  ├─ Go: bounded goroutine pool (semaphore pattern)
+│  └─ Rust: rayon::ThreadPool, tokio::task::spawn_blocking
+│
+├─ I/O-bound tasks
+│  ├─ Pool size = much larger than CPU cores (100s-1000s)
+│  ├─ Node.js: async/await (event loop handles concurrency)
+│  ├─ Python: asyncio, ThreadPoolExecutor for blocking I/O
+│  ├─ Go: goroutines (lightweight, thousands are fine)
+│  └─ Rust: tokio tasks (lightweight, thousands are fine)
+│
+└─ Mixed workloads
+   └─ Separate pools for CPU and I/O work
+      Don't let CPU-bound tasks block I/O pool
+      Don't let I/O waits occupy CPU pool slots
+```
+
+### Backpressure
+
+```
+Without backpressure:
+Producer (fast) → → → → → QUEUE OVERFLOW → OOM/Crash
+                          ↓ ↓ ↓ ↓ ↓ ↓ ↓
+Consumer (slow) → → →
+
+With backpressure:
+Producer (fast) → → BLOCKED (queue full)
+                          ↓ ↓ ↓
+Consumer (slow) → → → (processes at own pace)
+
+Implementation strategies:
+├─ Bounded queues: reject/block when full
+├─ Rate limiting: token bucket, leaky bucket
+├─ Circuit breaker: stop sending when consumer is unhealthy
+├─ Load shedding: drop low-priority work under pressure
+└─ Reactive streams: consumer signals demand to producer
+```
+
+### Batching
+
+```
+Individual operations:
+Request 1 → DB Query → Response
+Request 2 → DB Query → Response    Total: 100 DB queries
+Request 3 → DB Query → Response
+... (100 times)
+
+Batched operations:
+Request 1 ─┐
+Request 2 ──┤ Batch → 1 DB Query → Responses    Total: 1 DB query
+Request 3 ──┤
+... (100)  ─┘
+
+Implementation:
+├─ DataLoader pattern (GraphQL/general)
+│  Collect individual loads within one event loop tick
+│  Execute as single batch query
+│  Return individual results
+│
+├─ Bulk INSERT
+│  Collect rows, INSERT multiple in one statement
+│  INSERT INTO items (a, b) VALUES (1,2), (3,4), (5,6)
+│
+├─ Batch API calls
+│  Collect individual API calls
+│  Send as single batch request
+│  POST /batch [{method, path, body}, ...]
+│
+└─ Write coalescing
+   Buffer writes for short window (10-100ms)
+   Flush as single operation
+   Trade latency for throughput
+```
+
+## Memory Optimization
+
+### Object Pooling
+
+```
+When to pool:
+├─ Objects are expensive to create (DB connections, threads, buffers)
+├─ Objects are created and destroyed frequently
+├─ GC pressure is high (many short-lived allocations)
+└─ Object initialization involves I/O or complex setup
+
+Implementation pattern:
+Pool {
+  available: []     // Ready to use
+  in_use: []        // Currently checked out
+  max_size: N       // Maximum pool size
+
+  acquire():
+    if available.length > 0:
+      return available.pop()
+    elif in_use.length < max_size:
+      return create_new()
+    else:
+      wait_or_reject()
+
+  release(obj):
+    reset(obj)       // Clean state for reuse
+    available.push(obj)
+}
+
+Language-specific:
+- Go: sync.Pool (GC-aware, may evict items)
+- Rust: object-pool crate, crossbeam ObjectPool
+- Java: Apache Commons Pool, HikariCP (connection pool)
+- Python: queue.Queue-based custom pool
+- Node.js: generic-pool package
+```
+
+### Streaming vs Buffering
+
+```
+Buffering (load all into memory):
+├─ Simple code
+├─ Random access to data
+├─ DANGER: memory scales with data size
+└─ Max data size limited by available RAM
+
+Streaming (process chunk by chunk):
+├─ Constant memory regardless of data size
+├─ Can start processing before all data arrives
+├─ Required for: large files, real-time data, video/audio
+└─ Slightly more complex code
+
+Decision:
+├─ Data < 10MB → buffering is fine
+├─ Data > 100MB → streaming required
+├─ Data size unknown → streaming required
+├─ Real-time processing → streaming required
+└─ Need multiple passes → buffer or use temp file
+
+Examples:
+- Node.js: fs.createReadStream() vs fs.readFileSync()
+- Python: open().read() vs for line in open()
+- Go: io.Reader/io.Writer interfaces
+- Rust: BufReader/BufWriter, tokio AsyncRead/AsyncWrite
+```
+
+### String Interning
+
+```
+Problem: many duplicate strings consuming memory
+
+Before interning:
+  "status: active"  →  String { ptr: 0x1000, len: 14 }
+  "status: active"  →  String { ptr: 0x2000, len: 14 }  // Duplicate!
+  "status: active"  →  String { ptr: 0x3000, len: 14 }  // Another!
+
+After interning:
+  "status: active"  →  all point to same allocation
+
+When to use:
+├─ Many repeated string values (status fields, tags, categories)
+├─ Long-lived strings that are compared often
+└─ Parsing structured data with repetitive fields
+
+Language support:
+- Python: sys.intern() (automatic for small strings)
+- Java: String.intern() (JVM string pool)
+- Go: no built-in, use map[string]string dedup
+- Rust: string-interner crate
+- JavaScript: V8 interns short strings automatically
+```
+
+## Algorithm Optimization
+
+### Big-O Awareness
+
+```
+Common operations and their complexity:
+
+O(1)        Array index, hash map lookup, stack push/pop
+O(log n)    Binary search, balanced BST lookup, heap insert
+O(n)        Linear scan, array copy, linked list traversal
+O(n log n)  Efficient sort (merge, quick, heap sort)
+O(n²)       Nested loops, bubble sort, insertion sort
+O(2ⁿ)       Recursive Fibonacci (naive), power set
+
+Practical impact (n = 1,000,000):
+O(1)       = 1 operation
+O(log n)   = 20 operations
+O(n)       = 1,000,000 operations
+O(n log n) = 20,000,000 operations
+O(n²)      = 1,000,000,000,000 operations  ← TOO SLOW
+
+Quick wins:
+├─ Replace list search with set/hash map: O(n) → O(1)
+├─ Sort + binary search instead of linear search: O(n) → O(log n)
+├─ Replace nested loops with hash join: O(n²) → O(n)
+├─ Cache computed values (memoization): avoid redundant work
+└─ Use appropriate data structure for access pattern
+```
+
+### Data Structure Selection
+
+```
+Access pattern → best data structure:
+│
+├─ Fast lookup by key
+│  └─ Hash map / dictionary
+│     O(1) average lookup, insert, delete
+│
+├─ Ordered iteration + fast lookup
+│  └─ Balanced BST (TreeMap, BTreeMap)
+│     O(log n) lookup, insert, delete, ordered iteration
+│
+├─ Fast insert/remove at both ends
+│  └─ Deque (double-ended queue)
+│     O(1) push/pop at front and back
+│
+├─ Priority-based access (always get min/max)
+│  └─ Heap / priority queue
+│     O(1) peek min/max, O(log n) insert and extract
+│
+├─ Fast membership testing
+│  └─ Hash set
+│     O(1) contains check
+│  └─ Bloom filter (probabilistic, space-efficient)
+│     O(1) contains, may have false positives
+│
+├─ Fast prefix search / autocomplete
+│  └─ Trie
+│     O(k) lookup where k = key length
+│
+├─ Range queries (find all items between A and B)
+│  └─ Sorted array + binary search, or B-tree
+│
+└─ Graph relationships
+   ├─ Sparse graph → adjacency list
+   └─ Dense graph → adjacency matrix
+```
+
+## Anti-Patterns
+
+### Premature Optimization
+
+```
+"Premature optimization is the root of all evil" — Knuth
+
+Signs of premature optimization:
+├─ Optimizing before measuring
+├─ Optimizing code that runs once or rarely
+├─ Sacrificing readability for negligible performance gain
+├─ Optimizing at the wrong level (micro vs macro)
+└─ Optimizing before the feature is correct
+
+The right approach:
+1. Make it work (correct behavior)
+2. Make it right (clean, maintainable code)
+3. Make it fast (profile, then optimize measured bottlenecks)
+
+Exception: architectural decisions (data model, API design) are
+expensive to change later. Think about performance at design time
+for structural choices.
+```
+
+### Common Performance Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Better Approach |
+|-------------|-------------|-----------------|
+| N+1 queries | 1000 items = 1001 DB queries | Eager loading, batch queries, DataLoader |
+| Unbounded growth | Cache/queue/buffer grows without limit | Set max size, eviction policy, backpressure |
+| Synchronous I/O in async code | Blocks event loop/thread pool, kills throughput | Use async I/O throughout, offload blocking to thread pool |
+| Re-rendering everything | UI updates trigger full tree re-render | Virtual DOM diffing, memoization, fine-grained reactivity |
+| Serializing/deserializing repeatedly | Data converted between formats multiple times | Pass native objects, serialize once at boundary |
+| Polling when events are available | CPU waste checking for changes | WebSockets, SSE, file watch, pub/sub |
+| Logging in hot path | String formatting + I/O in tight loop | Sampling, async logging, log level guards |
+| Global locks | All threads contend on single mutex | Fine-grained locks, lock-free structures, sharding |
+| String concatenation in loop | O(n²) due to repeated copying | StringBuilder, join, format strings |
+| Creating regex in loop | Compile regex on every iteration | Compile once, reuse compiled pattern |
+| Deep cloning when shallow suffices | Copying entire object graph unnecessarily | Structural sharing, immutable data structures, shallow copy |
+| Catching exceptions for flow control | Exceptions are expensive (stack trace capture) | Use return values, option types, result types |

skills/refactor-ops/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: refactor-ops
+description: "Safe refactoring patterns - extract, rename, restructure with test-driven methodology and dead code detection. Use for: refactor, refactoring, extract function, extract component, rename, move file, restructure, dead code, unused imports, code smell, duplicate code, long function, god object, feature envy, DRY, technical debt, cleanup, simplify, decompose, inline, pull up, push down, strangler fig, parallel change."
+allowed-tools: "Read Edit Write Bash Glob Grep Agent"
+related-skills: [testing-ops, structural-search, debug-ops, code-stats, migrate-ops]
+---
+
+# Refactor Operations
+
+Comprehensive refactoring skill covering safe transformation patterns, code smell detection, dead code elimination, and test-driven refactoring methodology.
+
+## Refactoring Decision Tree
+
+```
+What kind of refactoring do you need?
+│
+├─ Extracting code into a new unit
+│  ├─ A block of statements with a clear purpose
+│  │  └─ Extract Function/Method
+│  │     Identify inputs (params) and outputs (return value)
+│  │
+│  ├─ A UI element with its own state or props
+│  │  └─ Extract Component (React, Vue, Svelte)
+│  │     Move JSX/template + related state into new file
+│  │
+│  ├─ Reusable stateful logic (not UI)
+│  │  └─ Extract Hook / Composable
+│  │     React: useCustomHook, Vue: useComposable
+│  │
+│  ├─ A file has grown beyond 300-500 lines
+│  │  └─ Extract Module
+│  │     Split by responsibility, create barrel exports
+│  │     Watch for circular dependencies
+│  │
+│  ├─ A class does too many things (SRP violation)
+│  │  └─ Extract Class / Service
+│  │     One responsibility per class, use dependency injection
+│  │
+│  └─ Magic numbers, hardcoded strings, env-specific values
+│     └─ Extract Configuration
+│        Constants file, env vars, feature flags
+│
+├─ Renaming for clarity
+│  ├─ Variable, function, or method
+│  │  └─ Rename Symbol
+│  │     Update all references (IDE rename or ast-grep)
+│  │
+│  ├─ File or directory
+│  │  └─ Rename File + Update Imports
+│  │     git mv to preserve history, update all import paths
+│  │
+│  └─ Module or package
+│     └─ Rename Module + Update All Consumers
+│        Search for all import/require references
+│        Consider re-exporting from old name temporarily
+│
+├─ Moving code to a better location
+│  ├─ Function/class to a different file
+│  │  └─ Move + Re-export from Original
+│  │     Leave re-export for one release cycle
+│  │
+│  ├─ Files to a different directory
+│  │  └─ Restructure + Update All Paths
+│  │     Use IDE refactoring or find-and-replace
+│  │
+│  └─ Reorganize entire directory structure
+│     └─ Incremental Migration
+│        Move one module at a time, keep tests green
+│
+├─ Simplifying existing code
+│  ├─ Function is too simple to justify its own name
+│  │  └─ Inline Function
+│  │     Replace call sites with the body
+│  │
+│  ├─ Variable used only once, right after assignment
+│  │  └─ Inline Variable
+│  │     Replace variable with expression
+│  │
+│  ├─ Deep nesting (> 3 levels)
+│  │  └─ Guard Clauses + Early Returns
+│  │     Invert conditions, return early
+│  │
+│  └─ Complex conditionals
+│     └─ Decompose Conditional
+│        Extract each branch into named function
+│
+└─ Removing dead code
+   ├─ Unused imports
+   │  └─ Lint + Auto-fix (eslint, ruff, goimports)
+   │
+   ├─ Unreachable code branches
+   │  └─ Static analysis + manual review
+   │
+   ├─ Orphaned files (no imports point to them)
+   │  └─ Dependency graph analysis (knip, ts-prune, vulture)
+   │
+   └─ Unused exports
+      └─ ts-prune, knip, or manual grep for import references
+```
+
+## Safety Checklist
+
+Run through this checklist before starting any refactoring:
+
+```
+Pre-Refactoring
+[ ] All tests pass (full suite, not just related tests)
+[ ] Working tree is clean (git status shows no uncommitted changes)
+[ ] On a dedicated branch (not main/master)
+[ ] CI is green on the base branch
+[ ] You understand what the code does (read it, don't assume)
+[ ] Characterization tests exist for untested code you will change
+
+During Refactoring
+[ ] Each commit compiles and all tests pass
+[ ] Commits are small and focused (one refactoring per commit)
+[ ] No behavior changes mixed with structural changes
+[ ] Running tests after every change (use --watch mode)
+
+Post-Refactoring
+[ ] Full test suite passes
+[ ] No new warnings from linter or type checker
+[ ] Code review requested (refactoring PRs need fresh eyes)
+[ ] Performance benchmarks unchanged (if applicable)
+[ ] Documentation updated (if public API changed)
+```
+
+## Extract Patterns Quick Reference
+
+| Pattern | When to Use | Key Considerations |
+|---------|-------------|-------------------|
+| **Extract Function** | Block of code has a clear single purpose, used or could be reused | Name should describe WHAT, not HOW. Pure functions preferred. |
+| **Extract Component** | UI element has own state, props, or rendering logic | Props interface should be minimal. Avoid prop drilling. |
+| **Extract Hook/Composable** | Stateful logic shared across components | Must start with `use`. Return stable references. |
+| **Extract Module** | File exceeds 300-500 lines, has multiple responsibilities | One module = one responsibility. Barrel exports for public API. |
+| **Extract Class/Service** | Object handles too many concerns | Dependency injection over hard-coded dependencies. |
+| **Extract Configuration** | Magic numbers, environment-specific values, feature flags | Type-safe config objects over loose constants. |
+
+## Rename Patterns Quick Reference
+
+| What to Rename | Method | Pitfalls |
+|----------------|--------|----------|
+| **Variable/function** | IDE rename (F2) or `ast-grep` | String references (logs, error messages) not caught by IDE |
+| **Class/type** | IDE rename + update file name to match | Serialized data may reference old name (JSON, DB) |
+| **File** | `git mv old new` + update all imports | Import paths in test files, storybook, config files often missed |
+| **Directory** | `git mv` + bulk import update | Barrel re-exports, path aliases in tsconfig/webpack |
+| **Package/module** | Rename + re-export from old name | External consumers need deprecation period |
+
+## Move/Restructure Quick Reference
+
+| Scenario | Strategy | Safety Net |
+|----------|----------|------------|
+| **Single file move** | `git mv` + update imports + re-export from old path | `rg 'old/path'` to find all references |
+| **Multiple related files** | Move together, update barrel exports | Run type checker after each move |
+| **Directory restructure** | Incremental: one directory per PR | Keep old paths working via re-exports |
+| **Monorepo package split** | Extract to new package, update all consumers | Version the new package, pin consumers |
+
+## Dead Code Detection Workflow
+
+```
+Step 1: Automated Detection
+│
+├─ TypeScript/JavaScript
+│  ├─ knip (comprehensive: files, deps, exports)
+│  │  └─ npx knip --reporter compact
+│  ├─ ts-prune (unused exports)
+│  │  └─ npx ts-prune
+│  └─ eslint (unused vars/imports)
+│     └─ eslint --rule 'no-unused-vars: error'
+│
+├─ Python
+│  ├─ vulture (dead code finder)
+│  │  └─ vulture src/ --min-confidence 80
+│  ├─ ruff (unused imports)
+│  │  └─ ruff check --select F401
+│  └─ coverage.py (unreachable branches)
+│     └─ coverage run && coverage report --show-missing
+│
+├─ Go
+│  └─ staticcheck / golangci-lint
+│     └─ golangci-lint run --enable unused,deadcode
+│
+├─ Rust
+│  └─ Compiler warnings (dead_code, unused_imports)
+│     └─ cargo build 2>&1 | rg 'warning.*unused'
+│
+Step 2: Manual Verification
+│  ├─ Check if "unused" code is used via reflection/dynamic import
+│  ├─ Check if exports are part of public API consumed externally
+│  ├─ Check if code is used in scripts, tests, or tooling not in the scan
+│  └─ Check if code is behind a feature flag or A/B test
+│
+Step 3: Remove with Confidence
+│  ├─ Remove in small batches, not all at once
+│  ├─ One commit per logical group of dead code
+│  └─ Keep git history -- you can always recover
+```
+
+## Code Smell Detection
+
+| Smell | Heuristic | Refactoring |
+|-------|-----------|-------------|
+| **Long function** | > 20 lines or > 5 levels of indentation | Extract Function, Decompose Conditional |
+| **God object** | Class with > 10 methods or > 500 lines | Extract Class, Split by responsibility |
+| **Feature envy** | Method uses another object's data more than its own | Move Method to the class whose data it uses |
+| **Duplicate code** | Same logic in 2+ places (> 5 similar lines) | Extract Function, Extract Module |
+| **Deep nesting** | > 3 levels of if/for/while nesting | Guard Clauses, Early Returns, Extract Function |
+| **Primitive obsession** | Using strings/numbers where a type would be safer | Value Objects, Branded Types, Enums |
+| **Shotgun surgery** | One change requires editing 5+ files | Move related code together, Extract Module |
+| **Dead code** | Unreachable branches, unused exports/imports | Delete it (git has history) |
+| **Data clumps** | Same group of parameters passed together repeatedly | Extract Parameter Object or Config Object |
+| **Long parameter list** | Function takes > 4 parameters | Extract Parameter Object, Builder Pattern |
+
+## Test-Driven Refactoring Methodology
+
+```
+Refactoring Untested Code
+│
+├─ Step 1: Write Characterization Tests
+│  │  Capture CURRENT behavior, even if it seems wrong
+│  │  These tests document what the code actually does
+│  └─ Goal: safety net, not correctness proof
+│
+├─ Step 2: Verify Coverage
+│  │  Run coverage tool, ensure all paths you will touch are covered
+│  └─ Add more tests if coverage is insufficient
+│
+├─ Step 3: Refactor in Small Steps
+│  │  One transformation at a time
+│  │  Run tests after EVERY change
+│  └─ If tests fail, undo and try smaller step
+│
+├─ Step 4: Improve Tests
+│  │  Now that code is cleaner, write better tests
+│  │  Replace characterization tests with intention-revealing tests
+│  └─ Add edge cases discovered during refactoring
+│
+└─ Step 5: Commit and Review
+   │  Separate commits: tests first, then refactoring
+   └─ Reviewers can verify tests pass on old code too
+```
+
+## Tool Reference
+
+| Tool | Language | Use Case | Command |
+|------|----------|----------|---------|
+| **ast-grep** | Multi | Structural search and replace | `sg -p 'console.log($$$)' -r '' -l js` |
+| **jscodeshift** | JS/TS | Large-scale AST-based codemods | `jscodeshift -t transform.js src/` |
+| **eslint --fix** | JS/TS | Auto-fix lint violations | `eslint --fix 'src/**/*.ts'` |
+| **ruff** | Python | Fast linting and auto-fix | `ruff check --fix src/` |
+| **goimports** | Go | Organize imports | `goimports -w .` |
+| **clippy** | Rust | Lint and suggest improvements | `cargo clippy --fix` |
+| **knip** | JS/TS | Find unused files, deps, exports | `npx knip` |
+| **ts-prune** | TS | Find unused exports | `npx ts-prune` |
+| **vulture** | Python | Find dead code | `vulture src/ --min-confidence 80` |
+| **rope** | Python | Refactoring library | Python API for rename, extract, move |
+| **IDE rename** | All | Rename with reference updates | F2 in VS Code, Shift+F6 in JetBrains |
+| **sd** | All | Find and replace in files | `sd 'oldName' 'newName' src/**/*.ts` |
+
+## Common Gotchas
+
+| Gotcha | Why It Happens | Prevention |
+|--------|---------------|------------|
+| Refactoring and behavior change in same commit | Tempting to "fix while you're in there" | Separate commits: refactor first, then change behavior |
+| Breaking public API during internal refactor | Renamed/moved exports consumed by external code | Re-export from old path, deprecation warnings |
+| Circular dependencies after extracting modules | New module imports from original, original imports from new | Dependency graph check after each extraction |
+| Tests pass but runtime breaks | Tests mock the refactored code, hiding the break | Integration tests alongside unit tests |
+| git history lost after file move | Used `cp` + `rm` instead of `git mv` | Always `git mv`, verify with `git log --follow` |
+| Renaming misses string references | IDE rename only catches code references, not configs/docs | `rg 'oldName'` across entire repo after rename |
+| Over-abstracting (premature DRY) | Extracting after seeing only 2 occurrences | Rule of three: wait for 3 duplicates before extracting |
+| Extracting coupled code | New function has 8 parameters because code is entangled | Refactor coupling first, then extract |
+| Dead code removal breaks reflection/plugins | Dynamic imports, dependency injection, decorators | Grep for string references, check plugin registries |
+| Performance regression after extraction | Extra function calls, lost inlining, cache misses | Benchmark before and after for hot paths |
+| Merge conflicts from large refactoring PR | Long-lived branch diverges from main | Small PRs, merge main frequently, or use stacked PRs |
+| Type errors after moving files | Path aliases, tsconfig paths, barrel exports not updated | Run type checker after every file move |
+
+## Reference Files
+
+| File | Contents | Lines |
+|------|----------|-------|
+| `references/extract-patterns.md` | Extract function, component, hook, module, class, configuration -- with before/after examples in multiple languages | ~700 |
+| `references/code-smells.md` | Code smell catalog with detection heuristics, tools by language, complexity metrics | ~650 |
+| `references/safe-methodology.md` | Test-driven refactoring, strangler fig, parallel change, branch by abstraction, feature flags, rollback | ~550 |
+
+## See Also
+
+| Skill | When to Combine |
+|-------|----------------|
+| `testing-ops` | Write characterization tests before refactoring, test strategy for refactored code |
+| `structural-search` | Use ast-grep for structural find-and-replace across codebase |
+| `debug-ops` | When refactoring exposes hidden bugs or introduces regressions |
+| `code-stats` | Measure complexity before and after refactoring to quantify improvement |
+| `migrate-ops` | Large-scale migrations that require systematic refactoring |
+| `git-workflow` | Branch strategy for refactoring PRs, stacked PRs, bisect to find regressions |

skills/refactor-ops/references/code-smells.md

@@ -0,0 +1,743 @@
+# Code Smells Reference
+
+Comprehensive catalog of code smells with detection heuristics, refactoring prescriptions, tooling by language, and complexity metrics.
+
+---
+
+## Smell Catalog
+
+### Long Function / Method
+
+**Heuristic:** > 20 lines, > 5 levels of indentation, or cyclomatic complexity > 10.
+
+**Why it's a smell:** Long functions do too many things. They are hard to name, hard to test, hard to reuse, and hard to understand. Each additional responsibility multiplies the cognitive load.
+
+**Detection:**
+
+```
+Function length check
+│
+├─ Count lines (excluding blanks and comments)
+│  ├─ < 10 lines → Fine
+│  ├─ 10-20 lines → Monitor
+│  ├─ 20-50 lines → Likely needs extraction
+│  └─ > 50 lines → Almost certainly too long
+│
+└─ Count indentation levels
+   ├─ 1-2 levels → Normal
+   ├─ 3 levels → Borderline
+   └─ 4+ levels → Extract inner blocks
+```
+
+**Refactoring options:**
+- Extract Function (most common)
+- Decompose Conditional (if/else chains)
+- Replace Loop with Pipeline (map/filter/reduce)
+- Replace Method with Method Object (when extraction needs too many params)
+
+**Example -- Before:**
+
+```python
+def process_application(app):
+    # Validate
+    if not app.name:
+        raise ValueError("Name required")
+    if not app.email or "@" not in app.email:
+        raise ValueError("Valid email required")
+    if app.age < 18:
+        raise ValueError("Must be 18+")
+
+    # Score
+    score = 0
+    if app.gpa > 3.5:
+        score += 30
+    elif app.gpa > 3.0:
+        score += 20
+    else:
+        score += 10
+
+    if app.experience_years > 5:
+        score += 40
+    elif app.experience_years > 2:
+        score += 25
+    else:
+        score += 10
+
+    if app.has_certification:
+        score += 20
+
+    # Decide
+    if score >= 70:
+        status = "accepted"
+    elif score >= 50:
+        status = "waitlisted"
+    else:
+        status = "rejected"
+
+    # Persist and notify
+    app.score = score
+    app.status = status
+    db.save(app)
+    send_email(app.email, f"Your application was {status}")
+    return app
+```
+
+**Example -- After:**
+
+```python
+def process_application(app):
+    validate_application(app)
+    score = calculate_score(app)
+    status = determine_status(score)
+    return finalize_application(app, score, status)
+```
+
+---
+
+### God Object / God Class
+
+**Heuristic:** > 10 public methods, > 500 lines, > 7 dependencies injected, or the class name contains "Manager", "Handler", "Processor", "Service" without a specific domain qualifier.
+
+**Why it's a smell:** A class that knows too much or does too much becomes a bottleneck. Every change risks breaking unrelated functionality. It attracts more responsibilities because "it already handles X, so let's add Y."
+
+**Detection:**
+
+```
+Signs of a God Object
+│
+├─ Class has 10+ public methods
+├─ Constructor takes 5+ dependencies
+├─ Multiple unrelated groups of methods
+│  (some deal with users, others with billing, others with notifications)
+├─ Methods don't use most of the class's fields
+│  (low cohesion -- methods only touch a subset of state)
+├─ Class is imported by > 20 other files
+└─ Changes to the class are in every PR
+```
+
+**Refactoring options:**
+- Extract Class (split by responsibility)
+- Extract Interface (define role-specific interfaces)
+- Move Method (move methods to the class whose data they use)
+- Facade Pattern (keep the god object as a thin coordinator)
+
+**TypeScript example -- identifying responsibilities:**
+
+```typescript
+// BEFORE: UserManager does everything
+class UserManager {
+  // Group 1: Authentication
+  login(email, password) { /* ... */ }
+  logout(userId) { /* ... */ }
+  resetPassword(email) { /* ... */ }
+
+  // Group 2: Profile management
+  updateProfile(userId, data) { /* ... */ }
+  uploadAvatar(userId, file) { /* ... */ }
+  getPreferences(userId) { /* ... */ }
+
+  // Group 3: Billing
+  createSubscription(userId, plan) { /* ... */ }
+  cancelSubscription(userId) { /* ... */ }
+  processPayment(userId, amount) { /* ... */ }
+
+  // Group 4: Notifications
+  sendWelcomeEmail(userId) { /* ... */ }
+  sendInvoice(userId) { /* ... */ }
+  updateNotificationPrefs(userId, prefs) { /* ... */ }
+}
+
+// AFTER: Split by responsibility
+class AuthService { login, logout, resetPassword }
+class ProfileService { updateProfile, uploadAvatar, getPreferences }
+class BillingService { createSubscription, cancelSubscription, processPayment }
+class NotificationService { sendWelcomeEmail, sendInvoice, updateNotificationPrefs }
+```
+
+---
+
+### Feature Envy
+
+**Heuristic:** A method accesses another object's data more than its own. Count field accesses -- if > 50% reference another class, the method probably belongs there.
+
+**Why it's a smell:** The method is in the wrong place. It has more affinity for another class's data, which means changes to that class's data structure will also require changing this method.
+
+**Detection:**
+
+```python
+# Feature Envy: this method is in OrderService but only touches Product data
+class OrderService:
+    def calculate_discount(self, product):
+        if product.category == "electronics" and product.price > 500:
+            return product.price * product.bulk_discount_rate
+        elif product.is_seasonal and product.days_until_expiry < 30:
+            return product.price * 0.25
+        return 0
+```
+
+**Fix: Move to the class whose data it uses:**
+
+```python
+class Product:
+    def calculate_discount(self) -> float:
+        if self.category == "electronics" and self.price > 500:
+            return self.price * self.bulk_discount_rate
+        elif self.is_seasonal and self.days_until_expiry < 30:
+            return self.price * 0.25
+        return 0
+```
+
+**Exception:** Feature envy is acceptable when:
+- You intentionally keep logic separate from data (e.g., pure functions operating on DTOs)
+- The "envied" class is a simple data transfer object with no behavior
+- Moving the method would create a circular dependency
+
+---
+
+### Duplicate Code
+
+**Heuristic:** Same logic in 2+ places, differing only in variable names or minor details. > 5 lines of near-identical code is a strong signal.
+
+**Why it's a smell:** When you fix a bug in one copy, you must find and fix all copies. You will forget one. Duplicated code also inflates the codebase, making it harder to navigate.
+
+**DRY vs WET vs AHA:**
+
+```
+Duplication Strategy
+│
+├─ 1 occurrence → Leave it alone
+│
+├─ 2 occurrences → Note it, but don't extract yet (WET: Write Everything Twice)
+│  │  Reason: You don't yet know the right abstraction
+│  └─ Exception: If the two are truly identical and likely to stay so, extract
+│
+├─ 3+ occurrences → Extract (AHA: Avoid Hasty Abstractions)
+│  │  Now you have enough examples to see the real pattern
+│  └─ Extract with parameters for the varying parts
+│
+└─ Wrong abstraction is worse than duplication
+   If the shared code diverges, it's OK to un-DRY and duplicate again
+```
+
+**Detection tools:**
+
+| Language | Tool | Command |
+|----------|------|---------|
+| JavaScript/TypeScript | jscpd | `npx jscpd src/ --min-lines 5` |
+| Python | pylint | `pylint --disable=all --enable=duplicate-code src/` |
+| Multi-language | PMD CPD | `pmd cpd --minimum-tokens 50 --dir src/` |
+| Any | ast-grep | Write a pattern to find structural duplicates |
+| IDE | IntelliJ | Analyze > Locate Duplicates |
+
+**Example -- Extract with parameterization:**
+
+```typescript
+// BEFORE: Two near-identical functions
+function sendWelcomeEmail(user: User) {
+  const template = loadTemplate('welcome');
+  const html = render(template, { name: user.name, date: new Date() });
+  await mailer.send({ to: user.email, subject: 'Welcome!', html });
+  await analytics.track('email_sent', { type: 'welcome', userId: user.id });
+}
+
+function sendPasswordResetEmail(user: User, token: string) {
+  const template = loadTemplate('password-reset');
+  const html = render(template, { name: user.name, token, date: new Date() });
+  await mailer.send({ to: user.email, subject: 'Password Reset', html });
+  await analytics.track('email_sent', { type: 'password-reset', userId: user.id });
+}
+
+// AFTER: Parameterized
+interface EmailParams {
+  templateName: string;
+  subject: string;
+  extraData?: Record<string, unknown>;
+}
+
+async function sendEmail(user: User, params: EmailParams) {
+  const template = loadTemplate(params.templateName);
+  const html = render(template, { name: user.name, date: new Date(), ...params.extraData });
+  await mailer.send({ to: user.email, subject: params.subject, html });
+  await analytics.track('email_sent', { type: params.templateName, userId: user.id });
+}
+
+// Usage
+await sendEmail(user, { templateName: 'welcome', subject: 'Welcome!' });
+await sendEmail(user, { templateName: 'password-reset', subject: 'Password Reset', extraData: { token } });
+```
+
+---
+
+### Deep Nesting
+
+**Heuristic:** > 3 levels of indentation from nesting if/for/while/try blocks.
+
+**Why it's a smell:** Each level of nesting adds cognitive load. The reader must mentally track every condition that led to the current branch. Error handling and happy path become interleaved and hard to follow.
+
+**Refactoring techniques:**
+
+#### Guard Clauses (Early Returns)
+
+```typescript
+// BEFORE: nested
+function processPayment(order: Order) {
+  if (order) {
+    if (order.items.length > 0) {
+      if (order.paymentMethod) {
+        if (order.total > 0) {
+          // actual logic buried 4 levels deep
+          return chargePayment(order);
+        } else {
+          throw new Error('Invalid total');
+        }
+      } else {
+        throw new Error('No payment method');
+      }
+    } else {
+      throw new Error('No items');
+    }
+  } else {
+    throw new Error('No order');
+  }
+}
+
+// AFTER: guard clauses
+function processPayment(order: Order) {
+  if (!order) throw new Error('No order');
+  if (order.items.length === 0) throw new Error('No items');
+  if (!order.paymentMethod) throw new Error('No payment method');
+  if (order.total <= 0) throw new Error('Invalid total');
+
+  return chargePayment(order);
+}
+```
+
+#### Replace Nested Loops with Pipeline
+
+```python
+# BEFORE
+results = []
+for user in users:
+    if user.is_active:
+        for order in user.orders:
+            if order.total > 100:
+                results.append({
+                    "user": user.name,
+                    "order": order.id,
+                    "total": order.total,
+                })
+
+# AFTER
+results = [
+    {"user": u.name, "order": o.id, "total": o.total}
+    for u in users if u.is_active
+    for o in u.orders if o.total > 100
+]
+```
+
+#### Extract Inner Block
+
+```go
+// BEFORE
+func processRecords(records []Record) error {
+    for _, record := range records {
+        if record.IsValid() {
+            for _, field := range record.Fields {
+                if field.NeedsTransform() {
+                    // 20 lines of transformation logic
+                }
+            }
+        }
+    }
+    return nil
+}
+
+// AFTER
+func processRecords(records []Record) error {
+    for _, record := range records {
+        if !record.IsValid() {
+            continue
+        }
+        if err := transformFields(record.Fields); err != nil {
+            return err
+        }
+    }
+    return nil
+}
+
+func transformFields(fields []Field) error {
+    for _, field := range fields {
+        if !field.NeedsTransform() {
+            continue
+        }
+        if err := transformField(field); err != nil {
+            return err
+        }
+    }
+    return nil
+}
+```
+
+---
+
+### Primitive Obsession
+
+**Heuristic:** Using raw strings, numbers, or booleans to represent domain concepts that have validation rules or behavior.
+
+**Why it's a smell:** A string can hold any value, but an email address cannot. Primitive obsession means validation logic is scattered across every place the value is used, or worse, missing entirely.
+
+**Examples:**
+
+```typescript
+// BEFORE: Primitives everywhere
+function createUser(
+  email: string,        // Could be "not-an-email"
+  age: number,          // Could be -5 or 999
+  role: string,         // Could be "superadmin-hacker"
+  currency: string,     // Could be "DOGECOIN"
+  amount: number,       // Dollars? Cents? Yen?
+) { /* ... */ }
+
+// AFTER: Value objects / branded types
+type Email = string & { readonly __brand: 'Email' };
+type Age = number & { readonly __brand: 'Age' };
+type Role = 'admin' | 'editor' | 'viewer';
+type Currency = 'USD' | 'EUR' | 'GBP';
+interface Money { amount: number; currency: Currency; }
+
+function createEmail(raw: string): Email {
+  if (!/^[^@]+@[^@]+\.[^@]+$/.test(raw)) throw new Error('Invalid email');
+  return raw as Email;
+}
+
+function createAge(raw: number): Age {
+  if (raw < 0 || raw > 150) throw new Error('Invalid age');
+  return raw as Age;
+}
+```
+
+```rust
+// Rust: newtypes
+struct Email(String);
+struct Age(u8);
+
+impl Email {
+    fn new(raw: &str) -> Result<Self, ValidationError> {
+        if raw.contains('@') { Ok(Email(raw.to_string())) }
+        else { Err(ValidationError::InvalidEmail) }
+    }
+}
+
+impl Age {
+    fn new(raw: u8) -> Result<Self, ValidationError> {
+        if raw > 0 && raw < 150 { Ok(Age(raw)) }
+        else { Err(ValidationError::InvalidAge) }
+    }
+}
+```
+
+```python
+# Python: dataclass value objects
+@dataclass(frozen=True)
+class Email:
+    value: str
+
+    def __post_init__(self):
+        if "@" not in self.value:
+            raise ValueError(f"Invalid email: {self.value}")
+
+@dataclass(frozen=True)
+class Money:
+    amount: Decimal
+    currency: str
+
+    def __add__(self, other: "Money") -> "Money":
+        if self.currency != other.currency:
+            raise ValueError("Cannot add different currencies")
+        return Money(self.amount + other.amount, self.currency)
+```
+
+---
+
+### Shotgun Surgery
+
+**Heuristic:** A single logical change requires editing 5+ files. The opposite of god object -- responsibility is spread too thin.
+
+**Why it's a smell:** Every change is a scavenger hunt. Easy to miss one of the N files that need updating, leading to inconsistencies.
+
+**Detection:**
+
+```
+Signs of Shotgun Surgery
+│
+├─ Adding a new field requires changes in:
+│  model + serializer + validator + API + UI + test + migration + docs
+│
+├─ git log shows that certain groups of files always change together
+│  └─ git log --name-only --pretty=format: | sort | uniq -c | sort -rn
+│
+└─ Code review comments: "Did you update X too?"
+```
+
+**Refactoring options:**
+- Move Method / Move Field to consolidate related logic
+- Inline Class (merge overly-split classes)
+- Create a module that owns the entire concept end-to-end
+
+---
+
+### Dead Code
+
+**Heuristic:** Code that is never executed -- unused imports, unreachable branches, commented-out code, exports with no importers, functions never called.
+
+**Why it's a smell:** Dead code confuses readers ("is this important?"), increases maintenance burden, and can mask bugs. It adds noise to search results and IDE navigation.
+
+**Detection by language:**
+
+```
+Dead Code Detection
+│
+├─ TypeScript / JavaScript
+│  ├─ knip → comprehensive (files, exports, deps, types)
+│  │  └─ npx knip
+│  ├─ ts-prune → unused exports
+│  │  └─ npx ts-prune
+│  ├─ eslint → unused vars, unreachable code
+│  │  └─ no-unused-vars, no-unreachable
+│  └─ webpack-bundle-analyzer → unused modules in bundle
+│
+├─ Python
+│  ├─ vulture → unused functions, variables, imports
+│  │  └─ vulture src/ --min-confidence 80
+│  ├─ ruff → unused imports (F401), unreachable code
+│  │  └─ ruff check --select F401,F811
+│  └─ coverage.py → branches never executed in tests
+│
+├─ Go
+│  ├─ Compiler → unused imports (error), unused vars (error)
+│  ├─ staticcheck → unused functions, types, fields
+│  │  └─ staticcheck ./...
+│  └─ golangci-lint → deadcode, unused linters
+│
+├─ Rust
+│  ├─ Compiler → dead_code, unused_imports warnings
+│  │  └─ cargo build 2>&1 | rg 'warning.*unused'
+│  └─ cargo-udeps → unused dependencies
+│     └─ cargo +nightly udeps
+│
+└─ Manual checks
+   ├─ Search for commented-out code blocks → delete them
+   ├─ Search for TODO/FIXME referencing removed features
+   └─ Check feature flags for permanently-off features
+```
+
+**Safe removal strategy:**
+
+1. Verify the code is truly dead (not used via reflection, dynamic import, or external consumers)
+2. Remove in small batches, run full test suite after each
+3. One commit per logical group of dead code
+4. Keep the PR focused: dead code removal only, no behavior changes
+
+---
+
+### Data Clumps
+
+**Heuristic:** The same group of 3+ values appears together repeatedly as function parameters, constructor args, or data fields.
+
+**Why it's a smell:** The group of values represents a concept that deserves its own name and type. Without it, you duplicate validation and the relationship between the values is implicit.
+
+**Example:**
+
+```typescript
+// BEFORE: Data clump (lat, lng, altitude appear together repeatedly)
+function calculateDistance(lat1: number, lng1: number, alt1: number,
+                           lat2: number, lng2: number, alt2: number): number { /* ... */ }
+
+function formatLocation(lat: number, lng: number, alt: number): string { /* ... */ }
+
+function isWithinBounds(lat: number, lng: number, alt: number,
+                         bounds: Bounds): boolean { /* ... */ }
+
+// AFTER: Extract parameter object
+interface GeoPoint {
+  lat: number;
+  lng: number;
+  altitude: number;
+}
+
+function calculateDistance(from: GeoPoint, to: GeoPoint): number { /* ... */ }
+function formatLocation(point: GeoPoint): string { /* ... */ }
+function isWithinBounds(point: GeoPoint, bounds: Bounds): boolean { /* ... */ }
+```
+
+---
+
+### Long Parameter List
+
+**Heuristic:** A function takes more than 4 parameters. Even 3 can be too many if they are all the same type (easy to swap by mistake).
+
+**Why it's a smell:** Hard to remember argument order. Easy to swap two arguments of the same type. Adding a parameter requires updating all call sites.
+
+**Refactoring options:**
+
+```
+Too many parameters?
+│
+├─ Parameters represent a concept → Extract Parameter Object
+│  (firstName, lastName, email, phone → ContactInfo)
+│
+├─ Parameters are configuration → Builder Pattern or Options Object
+│  (timeout, retries, baseUrl, headers → ClientOptions)
+│
+├─ Some parameters are always the same → Set defaults or partial application
+│  (logger, config are always the same → inject via constructor)
+│
+└─ Parameters are independent concerns → Split into multiple functions
+   (validate(data, rules, locale, format) → validate(data, rules) + format(data, locale))
+```
+
+---
+
+## Complexity Metrics
+
+### Cyclomatic Complexity
+
+Counts the number of independent paths through a function. Each `if`, `else`, `for`, `while`, `case`, `catch`, `&&`, `||` adds 1 to the count.
+
+| Score | Risk | Action |
+|-------|------|--------|
+| 1-5 | Low | No action needed |
+| 6-10 | Moderate | Consider simplification |
+| 11-20 | High | Refactor: extract functions, decompose conditionals |
+| > 20 | Very High | Mandatory refactoring |
+
+**Measurement tools:**
+
+| Language | Tool | Command |
+|----------|------|---------|
+| JavaScript | eslint complexity rule | `eslint --rule 'complexity: ["error", 10]'` |
+| Python | radon | `radon cc src/ -a -nc` |
+| Go | gocyclo | `gocyclo -over 10 .` |
+| Rust | cargo-geiger | Measures unsafe code complexity |
+| Multi | SonarQube | Dashboard with complexity metrics |
+
+### Cognitive Complexity
+
+A newer metric (from SonarSource) that better reflects human reading difficulty. Unlike cyclomatic complexity, it penalizes nesting and rewards linear flow.
+
+Key differences from cyclomatic complexity:
+- Nested `if` inside `for` scores higher than sequential `if` then `for`
+- Early returns (`guard clauses`) reduce complexity
+- `switch` counts once, not per case
+- Boolean operator sequences (`a && b && c`) count once
+
+### Coupling and Cohesion
+
+```
+Coupling (between modules) — LOWER is better
+│
+├─ Afferent Coupling (Ca): How many modules depend ON this module
+│  High Ca = changing this module breaks many things
+│
+├─ Efferent Coupling (Ce): How many modules this module depends ON
+│  High Ce = this module is fragile (many reasons to change)
+│
+└─ Instability = Ce / (Ca + Ce)
+   0.0 = maximally stable (many dependents, few dependencies)
+   1.0 = maximally unstable (few dependents, many dependencies)
+
+Cohesion (within a module) — HIGHER is better
+│
+├─ Every method uses every field → perfectly cohesive
+├─ Methods split into groups using different fields → low cohesion
+│  → Split into multiple classes
+└─ Measured by LCOM (Lack of Cohesion of Methods)
+   LCOM = 0 → perfectly cohesive
+   LCOM > 0 → methods don't relate to each other
+```
+
+---
+
+## Detection Tools by Language
+
+### JavaScript / TypeScript
+
+| Tool | Detects | Install | Command |
+|------|---------|---------|---------|
+| **eslint** | Unused vars, complexity, unreachable code | `npm i -D eslint` | `eslint --rule 'complexity: ["error", 10]' src/` |
+| **knip** | Unused files, exports, deps, types | `npm i -D knip` | `npx knip` |
+| **ts-prune** | Unused exports | `npm i -D ts-prune` | `npx ts-prune` |
+| **jscpd** | Copy-paste detection | `npm i -D jscpd` | `npx jscpd src/ --min-lines 5` |
+| **SonarQube** | Comprehensive (complexity, duplication, smells) | Server install | Web dashboard |
+
+### Python
+
+| Tool | Detects | Install | Command |
+|------|---------|---------|---------|
+| **ruff** | Unused imports, vars, complexity, style | `pip install ruff` | `ruff check --select ALL src/` |
+| **vulture** | Dead code (functions, vars, imports) | `pip install vulture` | `vulture src/ --min-confidence 80` |
+| **radon** | Cyclomatic + Halstead complexity | `pip install radon` | `radon cc src/ -a -nc` |
+| **pylint** | Duplicate code, design smells | `pip install pylint` | `pylint --disable=all --enable=R src/` |
+| **wily** | Complexity trends over time | `pip install wily` | `wily build src/ && wily report src/module.py` |
+
+### Go
+
+| Tool | Detects | Install | Command |
+|------|---------|---------|---------|
+| **golangci-lint** | Meta-linter (50+ linters) | Binary install | `golangci-lint run` |
+| **gocyclo** | Cyclomatic complexity | `go install` | `gocyclo -over 10 .` |
+| **goconst** | Repeated strings/numbers | Part of golangci-lint | `golangci-lint run --enable goconst` |
+| **dupl** | Duplicate code | Part of golangci-lint | `golangci-lint run --enable dupl` |
+| **staticcheck** | Unused code, bugs, simplifications | `go install` | `staticcheck ./...` |
+
+### Rust
+
+| Tool | Detects | Install | Command |
+|------|---------|---------|---------|
+| **clippy** | Lint, style, complexity, correctness | Built-in | `cargo clippy -- -W clippy::all` |
+| **cargo-udeps** | Unused dependencies | `cargo install` | `cargo +nightly udeps` |
+| **cargo-geiger** | Unsafe code usage | `cargo install` | `cargo geiger` |
+| **Compiler** | Dead code, unused imports/vars | Built-in | `#[deny(dead_code, unused)]` |
+
+---
+
+## Smell Prioritization
+
+Not all smells are equally urgent. Prioritize based on impact:
+
+```
+Triage Smells
+│
+├─ Fix NOW (blocks work or causes bugs)
+│  ├─ Dead code that confuses newcomers
+│  ├─ Duplicate code that has already diverged (bug in one copy)
+│  └─ God object that causes merge conflicts every sprint
+│
+├─ Fix SOON (increasing maintenance cost)
+│  ├─ Long functions (> 50 lines)
+│  ├─ Deep nesting (> 4 levels)
+│  └─ Shotgun surgery (every feature touches 10 files)
+│
+├─ Fix LATER (annoyances, not blockers)
+│  ├─ Primitive obsession (works but fragile)
+│  ├─ Data clumps (inconvenient but functional)
+│  └─ Moderate duplication (2 copies, stable)
+│
+└─ Maybe NEVER (acceptable trade-offs)
+   ├─ Generated code (don't refactor auto-generated files)
+   ├─ Legacy code with no tests (write tests first)
+   └─ Code scheduled for replacement
+```
+
+---
+
+## Anti-patterns in Smell Remediation
+
+| Anti-pattern | Problem | Better Approach |
+|--------------|---------|-----------------|
+| Refactoring without tests | Cannot verify behavior is preserved | Write characterization tests first |
+| Premature DRY | Wrong abstraction extracted from 2 examples | Wait for 3+ examples (AHA principle) |
+| Big-bang refactor | Everything breaks at once, can't bisect | Small, incremental changes with tests after each |
+| Gold plating | Refactoring beyond what is needed for the task | Refactor only the code you are actively working on |
+| Refactoring old stable code "just because" | Risk with no business value | Only refactor when you need to change it |
+| Introducing patterns without need | Design patterns are solutions to problems, not goals | Pattern should reduce complexity, not add it |

skills/refactor-ops/references/safe-methodology.md

@@ -0,0 +1,620 @@
+# Safe Refactoring Methodology Reference
+
+Strategies for large and small refactorings that preserve behavior, minimize risk, and provide rollback safety.
+
+---
+
+## Test-Driven Refactoring
+
+### The Core Loop
+
+```
+Red-Green-Refactor (for new code)
+│
+├─ RED: Write a failing test for the desired behavior
+├─ GREEN: Write the simplest code that makes the test pass
+└─ REFACTOR: Clean up while keeping tests green
+   └─ This is where refactoring happens safely
+
+Characterization-Then-Refactor (for existing code)
+│
+├─ Step 1: Write Characterization Tests
+│  │  Run the existing code and capture its actual output
+│  │  Assert on that output, even if it seems wrong
+│  │  Goal: document what the code DOES, not what it SHOULD do
+│  │
+│  │  Example:
+│  │  def test_calculate_tax_current_behavior():
+│  │      # This may be "wrong" but it's what the code does today
+│  │      assert calculate_tax(100) == 8.25  # captures actual behavior
+│  │
+│  └─ Coverage: ensure every branch you will touch is covered
+│
+├─ Step 2: Refactor Under Test Safety
+│  │  Make one small change
+│  │  Run all characterization tests
+│  │  If tests pass → commit and continue
+│  │  If tests fail → revert and try smaller change
+│  └─ Never refactor and change behavior in the same step
+│
+├─ Step 3: Replace Characterization Tests
+│  │  Once code is clean, write proper intention-revealing tests
+│  │  The characterization tests served as scaffolding
+│  └─ Now you can safely fix behavioral bugs you discovered
+│
+└─ Step 4: Fix Behavioral Issues (if any)
+   Now that you have proper tests and clean code,
+   fix any bugs discovered during characterization
+   Each fix gets its own test + commit
+```
+
+### Writing Effective Characterization Tests
+
+```python
+# Strategy: Use the code itself to tell you what to assert
+
+# 1. Call the function with representative inputs
+result = process_order(sample_order)
+
+# 2. Print the result
+print(result)  # {'total': 108.25, 'tax': 8.25, 'status': 'pending'}
+
+# 3. Assert on the printed output
+def test_process_order_characterization():
+    result = process_order(sample_order)
+    assert result['total'] == 108.25
+    assert result['tax'] == 8.25
+    assert result['status'] == 'pending'
+
+# 4. Cover edge cases the same way
+def test_process_order_empty_items():
+    result = process_order(Order(items=[]))
+    # Even if this behavior is "wrong", capture it
+    assert result['total'] == 0
+    assert result['status'] == 'pending'  # maybe should be 'invalid'?
+```
+
+### When You Cannot Write Tests First
+
+Sometimes characterization tests are impractical (tightly coupled UI, external service dependencies, time-based logic). Alternatives:
+
+```
+Cannot write characterization tests?
+│
+├─ Too coupled to test → Extract the testable parts first
+│  Use "Sprout Method" or "Sprout Class":
+│  1. Write the new logic in a new, testable function
+│  2. Call it from the old code
+│  3. Test the new function
+│  4. Gradually move more logic into testable functions
+│
+├─ External service dependency → Record and replay
+│  Use VCR/Polly/nock to record real responses
+│  Replay them in tests
+│
+├─ UI-heavy → Snapshot/Approval tests
+│  Capture screenshots or HTML output
+│  Compare against approved baseline
+│
+└─ Time-based logic → Inject a clock
+   Pass a clock/timer as a parameter
+   Use a fake clock in tests
+```
+
+---
+
+## Strangler Fig Pattern
+
+For replacing a large legacy system or module incrementally, without a risky big-bang rewrite.
+
+```
+Strangler Fig Strategy
+│
+├─ Phase 1: Identify boundaries
+│  │  Map the legacy system's entry points (API routes, function calls, events)
+│  │  Each entry point is a candidate for strangling
+│  └─ Prioritize by: risk (low first), value (high first), coupling (loose first)
+│
+├─ Phase 2: Build new implementation alongside old
+│  │  New code lives in a new module/service
+│  │  Both old and new exist simultaneously
+│  └─ No modification to legacy code yet
+│
+├─ Phase 3: Route traffic to new implementation
+│  │  Use a router/proxy/feature flag to direct requests
+│  │  Start with a small percentage (canary)
+│  │  Monitor for errors and performance differences
+│  └─ Gradually increase percentage
+│
+├─ Phase 4: Remove legacy code
+│  │  Once 100% traffic goes to new implementation
+│  │  Keep legacy code for one release cycle (rollback safety)
+│  └─ Then delete it
+│
+└─ Repeat for each entry point
+```
+
+### Example: Strangling a Legacy API Endpoint
+
+```typescript
+// Phase 2: New implementation alongside old
+// old: /api/v1/users (legacy monolith)
+// new: /api/v2/users (new service)
+
+// Phase 3: Router decides which to call
+app.get('/api/users', async (req, res) => {
+  const useNewImplementation = await featureFlag('new-users-api', {
+    userId: req.user?.id,
+    percentage: 25,  // Start with 25% of traffic
+  });
+
+  if (useNewImplementation) {
+    return newUsersService.getUsers(req, res);
+  }
+  return legacyUsersController.getUsers(req, res);
+});
+
+// Phase 4: Once at 100%, simplify
+app.get('/api/users', (req, res) => newUsersService.getUsers(req, res));
+```
+
+---
+
+## Parallel Change (Expand-Migrate-Contract)
+
+For changing an interface without breaking consumers. Three phases: expand (add new), migrate (move consumers), contract (remove old).
+
+```
+Parallel Change Phases
+│
+├─ EXPAND: Add the new interface alongside the old
+│  │  Both old and new work simultaneously
+│  │  Old interface delegates to new implementation internally
+│  └─ All existing tests continue to pass
+│
+├─ MIGRATE: Update all consumers to use the new interface
+│  │  One consumer at a time
+│  │  Each migration is a separate commit/PR
+│  │  Old interface still works (backward compatible)
+│  └─ Monitor for issues after each migration
+│
+└─ CONTRACT: Remove the old interface
+   │  All consumers now use the new interface
+   │  Delete old code and update tests
+   └─ This is the only "breaking" change
+```
+
+### Example: Renaming a Function
+
+```python
+# EXPAND: Add new name, keep old as alias
+def calculate_shipping_cost(order: Order) -> Money:
+    """New name with improved logic."""
+    # ... implementation ...
+
+def calcShipping(order: Order) -> Money:
+    """Deprecated: Use calculate_shipping_cost instead."""
+    import warnings
+    warnings.warn("calcShipping is deprecated, use calculate_shipping_cost", DeprecationWarning)
+    return calculate_shipping_cost(order)
+
+# MIGRATE: Update all call sites one by one
+# grep for calcShipping, replace with calculate_shipping_cost
+# Run tests after each file
+
+# CONTRACT: Remove old function
+# Delete calcShipping entirely
+# Remove deprecation warning
+```
+
+### Example: Changing a Database Schema
+
+```sql
+-- EXPAND: Add new column alongside old
+ALTER TABLE users ADD COLUMN full_name VARCHAR(255);
+
+-- Application code writes to BOTH columns
+-- UPDATE users SET full_name = first_name || ' ' || last_name, ...
+
+-- MIGRATE: Backfill existing data
+-- UPDATE users SET full_name = first_name || ' ' || last_name WHERE full_name IS NULL;
+-- Update all queries to read from full_name
+
+-- CONTRACT: Remove old columns
+-- ALTER TABLE users DROP COLUMN first_name, DROP COLUMN last_name;
+```
+
+---
+
+## Branch by Abstraction
+
+For replacing an internal implementation without feature branches. Introduce an abstraction layer, swap the implementation behind it.
+
+```
+Branch by Abstraction
+│
+├─ Step 1: Create abstraction (interface/protocol/trait)
+│  │  Define the contract that both old and new implementations satisfy
+│  └─ All existing code uses the abstraction, not the concrete implementation
+│
+├─ Step 2: Wrap existing implementation
+│  │  Make existing code implement the new abstraction
+│  └─ All tests pass -- no behavior change
+│
+├─ Step 3: Build new implementation
+│  │  New implementation also satisfies the abstraction
+│  │  Test new implementation independently
+│  └─ Old implementation is still the default
+│
+├─ Step 4: Switch
+│  │  Change the wiring to use new implementation
+│  │  Feature flag or config toggle for easy rollback
+│  └─ Monitor in production
+│
+└─ Step 5: Clean up
+   Remove old implementation
+   Remove abstraction if only one implementation remains
+   Remove feature flag
+```
+
+### Example:
+
+```typescript
+// Step 1: Define abstraction
+interface PaymentGateway {
+  charge(amount: Money, card: CardInfo): Promise<PaymentResult>;
+  refund(paymentId: string, amount: Money): Promise<RefundResult>;
+}
+
+// Step 2: Wrap existing implementation
+class StripeGateway implements PaymentGateway {
+  async charge(amount: Money, card: CardInfo): Promise<PaymentResult> {
+    // existing Stripe code, now behind the interface
+  }
+  async refund(paymentId: string, amount: Money): Promise<RefundResult> {
+    // existing Stripe refund code
+  }
+}
+
+// Step 3: Build new implementation
+class SquareGateway implements PaymentGateway {
+  async charge(amount: Money, card: CardInfo): Promise<PaymentResult> {
+    // new Square implementation
+  }
+  async refund(paymentId: string, amount: Money): Promise<RefundResult> {
+    // new Square refund implementation
+  }
+}
+
+// Step 4: Switch via configuration
+function createPaymentGateway(): PaymentGateway {
+  if (config.paymentProvider === 'square') {
+    return new SquareGateway();
+  }
+  return new StripeGateway(); // default/fallback
+}
+```
+
+---
+
+## Small Commits Strategy
+
+Every commit during a refactoring must satisfy two invariants:
+
+1. **Code compiles** (type-checks, no syntax errors)
+2. **All tests pass** (no behavioral regressions)
+
+### Commit Granularity Guide
+
+```
+Refactoring Commit Patterns
+│
+├─ Rename → 1 commit
+│  "refactor: rename calcShipping to calculateShippingCost"
+│
+├─ Extract Function → 1 commit
+│  "refactor: extract validateOrderItems from processOrder"
+│
+├─ Move File → 1 commit
+│  "refactor: move utils/helpers.ts to lib/string-utils.ts"
+│
+├─ Extract Class → 2-3 commits
+│  1. "refactor: extract PriceCalculator interface"
+│  2. "refactor: implement PriceCalculator, delegate from OrderService"
+│  3. "refactor: remove pricing logic from OrderService"
+│
+├─ Replace Algorithm → 2 commits
+│  1. "test: add characterization tests for sorting"
+│  2. "refactor: replace bubble sort with merge sort"
+│
+└─ Large Restructure → Many small commits
+   Each file move or extraction is its own commit
+   Never batch unrelated changes
+```
+
+### Git Workflow for Refactoring
+
+```bash
+# Start a refactoring session
+git checkout -b refactor/extract-payment-service
+
+# After each small refactoring step
+git add -p  # Stage only the relevant changes
+git commit -m "refactor: extract PaymentValidator from PaymentService"
+
+# Verify at each step
+npm test  # or pytest, cargo test, go test ./...
+
+# If a step goes wrong, revert just that step
+git revert HEAD
+
+# When done, create a clean PR
+# Each commit should be reviewable independently
+```
+
+---
+
+## Feature Flags for Gradual Rollout
+
+When a refactoring affects runtime behavior (e.g., new algorithm, new data flow), use feature flags to control rollout.
+
+```
+Feature Flag Strategy
+│
+├─ Before refactoring
+│  │  Add a feature flag that defaults to OFF (old behavior)
+│  └─ Deploy the flag infrastructure
+│
+├─ During refactoring
+│  │  New code path guarded by the flag
+│  │  Old code path remains the default
+│  └─ Both paths are tested
+│
+├─ Rollout
+│  │  Enable for internal users first
+│  │  Enable for 1% → 10% → 50% → 100%
+│  │  Monitor error rates, latency, correctness
+│  └─ Rollback = disable the flag (instant, no deploy needed)
+│
+└─ Cleanup
+   Remove the flag and old code path
+   This is a separate PR after the rollout is complete
+```
+
+### Implementation Pattern
+
+```typescript
+// Simple feature flag check
+async function searchProducts(query: string): Promise<Product[]> {
+  if (await featureFlags.isEnabled('new-search-algorithm', { userId })) {
+    return newSearchAlgorithm(query);
+  }
+  return legacySearch(query);
+}
+```
+
+### Feature Flag Hygiene
+
+| Rule | Why |
+|------|-----|
+| Remove flags within 2 sprints of 100% rollout | Stale flags accumulate and confuse |
+| Name flags descriptively | `new-search-algorithm` not `flag-123` |
+| Log flag evaluations | Debug which path was taken |
+| Test both paths | Both old and new must have coverage |
+| Flag owner documented | Someone must clean up the flag |
+
+---
+
+## Approval Testing / Snapshot Testing
+
+Capture the output of existing code and use it as the test assertion. Ideal for characterization testing before refactoring.
+
+### How It Works
+
+```
+Approval Testing Flow
+│
+├─ First run: Capture output → save as "approved" baseline
+│  ├─ HTML output → screenshot or HTML snapshot
+│  ├─ JSON output → save formatted JSON
+│  ├─ Console output → save text
+│  └─ API response → save response body
+│
+├─ Subsequent runs: Compare output against baseline
+│  ├─ Match → test passes
+│  └─ Mismatch → test fails, show diff
+│     ├─ If expected change → approve new baseline
+│     └─ If unexpected change → regression, investigate
+│
+└─ During refactoring: any output change is flagged
+   You decide if the change is intentional or a bug
+```
+
+### Tools
+
+| Language | Tool | Type |
+|----------|------|------|
+| JavaScript | Jest snapshots | `expect(result).toMatchSnapshot()` |
+| JavaScript | Storybook Chromatic | Visual regression |
+| Python | pytest-snapshot | `snapshot.assert_match(result)` |
+| Python | Approval Tests | `verify(result)` |
+| Go | go-snaps | `snaps.MatchSnapshot(t, result)` |
+| Rust | insta | `insta::assert_snapshot!(result)` |
+| Any | screenshot comparison | Playwright, Cypress, Percy |
+
+### Jest Snapshot Example
+
+```typescript
+// Before refactoring: create baseline
+test('renders user profile', () => {
+  const { container } = render(<UserProfile user={mockUser} />);
+  expect(container.innerHTML).toMatchSnapshot();
+});
+
+// During refactoring: any HTML change will fail this test
+// If the change is intentional:
+//   npx jest --updateSnapshot
+```
+
+### Python Approval Test Example
+
+```python
+from approvaltests import verify
+
+def test_generate_report():
+    report = generate_report(sample_data)
+    verify(report)  # First run saves "approved" file
+                    # Subsequent runs compare against it
+```
+
+---
+
+## Rollback Strategies
+
+```
+Rollback Options (fastest to slowest)
+│
+├─ Feature flag toggle (seconds)
+│  └─ Disable the flag → old code path runs instantly
+│     No deployment needed
+│
+├─ Git revert (minutes)
+│  └─ git revert <commit-hash>
+│     Creates a new commit that undoes the change
+│     Deploy the revert
+│
+├─ Redeploy previous version (minutes-hours)
+│  └─ Roll back to previous container image / release tag
+│     CI/CD pipeline handles the rest
+│
+├─ Database rollback (hours-days)
+│  └─ If schema changed: run reverse migration
+│     If data changed: restore from backup
+│     Most disruptive, avoid if possible
+│
+└─ Cannot rollback (prevention only)
+   Deleted data, sent emails, external API calls
+   Design for forward-fix instead
+```
+
+### Forward-Fix vs Rollback Decision
+
+```
+Should you rollback or fix forward?
+│
+├─ Is the bug causing data loss or corruption?
+│  └─ ROLLBACK immediately, fix later
+│
+├─ Is the bug affecting > 10% of users?
+│  └─ ROLLBACK, then fix forward on a branch
+│
+├─ Is the fix obvious and small (< 5 lines)?
+│  └─ FIX FORWARD with expedited review
+│
+├─ Is the bug cosmetic or low-severity?
+│  └─ FIX FORWARD in next regular release
+│
+└─ Are you unsure of the scope?
+   └─ ROLLBACK (when in doubt, be safe)
+```
+
+---
+
+## Code Review Checklist for Refactoring PRs
+
+```
+Reviewer Checklist
+│
+├─ Behavior Preservation
+│  [ ] No functional changes mixed with structural changes
+│  [ ] Test suite passes (check CI, not just author's word)
+│  [ ] Snapshot/approval tests show no unexpected diffs
+│  [ ] Public API unchanged (or deprecated properly)
+│
+├─ Quality of Refactoring
+│  [ ] Each commit is atomic and independently valid
+│  [ ] Naming improves clarity (not just different)
+│  [ ] Abstraction level is appropriate (not over-engineered)
+│  [ ] No new duplication introduced
+│  [ ] No circular dependencies introduced
+│
+├─ Safety
+│  [ ] Characterization tests exist for changed code
+│  [ ] Feature flag or rollback plan documented (if applicable)
+│  [ ] Performance-sensitive code benchmarked before/after
+│  [ ] No dead code left behind (old implementations removed)
+│
+└─ Completeness
+   [ ] All references updated (imports, configs, docs, tests)
+   [ ] Deprecation warnings added for public API changes
+   [ ] Migration guide for downstream consumers (if applicable)
+```
+
+---
+
+## Measuring Refactoring Success
+
+Refactoring is an investment. Measure whether it paid off.
+
+### Quantitative Metrics
+
+| Metric | Before/After | Tool |
+|--------|-------------|------|
+| **Cyclomatic complexity** | Should decrease | radon, eslint, gocyclo |
+| **Cognitive complexity** | Should decrease | SonarQube |
+| **File length** | Should decrease (god files → smaller modules) | tokei, wc -l |
+| **Test coverage** | Should increase or stay the same | coverage.py, istanbul, tarpaulin |
+| **Build time** | Should not increase significantly | CI pipeline timing |
+| **Bundle size** | Should not increase (may decrease with dead code removal) | webpack-bundle-analyzer |
+| **Deployment frequency** | Should increase (easier to ship) | DORA metrics |
+| **Change failure rate** | Should decrease (fewer regressions) | DORA metrics |
+
+### Qualitative Indicators
+
+| Signal | Meaning |
+|--------|---------|
+| Fewer merge conflicts in the area | Code is better organized, less contention |
+| New features in the area are faster to build | Reduced coupling and clear boundaries |
+| Fewer bug reports in the area | Cleaner code, better error handling |
+| Team members are less afraid to change the code | Improved testability and readability |
+| Code review comments shift from "I don't understand" to "looks good" | Better naming and structure |
+
+### Before/After Comparison Template
+
+```bash
+# Capture BEFORE metrics
+echo "=== BEFORE ==="
+tokei src/module-to-refactor/          # Line counts
+radon cc src/module-to-refactor/ -a    # Cyclomatic complexity (Python)
+npx knip --reporter compact            # Unused code (JS/TS)
+
+# ... do the refactoring ...
+
+# Capture AFTER metrics
+echo "=== AFTER ==="
+tokei src/module-to-refactor/
+radon cc src/module-to-refactor/ -a
+npx knip --reporter compact
+
+# Compare
+# Complexity should go down
+# Line count may go up slightly (more files, smaller each)
+# Unused code count should go down
+```
+
+---
+
+## Anti-Patterns in Refactoring Methodology
+
+| Anti-pattern | Problem | Better Approach |
+|--------------|---------|-----------------|
+| Big-bang rewrite | High risk, nothing works for weeks | Strangler fig: replace incrementally |
+| Refactoring without a goal | Endless polishing, no business value | Define success criteria before starting |
+| Refactoring everything at once | Merge conflicts, hard to review, hard to rollback | One module at a time, one PR at a time |
+| Skipping characterization tests | No safety net, cannot verify behavior preserved | Always capture current behavior first |
+| Mixing refactoring with features | Cannot tell which caused a regression | Separate PRs: refactor first, then add feature |
+| Not measuring improvement | Cannot justify the time investment | Capture before/after metrics |
+| Stopping halfway | Half-old, half-new is worse than either | Plan for completion, or don't start |
+| Over-designing for the future | YAGNI -- you are not going to need it | Refactor for today's needs, not hypothetical future |
+| Refactoring shared library without coordinating consumers | Breaks downstream teams | Parallel change + deprecation period |
+| No rollback plan | Stuck if something goes wrong in production | Always have a path back: feature flag, git revert, or previous deploy |

skills/scaffold/SKILL.md

@@ -0,0 +1,548 @@
+---
+name: scaffold
+description: "Project scaffolding - generate boilerplate for common project types with best-practice defaults. Use for: scaffold, boilerplate, template, new project, init, create project, starter, setup, project structure, directory structure, monorepo, microservice, API template, web app template, CLI tool template, library template."
+allowed-tools: "Read Edit Write Bash Glob Grep Agent"
+related-skills: [docker-ops, ci-cd-ops, testing-ops, python-env, typescript-ops]
+---
+
+# Scaffold
+
+Project scaffolding templates and boilerplate generation for common project types with best-practice defaults.
+
+## Project Type Decision Tree
+
+```
+What are you building?
+│
+├─ API / Backend Service
+│  ├─ REST API
+│  │  ├─ Python → FastAPI (async, OpenAPI auto-docs)
+│  │  ├─ Node.js → Express or Fastify (Fastify for performance)
+│  │  ├─ Go → Gin (ergonomic) or Echo (middleware-rich)
+│  │  └─ Rust → Axum (tower ecosystem, async-first)
+│  ├─ GraphQL API
+│  │  ├─ Python → Strawberry + FastAPI
+│  │  ├─ Node.js → Apollo Server or Pothos + Yoga
+│  │  ├─ Go → gqlgen (code-first)
+│  │  └─ Rust → async-graphql + Axum
+│  └─ gRPC Service
+│     ├─ Python → grpcio + protobuf
+│     ├─ Go → google.golang.org/grpc
+│     └─ Rust → tonic
+│
+├─ Web Application
+│  ├─ Full-stack with SSR
+│  │  ├─ React ecosystem → Next.js 14+ (App Router)
+│  │  ├─ Vue ecosystem → Nuxt 3
+│  │  ├─ Svelte ecosystem → SvelteKit
+│  │  └─ Content-heavy / multi-framework → Astro
+│  ├─ SPA (client-only)
+│  │  ├─ React → Vite + React + React Router
+│  │  ├─ Vue → Vite + Vue + Vue Router
+│  │  └─ Svelte → Vite + Svelte + svelte-routing
+│  └─ Static Site
+│     ├─ Blog / docs → Astro or VitePress
+│     └─ Marketing / landing → Astro or Next.js (static export)
+│
+├─ CLI Tool
+│  ├─ Python → Typer (simple) or Click (complex)
+│  ├─ Node.js → Commander + Inquirer
+│  ├─ Go → Cobra + Viper
+│  └─ Rust → Clap (derive API)
+│
+├─ Library / Package
+│  ├─ npm package → TypeScript + tsup + Vitest
+│  ├─ PyPI package → uv + pyproject.toml + pytest
+│  ├─ Go module → go mod init + go test
+│  └─ Rust crate → cargo init --lib + cargo test
+│
+└─ Monorepo
+   ├─ JavaScript/TypeScript → Turborepo + pnpm workspaces
+   ├─ Full-stack JS → Nx
+   ├─ Go → Go workspaces (go.work)
+   ├─ Rust → Cargo workspaces
+   └─ Python → uv workspaces or hatch
+```
+
+## Stack Selection Matrix
+
+| Project Type | Language | Framework | Database | ORM/Query | Deploy Target |
+|-------------|----------|-----------|----------|-----------|---------------|
+| REST API | Python | FastAPI | PostgreSQL | SQLAlchemy + Alembic | Docker / AWS ECS |
+| REST API | Node.js | Fastify | PostgreSQL | Prisma or Drizzle | Docker / Vercel |
+| REST API | Go | Gin | PostgreSQL | sqlx (raw) or GORM | Docker / Fly.io |
+| REST API | Rust | Axum | PostgreSQL | sqlx | Docker / Fly.io |
+| Web App | TypeScript | Next.js 14+ | PostgreSQL | Prisma or Drizzle | Vercel / Docker |
+| Web App | TypeScript | Nuxt 3 | PostgreSQL | Prisma | Vercel / Netlify |
+| Web App | TypeScript | Astro | SQLite / none | Drizzle | Cloudflare / Netlify |
+| CLI Tool | Python | Typer | SQLite | sqlite3 stdlib | PyPI |
+| CLI Tool | Go | Cobra | SQLite / BoltDB | sqlx | GitHub Releases |
+| CLI Tool | Rust | Clap | SQLite | rusqlite | crates.io |
+| Library | TypeScript | tsup | n/a | n/a | npm |
+| Library | Python | hatch/uv | n/a | n/a | PyPI |
+
+## Quick Scaffold Commands
+
+### Python (API)
+
+```bash
+# FastAPI with uv
+mkdir my-api && cd my-api
+uv init --python 3.12
+uv add fastapi uvicorn sqlalchemy alembic psycopg2-binary pydantic-settings
+uv add --dev pytest pytest-asyncio httpx ruff mypy
+```
+
+### Node.js (Web App)
+
+```bash
+# Next.js 14+
+npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
+
+# Vite + React
+npm create vite@latest my-app -- --template react-ts
+```
+
+### Go (API)
+
+```bash
+mkdir my-api && cd my-api
+go mod init github.com/user/my-api
+go get github.com/gin-gonic/gin
+go get github.com/jmoiron/sqlx
+go get github.com/lib/pq
+```
+
+### Rust (CLI)
+
+```bash
+cargo init my-cli
+cd my-cli
+cargo add clap --features derive
+cargo add serde --features derive
+cargo add anyhow tokio --features tokio/full
+```
+
+### Monorepo (Turborepo)
+
+```bash
+npx create-turbo@latest my-monorepo
+# Or manual:
+mkdir my-monorepo && cd my-monorepo
+npm init -y
+npm install turbo --save-dev
+mkdir -p apps/web apps/api packages/shared
+```
+
+## API Project Template
+
+### Directory Structure (FastAPI Example)
+
+```
+my-api/
+├── src/
+│   └── my_api/
+│       ├── __init__.py
+│       ├── main.py              # FastAPI app, lifespan, middleware
+│       ├── config.py            # pydantic-settings configuration
+│       ├── database.py          # SQLAlchemy engine, session
+│       ├── dependencies.py      # Shared FastAPI dependencies
+│       ├── routers/
+│       │   ├── __init__.py
+│       │   ├── health.py        # Health check endpoint
+│       │   └── users.py         # User CRUD endpoints
+│       ├── models/
+│       │   ├── __init__.py
+│       │   └── user.py          # SQLAlchemy models
+│       ├── schemas/
+│       │   ├── __init__.py
+│       │   └── user.py          # Pydantic request/response schemas
+│       └── services/
+│           ├── __init__.py
+│           └── user.py          # Business logic
+├── alembic/
+│   ├── alembic.ini
+│   ├── env.py
+│   └── versions/
+├── tests/
+│   ├── conftest.py              # Fixtures: test DB, client, factories
+│   ├── test_health.py
+│   └── test_users.py
+├── pyproject.toml
+├── Dockerfile
+├── docker-compose.yml
+├── .env.example
+├── .gitignore
+└── .dockerignore
+```
+
+### Directory Structure (Express/Fastify Example)
+
+```
+my-api/
+├── src/
+│   ├── index.ts                 # Entry point, server startup
+│   ├── app.ts                   # Express/Fastify app setup
+│   ├── config.ts                # Environment config with zod validation
+│   ├── database.ts              # Prisma client or Drizzle config
+│   ├── middleware/
+│   │   ├── auth.ts
+│   │   ├── error-handler.ts
+│   │   └── request-logger.ts
+│   ├── routes/
+│   │   ├── health.ts
+│   │   └── users.ts
+│   ├── services/
+│   │   └── user.service.ts
+│   └── types/
+│       └── index.ts
+├── prisma/
+│   └── schema.prisma
+├── tests/
+│   ├── setup.ts
+│   └── routes/
+│       └── users.test.ts
+├── package.json
+├── tsconfig.json
+├── Dockerfile
+├── docker-compose.yml
+├── .env.example
+└── .gitignore
+```
+
+## Web App Project Template
+
+### Directory Structure (Next.js App Router)
+
+```
+my-app/
+├── src/
+│   ├── app/
+│   │   ├── layout.tsx           # Root layout
+│   │   ├── page.tsx             # Home page
+│   │   ├── loading.tsx          # Global loading UI
+│   │   ├── error.tsx            # Global error boundary
+│   │   ├── not-found.tsx        # 404 page
+│   │   ├── globals.css          # Global styles + Tailwind
+│   │   ├── (auth)/
+│   │   │   ├── login/page.tsx
+│   │   │   └── register/page.tsx
+│   │   ├── dashboard/
+│   │   │   ├── layout.tsx
+│   │   │   └── page.tsx
+│   │   └── api/
+│   │       └── health/route.ts
+│   ├── components/
+│   │   ├── ui/                  # Reusable primitives
+│   │   └── features/            # Feature-specific components
+│   ├── lib/
+│   │   ├── db.ts                # Database client
+│   │   ├── auth.ts              # Auth helpers
+│   │   └── utils.ts             # Shared utilities
+│   └── types/
+│       └── index.ts
+├── public/
+│   └── favicon.ico
+├── tests/
+│   ├── setup.ts
+│   └── components/
+├── next.config.ts
+├── tailwind.config.ts
+├── tsconfig.json
+├── package.json
+├── .env.local.example
+└── .gitignore
+```
+
+## CLI Tool Project Template
+
+### Directory Structure (Python / Typer)
+
+```
+my-cli/
+├── src/
+│   └── my_cli/
+│       ├── __init__.py
+│       ├── __main__.py          # python -m my_cli entry
+│       ├── cli.py               # Typer app, command groups
+│       ├── commands/
+│       │   ├── __init__.py
+│       │   ├── init.py          # my-cli init
+│       │   └── run.py           # my-cli run
+│       ├── config.py            # Config file loading (TOML/YAML)
+│       └── utils.py
+├── tests/
+│   ├── conftest.py
+│   └── test_commands.py
+├── pyproject.toml               # [project.scripts] entry point
+├── .gitignore
+└── README.md
+```
+
+### Directory Structure (Go / Cobra)
+
+```
+my-cli/
+├── cmd/
+│   ├── root.go                  # Root command, global flags
+│   ├── init.go                  # my-cli init
+│   └── run.go                   # my-cli run
+├── internal/
+│   ├── config/
+│   │   └── config.go            # Viper config loading
+│   └── runner/
+│       └── runner.go            # Core logic
+├── main.go                      # Entry point, calls cmd.Execute()
+├── go.mod
+├── go.sum
+├── Makefile
+└── .gitignore
+```
+
+## Library Project Template
+
+### Directory Structure (npm Package)
+
+```
+my-lib/
+├── src/
+│   ├── index.ts                 # Public API exports
+│   ├── core.ts                  # Core implementation
+│   └── types.ts                 # Public type definitions
+├── tests/
+│   └── core.test.ts
+├── package.json                 # "type": "module", exports map
+├── tsconfig.json                # declaration: true, declarationMap: true
+├── tsup.config.ts               # Build config: cjs + esm
+├── vitest.config.ts
+├── .npmignore
+├── .gitignore
+├── CHANGELOG.md
+└── LICENSE
+```
+
+### Directory Structure (PyPI Package)
+
+```
+my-lib/
+├── src/
+│   └── my_lib/
+│       ├── __init__.py          # Public API, __version__
+│       ├── core.py
+│       └── py.typed             # PEP 561 marker
+├── tests/
+│   ├── conftest.py
+│   └── test_core.py
+├── pyproject.toml               # Build system, metadata, tool config
+├── .gitignore
+├── CHANGELOG.md
+└── LICENSE
+```
+
+## Monorepo Template
+
+### Turborepo + pnpm Workspaces
+
+```
+my-monorepo/
+├── apps/
+│   ├── web/                     # Next.js frontend
+│   │   ├── src/
+│   │   ├── package.json         # depends on @repo/shared
+│   │   └── tsconfig.json        # extends ../../tsconfig.base.json
+│   └── api/                     # Fastify backend
+│       ├── src/
+│       ├── package.json
+│       └── tsconfig.json
+├── packages/
+│   ├── shared/                  # Shared types, utils, validators
+│   │   ├── src/
+│   │   ├── package.json         # "name": "@repo/shared"
+│   │   └── tsconfig.json
+│   ├── ui/                      # Shared React components
+│   │   ├── src/
+│   │   └── package.json         # "name": "@repo/ui"
+│   └── config/                  # Shared configs
+│       ├── eslint/
+│       ├── typescript/
+│       └── package.json
+├── turbo.json                   # Pipeline: build, test, lint
+├── pnpm-workspace.yaml          # packages: ["apps/*", "packages/*"]
+├── package.json                 # Root devDeps: turbo
+├── tsconfig.base.json           # Shared TypeScript config
+├── .gitignore
+└── .npmrc
+```
+
+### Cargo Workspaces (Rust)
+
+```
+my-workspace/
+├── crates/
+│   ├── my-core/                 # Core library
+│   │   ├── src/lib.rs
+│   │   └── Cargo.toml
+│   ├── my-cli/                  # CLI binary
+│   │   ├── src/main.rs
+│   │   └── Cargo.toml           # depends on my-core
+│   └── my-server/               # API binary
+│       ├── src/main.rs
+│       └── Cargo.toml
+├── Cargo.toml                   # [workspace] members = ["crates/*"]
+├── Cargo.lock
+├── .gitignore
+└── rust-toolchain.toml
+```
+
+## Common Additions Checklist
+
+```
+Project setup complete? Add these:
+│
+├─ Version Control
+│  ├─ [ ] .gitignore (language-specific)
+│  ├─ [ ] .gitattributes (line endings, binary files)
+│  └─ [ ] Branch protection rules
+│
+├─ CI/CD
+│  ├─ [ ] GitHub Actions workflow (test on PR, deploy on merge)
+│  ├─ [ ] Matrix testing (OS, runtime versions)
+│  └─ [ ] Release automation
+│
+├─ Docker
+│  ├─ [ ] Multi-stage Dockerfile
+│  ├─ [ ] docker-compose.yml (app + database + cache)
+│  ├─ [ ] .dockerignore
+│  └─ [ ] Health check endpoint
+│
+├─ Code Quality
+│  ├─ [ ] Linter (ESLint, Ruff, golangci-lint, Clippy)
+│  ├─ [ ] Formatter (Prettier, Black/Ruff, gofmt, rustfmt)
+│  ├─ [ ] Pre-commit hooks (Husky, pre-commit)
+│  └─ [ ] Type checking (TypeScript strict, mypy, go vet)
+│
+├─ Testing
+│  ├─ [ ] Test framework configured (Vitest, pytest, go test)
+│  ├─ [ ] Coverage reporting
+│  ├─ [ ] Test database setup
+│  └─ [ ] CI test pipeline
+│
+├─ Editor
+│  ├─ [ ] .editorconfig
+│  ├─ [ ] .vscode/settings.json
+│  └─ [ ] .vscode/extensions.json
+│
+└─ Documentation
+   ├─ [ ] README.md (project description, setup, usage)
+   ├─ [ ] CONTRIBUTING.md
+   └─ [ ] API documentation (OpenAPI, godoc, rustdoc)
+```
+
+## Configuration File Templates
+
+### .editorconfig (Universal)
+
+```ini
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{py,rs}]
+indent_size = 4
+
+[*.go]
+indent_style = tab
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+```
+
+### pyproject.toml (Python)
+
+```toml
+[project]
+name = "my-project"
+version = "0.1.0"
+requires-python = ">=3.12"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+strict = true
+```
+
+### tsconfig.json (TypeScript - Strict)
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## Common Gotchas
+
+| Gotcha | Why It Happens | Prevention |
+|--------|---------------|------------|
+| Wrong .gitignore for language | Used generic template, missing language-specific entries | Use `gitignore.io` or GitHub's templates for your stack |
+| Forgot .env.example | Team members don't know which env vars are needed | Create .env.example with every var (empty values) at project start |
+| No lockfile committed | Inconsistent dependency versions across environments | Commit package-lock.json, uv.lock, go.sum, Cargo.lock |
+| Hardcoded port/host in code | Works locally, breaks in Docker/cloud | Always read from env var with sensible default |
+| Tests coupled to real database | Tests fail without running DB, CI setup is complex | Use test containers or in-memory SQLite for unit tests |
+| Missing health check endpoint | Deployment orchestrator cannot verify readiness | Add /health endpoint that checks DB connectivity |
+| No multi-stage Docker build | Image is 2GB instead of 200MB | Use builder stage for deps/compile, slim runtime stage |
+| Mixing tabs and spaces | .editorconfig missing, editor defaults vary | Add .editorconfig to every project root |
+| No .dockerignore | Docker context sends node_modules/venv, build takes minutes | Mirror .gitignore entries plus .git directory |
+| Monorepo without workspace protocol | Packages resolve from registry instead of local | Use `workspace:*` (pnpm) or path deps (Cargo, Go) |
+| TypeScript paths not in tsconfig | Module aliases work in dev but fail at build time | Configure paths in tsconfig AND build tool (tsup, vite) |
+
+## Reference Files
+
+| File | Contents | Lines |
+|------|----------|-------|
+| `references/api-templates.md` | Complete API scaffolds: FastAPI, Express/Fastify, Gin, Axum with full file content | ~700 |
+| `references/frontend-templates.md` | Web app scaffolds: Next.js, Nuxt 3, Astro, SvelteKit, Vite+React with config | ~650 |
+| `references/tooling-templates.md` | CI/CD, Docker, linting, testing, pre-commit, editor config, git templates | ~550 |
+
+## See Also
+
+| Skill | When to Combine |
+|-------|----------------|
+| `docker-ops` | Container configuration, multi-stage builds, compose orchestration |
+| `ci-cd-ops` | GitHub Actions workflows, deployment pipelines, release automation |
+| `testing-ops` | Test framework setup, coverage configuration, CI test integration |
+| `python-env` | Python virtual environments, dependency management with uv |
+| `typescript-ops` | TypeScript configuration, strict mode, module resolution |

skills/tool-discovery/SKILL.md

@@ -54,6 +54,11 @@ Is this a reference/lookup task?
 | **auth-ops** | jwt, oauth2, session, rbac, passkey, mfa, login |
 | **monitoring-ops** | prometheus, grafana, opentelemetry, SLO, alerting |
 | **debug-ops** | debug, crash, memory leak, race condition, bisect |
+| **perf-ops** | performance, profiling, flamegraph, bundle size, load test, benchmark |
+| **migrate-ops** | migrate, upgrade, breaking changes, codemod, version upgrade |
+| **refactor-ops** | refactor, extract, code smell, dead code, rename, restructure |
+| **scaffold** | scaffold, boilerplate, project template, init project, new project |
+| **log-ops** | JSONL, log analysis, parse logs, lnav, log search, timeline |
 
 ## Quick Agent Reference
 

skills/tool-discovery/references/skills-catalog.md

@@ -554,6 +554,89 @@ Project and development workflow automation.
 - structural-search: Security scans
 - doc-scanner: Documentation consolidation
 - project-planner: Session planning
+- migrate-ops: Framework version upgrades
+- refactor-ops: Large-scale refactoring
+
+---
+
+### migrate-ops
+
+**Triggers:** migrate, upgrade, migration, version upgrade, breaking changes, codemod, rector, jscodeshift, framework upgrade, dependency audit
+
+**Use For:**
+- Framework version upgrades (React 18→19, Vue 2→3, Next.js Pages→App Router, Laravel 10→11)
+- Language upgrades (Python 3.9→3.13, Node 18→22, TypeScript 4→5, Go, Rust editions)
+- Dependency audit and upgrade workflows (npm audit, pip-audit, cargo audit, govulncheck)
+- Breaking change detection and codemod application
+- Rollback strategies and pre-migration checklists
+
+**References:** framework-upgrades.md, language-upgrades.md, dependency-management.md
+
+---
+
+### refactor-ops
+
+**Triggers:** refactor, extract function, extract component, code smell, dead code, rename, restructure, technical debt, cyclomatic complexity
+
+**Use For:**
+- Extract patterns (function, component, hook, module, class, configuration)
+- Code smell detection (long functions, god objects, feature envy, duplicate code)
+- Dead code detection and removal workflows
+- Test-driven refactoring methodology (characterization tests, strangler fig)
+- Safe rename and move operations across codebase
+
+**References:** extract-patterns.md, code-smells.md, safe-methodology.md
+
+---
+
+### scaffold
+
+**Triggers:** scaffold, boilerplate, project template, init project, create project, starter, new project, setup project
+
+**Use For:**
+- API project scaffolding (FastAPI, Express, Gin, Axum)
+- Web app scaffolding (Next.js, Nuxt, Astro, SvelteKit)
+- CLI tool scaffolding (Typer, Commander, Cobra, Clap)
+- Library/package scaffolding (npm, PyPI, crate, Go module)
+- Monorepo scaffolding (Turborepo, Nx, workspaces)
+- Common additions (CI/CD, Docker, linting, pre-commit)
+
+**References:** api-templates.md, frontend-templates.md, tooling-templates.md
+
+---
+
+### perf-ops
+
+**Triggers:** performance, profiling, flamegraph, memory leak, bundle size, load test, benchmark, slow, latency, optimization, pprof, py-spy, clinic.js
+
+**Use For:**
+- CPU profiling (flamegraphs, pprof, py-spy, clinic.js, samply)
+- Memory profiling (heaptrack, memray, Chrome DevTools, Valgrind)
+- Bundle analysis (webpack-bundle-analyzer, source-map-explorer)
+- Load testing (k6, artillery, vegeta, locust)
+- Benchmarking (hyperfine, criterion, pytest-benchmark, vitest bench)
+- Optimization patterns (caching, lazy loading, connection pooling)
+
+**References:** cpu-memory-profiling.md, load-testing.md, optimization-patterns.md
+
+---
+
+### log-ops
+
+**Triggers:** log analysis, JSONL, log file, parse logs, search logs, lnav, jq logs, structured logs, log aggregation, timeline reconstruction, cross-log correlation
+
+**Use For:**
+- JSONL streaming extraction and aggregation with jq
+- Two-stage rg+jq pipelines for large log files
+- Timeline reconstruction from log timestamps
+- Cross-log correlation across multiple files
+- Agent conversation log analysis (tool calls, errors, phases)
+- Cross-directory log searching (fd + rg + jq composition)
+- Interactive log exploration with lnav
+
+**References:** jsonl-patterns.md, analysis-workflows.md, tool-setup.md
+
+---
 
 ## When to Use Skills vs Agents