cokit-cli 1.2.6 → 1.3.0

package/skills/debug/SKILL.md

@@ -1,170 +1,112 @@
 ---
 name: debug
-description: Debug systematically with root cause analysis before fixes. Covers bugs, test failures, log analysis, CI/CD failures, database diagnostics, system investigation, performance issues, call stack tracing, multi-layer validation.
+description: "Debug systematically with root cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, call stack tracing, multi-layer validation, log analysis, CI/CD failures, database diagnostics, system investigation."
+languages: all
+argument-hint: "[error or issue description]"
 ---
 
 # Debugging & System Investigation
 
-Comprehensive debugging framework combining systematic investigation, root cause tracing, defense-in-depth validation, verification protocols, and system-level diagnostics.
+Comprehensive framework combining systematic debugging, root cause tracing, defense-in-depth validation, verification protocols, and system-level investigation (logs, CI/CD, databases, performance).
 
 ## Core Principle
 
 **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
 
-Random fixes waste time and create new bugs. Find the root cause, fix at source, validate at every layer, verify before claiming success.
+Random fixes waste time and create new bugs. Find root cause, fix at source, validate at every layer, verify before claiming success.
 
 ## When to Use
 
-**Code-level:** Test failures, bugs, unexpected behavior, build failures, integration problems, before claiming work complete
-
-**System-level:** CI/CD pipeline failures, log analysis, database diagnostics, performance bottlenecks, infrastructure issues
-
-**Especially when:** Under time pressure, "quick fix" seems obvious, tried multiple fixes, don't fully understand issue, about to claim success
+**Code-level:** Test failures, bugs, unexpected behavior, build failures, integration problems
+**System-level:** Server errors, CI/CD pipeline failures, performance degradation, database issues, log analysis
+**Always:** Before claiming work complete
 
 ## Techniques
 
 ### 1. Systematic Debugging (`references/systematic-debugging.md`)
 
-Four-phase framework:
-- Phase 1: Root Cause Investigation (read errors, reproduce, check changes, gather evidence)
-- Phase 2: Pattern Analysis (find working examples, compare, identify differences)
-- Phase 3: Hypothesis and Testing (form theory, test minimally, verify)
-- Phase 4: Implementation (create test, fix once, verify)
-
-Complete each phase before proceeding. No fixes without Phase 1.
+Four-phase framework: Root Cause Investigation → Pattern Analysis → Hypothesis Testing → Implementation. Complete each phase before proceeding. No fixes without Phase 1.
 
 **Load when:** Any bug/issue requiring investigation and fix
 
 ### 2. Root Cause Tracing (`references/root-cause-tracing.md`)
 
-Trace bugs backward through call stack to find original trigger. Fix at source, not at symptom.
-
-**Includes:** `scripts/find-polluter.sh` for bisecting test pollution
+Trace bugs backward through call stack to find original trigger. Fix at source, not symptom. Includes `scripts/find-polluter.sh` for bisecting test pollution.
 
 **Load when:** Error deep in call stack, unclear where invalid data originated
 
 ### 3. Defense-in-Depth (`references/defense-in-depth.md`)
 
-Validate at every layer data passes through. Four layers: Entry validation → Business logic → Environment guards → Debug instrumentation
+Validate at every layer: Entry validation → Business logic → Environment guards → Debug instrumentation
 
-**Load when:** After finding root cause, need to add comprehensive validation
+**Load when:** After finding root cause, need comprehensive validation
 
 ### 4. Verification (`references/verification.md`)
 
-Run verification commands and confirm output before claiming success.
-
-**Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+**Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE. Run command. Read output. Then claim result.
 
 **Load when:** About to claim work complete, fixed, or passing
 
-### 5. Investigation Methodology
+### 5. Investigation Methodology (`references/investigation-methodology.md`)
 
-For system-level issues (CI/CD, infrastructure, data pipeline):
+Five-step structured investigation for system-level issues: Initial Assessment → Data Collection → Analysis → Root Cause ID → Solution Development
 
-1. **Scope** - Define what is broken and what is working
-2. **Gather** - Collect logs, metrics, error outputs before touching anything
-3. **Isolate** - Narrow to smallest reproducible case
-4. **Hypothesize** - Form one theory, test it, reject or confirm
-5. **Fix & Validate** - Fix at root, verify at every affected layer
+**Load when:** Server incidents, system behavior analysis, multi-component failures
 
-**Load when:** Issue is not code-local — spans services, environments, or pipelines
+### 6. Log & CI/CD Analysis (`references/log-and-ci-analysis.md`)
 
-### 6. Log & CI/CD Analysis
+Collect and analyze logs from servers, CI/CD pipelines (GitHub Actions), application layers. Tools: `gh` CLI, structured log queries, correlation across sources.
 
-Use `gh` CLI and structured queries to diagnose pipeline failures:
+**Load when:** CI/CD pipeline failures, server errors, deployment issues
 
-```bash
-# View failed CI run logs
-gh run view <run-id> --log-failed
+### 7. Performance Diagnostics (`references/performance-diagnostics.md`)
 
-# List recent runs for a workflow
-gh run list --workflow=<name> --limit 10
+Identify bottlenecks, analyze query performance, develop optimization strategies. Covers database queries, API response times, resource utilization.
 
-# Watch a running workflow
-gh run watch <run-id>
-```
-
-For structured logs: filter by severity, timestamp range, and correlation ID before reading raw output.
-
-**Load when:** CI/CD failure, deployment issue, or log-driven investigation
+**Load when:** Performance degradation, slow queries, high latency, resource exhaustion
 
-### 7. Performance Diagnostics
+### 8. Reporting Standards (`references/reporting-standards.md`)
 
-Identify bottlenecks before optimizing:
-- Profile first — measure before guessing
-- Check slow queries with `EXPLAIN ANALYZE` (PostgreSQL) or equivalent
-- Identify N+1 query patterns in ORM usage
-- Check memory allocation patterns for leaks
-- Use `psql` for live database diagnostics
+Structured diagnostic reports: Executive Summary → Technical Analysis → Recommendations → Evidence
 
-**Load when:** Slowness reported, timeout errors, resource exhaustion
+**Load when:** Need to produce investigation report or diagnostic summary
 
-### 8. Reporting Standards
+### 9. Task Management (`references/task-management-debugging.md`)
 
-For multi-component investigations, write a structured diagnostic report:
+Track investigation pipelines via Native Tasks (TaskCreate, TaskUpdate, TaskList). Hydration pattern for multi-step investigations with dependency chains and parallel evidence collection. **Fallback:** Task tools are CLI-only — if unavailable (VSCode extension), use `TodoWrite` for tracking. Debug workflow remains fully functional.
 
-```
-## Diagnostic Report
-- **Issue:** [one-line description]
-- **Root Cause:** [where and why it fails]
-- **Evidence:** [logs, output, reproduction steps]
-- **Fix Applied:** [what was changed]
-- **Verification:** [command run + result]
-- **Remaining Risk:** [any open questions]
-```
+**Load when:** Multi-component investigation (3+ steps), parallel log collection, coordinating debugger subagents
 
-Save to `plans/reports/debugger-{date}-{slug}.md`.
+### 10. Frontend Verification (`references/frontend-verification.md`)
 
-**Load when:** Investigation spans multiple components or will be shared with others
+Visual verification of frontend implementations via Chrome MCP (if available) or `chrome-devtools` (if available) skill fallback. Detect if frontend-related → check Chrome MCP availability → screenshot + console error check → report. Skip if not frontend.
 
-### 9. Task Management
+**Load when:** Implementation touches frontend files (tsx/jsx/vue/svelte/html/css), UI bugs, visual regressions
 
-For multi-component investigations, track progress with a checklist rather than holding state mentally:
+## Quick Reference
 
 ```
-- [ ] Reproduce the issue
-- [ ] Identify root cause
-- [ ] Fix applied
-- [ ] Tests passing
-- [ ] Verification complete
-```
-
-Add this checklist to the active plan or investigation report. Check items off as each step completes.
-
-**Load when:** Investigation touches 3+ components or files
-
-### 10. Frontend Verification
+Code bug       → systematic-debugging.md (Phase 1-4)
+  Deep in stack  → root-cause-tracing.md (trace backward)
+  Found cause    → defense-in-depth.md (add layers)
+  Claiming done  → verification.md (verify first)
 
-For visual bugs or UI regressions, use browser developer tools (or the `agent-browser` skill) to inspect rendering, network, and console errors directly in the browser.
+System issue   → investigation-methodology.md (5 steps)
+  CI/CD failure  → log-and-ci-analysis.md
+  Slow system    → performance-diagnostics.md
+  Need report    → reporting-standards.md
 
-Use `/ck-scout ext` to search for frontend-specific patterns before diving into devtools.
-
-**Load when:** Visual regression, layout bug, client-side network error, or UI behavior that differs from expected
-
-## Quick Reference
-
-```
-Code bug → systematic-debugging.md (Phase 1-4)
-  Error deep in stack? → root-cause-tracing.md (trace backward)
-  Found root cause? → defense-in-depth.md (add layers)
-  About to claim success? → verification.md (verify first)
-
-System issue → Investigation Methodology (5 steps)
-  CI/CD failure? → Log & CI/CD Analysis (gh CLI)
-  Slow/timeout? → Performance Diagnostics
-  Multi-component? → Task Management checklist + Reporting Standards
-  Visual/UI bug? → Frontend Verification (agent-browser / browser devtools)
+Frontend fix   → frontend-verification.md (Chrome/devtools)
 ```
 
 ## Tools Integration
 
-| Tool | Use Case |
-|------|----------|
-| `execute` | Run test commands, build scripts, verification steps |
-| `gh` CLI | CI/CD log analysis, PR checks, workflow runs |
-| `psql` | Live database diagnostics and slow query analysis |
-| `agent-browser` skill | Frontend visual verification and network inspection |
-| `/ck-scout` | Search codebase for related patterns before investigating |
+- **Database:** `psql` for PostgreSQL queries and diagnostics
+- **CI/CD:** `gh` CLI for GitHub Actions logs and pipeline debugging
+- **Codebase:** `docs-seeker` skill for package/plugin docs; `repomix` skill for codebase summary
+- **Scouting:** `/ck-scout` or `/ck-scout ext` for finding relevant files
+- **Frontend:** Chrome browser or `chrome-devtools` (if available) skill for visual verification (screenshots, console, network)
+- **Skills:** Activate `problem-solving` skill when stuck on complex issues
 
 ## Red Flags
 

package/skills/debug/references/frontend-verification.md

@@ -0,0 +1,103 @@
+# Frontend Verification
+
+Visual verification of frontend implementations using Chrome MCP (if available) or `chrome-devtools` (if available) skill fallback.
+
+## Applicability Check
+
+**Skip entirely if task is NOT frontend-related.** Frontend indicators:
+- Files modified: `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.html`, `*.css`, `*.scss`
+- Changes to: components, layouts, pages, styles, DOM structure, UI behavior
+- Keywords: render, display, layout, responsive, animation, visual, UI, UX
+
+If none match, skip this technique.
+
+## Step 1: Detect Chrome MCP Availability
+
+Check if Chrome MCP server is available via `mcp-management` skill or `ListMcpResourcesTool`:
+
+```
+Use ListMcpResourcesTool to check for Chrome MCP tools.
+Look for tools prefixed with "chrome__" (e.g., chrome__navigate, chrome__screenshot).
+```
+
+**Available** → Proceed to Step 2A (Chrome MCP)
+**Not available** → Proceed to Step 2B (chrome-devtools fallback)
+
+## Step 2A: Chrome MCP Available — Direct Verification
+
+Use Chrome MCP tools to verify the implementation in the user's actual browser. Ensure dev server is running first.
+
+### Navigate & Screenshot
+
+```
+1. chrome__navigate → http://localhost:3000 (or project dev URL)
+2. chrome__screenshot → capture current page state
+3. Read the screenshot with Read tool to visually inspect
+```
+
+### Visual Inspection Checklist
+
+After capturing screenshot, verify:
+1. **Layout** — Elements positioned correctly, no overflow/overlap
+2. **Content** — Text, images, data rendered as expected
+3. **Responsiveness** — Resize viewport if MCP supports it
+4. **Interactions** — Use chrome__click / chrome__type to test interactive elements
+5. **Console errors** — Use chrome__evaluate to check `console.error` output
+
+### Console Error Check
+
+```
+chrome__evaluate → "JSON.stringify(window.__consoleErrors || [])"
+```
+
+Or navigate and observe any error output from Chrome MCP tool responses.
+
+### Get Page Content
+
+```
+chrome__get_content → extract DOM/text to verify rendered output matches expectations
+```
+
+## Step 2B: Chrome MCP NOT Available — Fallback to chrome-devtools Skill
+
+When Chrome MCP is not configured, use `chrome-devtools` (if available) skill (Puppeteer with bundled Chromium):
+
+```bash
+SKILL_DIR="chrome-devtools scripts (if available)"
+
+# Install deps if first time
+npm install --prefix "$SKILL_DIR" 2>/dev/null
+
+# Screenshot + console error check
+node "$SKILL_DIR/screenshot.js" --url http://localhost:3000 --output ./verification-screenshot.png
+node "$SKILL_DIR/console.js" --url http://localhost:3000 --types error,pageerror --duration 5000
+```
+
+If `chrome-devtools` (if available) skill is also unavailable, skip visual verification and note in report:
+> "Visual verification skipped — no Chrome MCP or chrome-devtools available."
+
+## Step 3: Analyze Results
+
+After capture:
+1. **Read screenshot** — Use Read tool on the PNG to visually inspect
+2. **Check console output** — Zero errors = pass; errors = investigate before claiming done
+3. **Compare with expected** — Match against design specs or user description
+4. **Document findings** — Include screenshot path and any issues found in verification report
+
+## Integration with Verification Protocol
+
+This technique extends `verification.md`. After standard verification (tests pass, build succeeds), add frontend verification as final gate:
+
+```
+Standard verification → Tests pass → Build succeeds → Frontend visual verification → Claim complete
+```
+
+Report format:
+```
+## Frontend Verification
+- Method: [Chrome MCP | chrome-devtools | skipped]
+- Screenshot: ./verification-screenshot.png
+- Console errors: [none | list]
+- Visual check: [pass | issues found]
+- Responsive: [checked at X viewports | skipped]
+```

package/skills/debug/references/investigation-methodology.md

@@ -0,0 +1,101 @@
+# Investigation Methodology
+
+Five-step structured investigation for system-level issues, incidents, and multi-component failures.
+
+## When to Use
+
+- Server returning 500 errors or unexpected responses
+- System behavior changed without obvious code changes
+- Multi-component failures spanning services/databases/infrastructure
+- Need to understand "what happened" before fixing
+
+## Step 1: Initial Assessment
+
+**Gather scope and impact before diving in.**
+
+1. **Collect symptoms** - Error messages, affected endpoints, user reports
+2. **Identify affected components** - Which services, databases, queues involved?
+3. **Determine timeframe** - When did issue start? Correlate with deployments/changes
+4. **Assess severity** - Users affected? Data at risk? Revenue impact?
+5. **Check recent changes** - Git log, deployment history, config changes, dependency updates
+
+```bash
+# Recent deployments
+gh run list --limit 10
+# Recent commits
+git log --oneline -20 --since="2 days ago"
+# Config changes
+git diff HEAD~5 -- '*.env*' '*.config*' '*.yml' '*.yaml' '*.json'
+```
+
+## Step 2: Data Collection
+
+**Gather evidence systematically before analysis.**
+
+1. **Server/application logs** - Filter by timeframe and affected components
+2. **CI/CD pipeline logs** - Use `gh run view <run-id> --log-failed` for GitHub Actions
+3. **Database state** - Query relevant tables, check recent migrations
+4. **System metrics** - CPU, memory, disk, network utilization
+5. **External dependencies** - Third-party API status, DNS, CDN
+
+```bash
+# GitHub Actions: list recent workflow runs
+gh run list --workflow=<workflow> --limit 5
+# View failed run logs
+gh run view <run-id> --log-failed
+# Download full logs
+gh run view <run-id> --log > /tmp/ci-logs.txt
+```
+
+**For codebase understanding:**
+- Read `docs/codebase-summary.md` if exists and up-to-date (<2 days old)
+- Otherwise use `repomix` to generate fresh codebase summary
+- Use `/ck-scout` or `/ck-scout ext` to find relevant files
+- Use `docs-seeker` skill for package/plugin documentation
+
+## Step 3: Analysis Process
+
+**Correlate evidence across sources.**
+
+1. **Timeline reconstruction** - Order events chronologically across all log sources
+2. **Pattern identification** - Recurring errors, timing patterns, affected user segments
+3. **Execution path tracing** - Follow request flow through system components
+4. **Database analysis** - Query performance, table relationships, data integrity
+5. **Dependency mapping** - Which components depend on the failing one?
+
+**Key questions:**
+- Does issue correlate with specific deployments or time windows?
+- Is it intermittent or consistent?
+- Does it affect all users or a subset?
+- Are there related errors in upstream/downstream services?
+
+## Step 4: Root Cause Identification
+
+**Systematic elimination with evidence.**
+
+1. **List hypotheses** ranked by evidence strength
+2. **Test each** - Design smallest experiment to confirm/eliminate
+3. **Validate with evidence** - Logs, metrics, reproduction steps
+4. **Consider environmental factors** - Race conditions, resource limits, config drift
+5. **Document the chain** - Full event sequence from trigger to symptom
+
+**Avoid:** Fixing first hypothesis without testing alternatives. Multiple plausible causes require elimination.
+
+## Step 5: Solution Development
+
+**Design targeted, evidence-backed fixes.**
+
+1. **Immediate fix** - Minimum change to restore service (hotfix, rollback, config change)
+2. **Root cause fix** - Address underlying issue permanently
+3. **Preventive measures** - Monitoring, alerting, validation to catch recurrence early
+4. **Verification plan** - How to confirm fix works in production
+
+**Prioritize:** Impact × urgency. Restore service first, then fix root cause, then prevent recurrence.
+
+## Integration with Code-Level Debugging
+
+When investigation narrows to specific code:
+- Switch to `systematic-debugging.md` for the code-level fix
+- Use `root-cause-tracing.md` if error is deep in call stack
+- Apply `defense-in-depth.md` after fixing
+- Always finish with `verification.md`

package/skills/debug/references/log-and-ci-analysis.md

@@ -0,0 +1,97 @@
+# Log & CI/CD Analysis
+
+Collect and analyze logs from servers, CI/CD pipelines, and application layers to diagnose failures.
+
+## GitHub Actions Analysis
+
+### List and Inspect Runs
+
+```bash
+# List recent runs (all workflows)
+gh run list --limit 10
+
+# List runs for specific workflow
+gh run list --workflow=ci.yml --limit 5
+
+# View specific run details
+gh run view <run-id>
+
+# View failed job logs only
+gh run view <run-id> --log-failed
+
+# Download complete logs
+gh run view <run-id> --log > /tmp/ci-full.txt
+
+# Re-run failed jobs
+gh run rerun <run-id> --failed
+```
+
+### Common CI/CD Failure Patterns
+
+| Pattern | Likely Cause | Investigation |
+|---------|-------------|---------------|
+| Passes locally, fails CI | Environment diff | Check Node/Python version, OS, env vars |
+| Intermittent failures | Race conditions, flaky tests | Run 3x, check timing, shared state |
+| Timeout failures | Resource limits, infinite loops | Check resource usage, add timeouts |
+| Permission errors | Token/secret misconfiguration | Verify `GITHUB_TOKEN`, secret names |
+| Dependency install fails | Registry issues, version conflicts | Check lockfile, registry status |
+| Build succeeds, tests fail | Test environment setup | Check test config, database setup, fixtures |
+
+### Analyzing Failed Steps
+
+1. **Identify which step failed** - `gh run view <id>` shows step-by-step status
+2. **Get the logs** - `gh run view <id> --log-failed` for focused output
+3. **Search for error patterns** - Look for `Error:`, `FAIL`, `exit code`, stack traces
+4. **Check annotations** - `gh api repos/{owner}/{repo}/check-runs/{id}/annotations`
+
+## Server Log Analysis
+
+### Log Collection Strategy
+
+1. **Identify log locations** - Application logs, system logs, web server logs
+2. **Filter by timeframe** - Narrow to incident window
+3. **Correlate request IDs** - Trace single request across services
+4. **Look for patterns** - Repeated errors, error rate changes, unusual payloads
+
+### Structured Log Queries
+
+```bash
+# Search application logs for errors (use Grep tool when possible)
+# Pattern: timestamp, level, message
+# Filter by time range and severity
+
+# PostgreSQL slow query log
+psql -c "SELECT query, calls, mean_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"
+
+# Check database connections
+psql -c "SELECT count(*), state FROM pg_stat_activity GROUP BY state;"
+```
+
+### Cross-Source Correlation
+
+1. **Align timestamps** across all log sources (timezone awareness)
+2. **Build timeline** - First error → propagation → user impact
+3. **Identify trigger** - What changed immediately before first error?
+4. **Map blast radius** - Which services/endpoints affected?
+
+## Application Log Analysis
+
+### Error Pattern Recognition
+
+- **Sudden spike** → Deployment, config change, external dependency failure
+- **Gradual increase** → Resource leak, data growth, degradation
+- **Periodic failures** → Cron jobs, scheduled tasks, resource contention
+- **Single endpoint** → Code bug, data issue, specific dependency
+- **All endpoints** → Infrastructure, database, network issue
+
+### Key Log Fields
+
+Prioritize: timestamp, level, error message, stack trace, request ID, user ID, endpoint, response code, duration
+
+### Evidence Preservation
+
+Always capture relevant log excerpts for the diagnostic report. Include:
+- Exact error messages and stack traces
+- Timestamps and request IDs
+- Before/after comparison (normal vs error state)
+- Counts and frequencies

package/skills/debug/references/performance-diagnostics.md

@@ -0,0 +1,113 @@
+# Performance Diagnostics
+
+Identify bottlenecks, analyze query performance, and develop optimization strategies.
+
+## When to Use
+
+- Response times increased significantly
+- Application feels slow or unresponsive
+- Database queries taking too long
+- High CPU/memory/disk usage
+- Resource exhaustion or OOM errors
+
+## Diagnostic Process
+
+### 1. Quantify the Problem
+
+**Measure before optimizing.** Establish baseline and current state.
+
+- What is the expected response time vs actual?
+- When did degradation start? (correlate with changes)
+- Which endpoints/operations are affected?
+- Is it consistent or intermittent?
+
+### 2. Identify the Bottleneck Layer
+
+```
+Request → Network → Web Server → Application → Database → Filesystem
+                                      ↓
+                              External APIs / Services
+```
+
+**Elimination approach:** Measure time at each layer to find where delay occurs.
+
+| Layer | Check | Tool |
+|-------|-------|------|
+| Network | Latency, DNS, TLS | `curl -w` timing, network logs |
+| Web server | Request queue, connections | Server metrics, access logs |
+| Application | CPU profiling, memory | Profiler, APM, `process.memoryUsage()` |
+| Database | Query time, connections | `EXPLAIN ANALYZE`, `pg_stat_statements` |
+| Filesystem | I/O wait, disk usage | `iostat`, `df -h` |
+| External APIs | Response time, timeouts | Request logging with durations |
+
+### 3. Database Performance
+
+#### PostgreSQL Diagnostics
+
+```sql
+-- Slow queries (requires pg_stat_statements extension)
+SELECT query, calls, mean_exec_time, total_exec_time
+FROM pg_stat_statements
+ORDER BY mean_exec_time DESC LIMIT 20;
+
+-- Active queries right now
+SELECT pid, now() - pg_stat_activity.query_start AS duration, query, state
+FROM pg_stat_activity
+WHERE state != 'idle'
+ORDER BY duration DESC;
+
+-- Table sizes and bloat
+SELECT relname, pg_size_pretty(pg_total_relation_size(relid))
+FROM pg_catalog.pg_statio_user_tables
+ORDER BY pg_total_relation_size(relid) DESC LIMIT 20;
+
+-- Missing indexes (sequential scans on large tables)
+SELECT relname, seq_scan, seq_tup_read, idx_scan
+FROM pg_stat_user_tables
+WHERE seq_scan > 100 AND seq_tup_read > 10000
+ORDER BY seq_tup_read DESC;
+
+-- Connection pool status
+SELECT count(*), state FROM pg_stat_activity GROUP BY state;
+```
+
+#### Query Optimization
+
+```sql
+-- Analyze specific query execution plan
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) <your-query>;
+```
+
+**Look for:** Sequential scans on large tables, nested loops with high row counts, sorts without indexes, excessive buffer hits.
+
+### 4. Application Performance
+
+**Common bottlenecks:**
+
+| Issue | Symptom | Fix |
+|-------|---------|-----|
+| N+1 queries | Many small DB calls per request | Eager loading, batch queries |
+| Memory leaks | Growing memory over time | Profile heap, check event listeners |
+| Blocking I/O | High response time, low CPU | Async operations, connection pooling |
+| CPU-bound | High CPU, proportional to load | Optimize algorithms, caching |
+| Connection exhaustion | Intermittent timeouts | Pool sizing, connection reuse |
+| Large payloads | Slow transfers, high memory | Pagination, compression, streaming |
+
+### 5. Optimization Strategy
+
+**Priority order:**
+1. **Quick wins** - Add missing index, fix N+1 query, enable caching
+2. **Configuration** - Pool sizes, timeouts, buffer sizes, worker counts
+3. **Code changes** - Algorithm optimization, data structure changes
+4. **Architecture** - Caching layer, read replicas, async processing, CDN
+
+**Always:** Measure after each change to verify improvement. One change at a time.
+
+## Reporting Performance Issues
+
+Include in diagnostic report:
+- **Baseline vs current** metrics (with numbers)
+- **Bottleneck identification** with evidence
+- **Root cause** explanation
+- **Recommended fixes** with expected impact
+- **Verification plan** to confirm improvement