aios-core 2.1.6 → 2.2.0

package/.aios-core/development/tasks/analyze-performance.md

@@ -1,637 +1,637 @@
-# Task: Analyze Performance
-
-**Purpose**: Query performance analysis and optimization (explain plans, hotpath detection, interactive optimization)
-
-**Elicit**: true
-
-**Consolidated From (Story 6.1.2.3):**
-- `db-explain.md` - Query execution plan analysis
-- `db-analyze-hotpaths.md` - Performance bottleneck detection
-- `query-optimization.md` - Interactive query optimization (if existed)
-
----
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: analyzePerformance()
-responsável: Dex (Builder)
-responsavel_type: Agente
-atomic_layer: Strategy
-
-**Entrada:**
-- campo: target
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Valid path or identifier
-
-- campo: options
-  tipo: object
-  origem: config
-  obrigatório: false
-  validação: Analysis configuration
-
-- campo: depth
-  tipo: number
-  origem: User Input
-  obrigatório: false
-  validação: Default: 1 (0-3)
-
-**Saída:**
-- campo: analysis_report
-  tipo: object
-  destino: File (.ai/*.json)
-  persistido: true
-
-- campo: findings
-  tipo: array
-  destino: Memory
-  persistido: false
-
-- campo: metrics
-  tipo: object
-  destino: Memory
-  persistido: false
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Target exists and is accessible; analysis tools available
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check target exists and is accessible; analysis tools available
-    error_message: "Pre-condition failed: Target exists and is accessible; analysis tools available"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Analysis complete; report generated; no critical issues
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify analysis complete; report generated; no critical issues
-    error_message: "Post-condition failed: Analysis complete; report generated; no critical issues"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Analysis accurate; all targets covered; report complete
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert analysis accurate; all targets covered; report complete
-    error_message: "Acceptance criterion not met: Analysis accurate; all targets covered; report complete"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** code-analyzer
-  - **Purpose:** Static code analysis and metrics
-  - **Source:** .aios-core/utils/code-analyzer.js
-
-- **Tool:** file-system
-  - **Purpose:** Recursive directory traversal
-  - **Source:** Node.js fs module
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** analyze-codebase.js
-  - **Purpose:** Codebase analysis and reporting
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/analyze-codebase.js
-
----
-
-## Error Handling
-
-**Strategy:** fallback
-
-**Common Errors:**
-
-1. **Error:** Target Not Accessible
-   - **Cause:** Path does not exist or permissions denied
-   - **Resolution:** Verify path and check permissions
-   - **Recovery:** Skip inaccessible paths, continue with accessible ones
-
-2. **Error:** Analysis Timeout
-   - **Cause:** Analysis exceeds time limit for large codebases
-   - **Resolution:** Reduce analysis depth or scope
-   - **Recovery:** Return partial results with timeout warning
-
-3. **Error:** Memory Limit Exceeded
-   - **Cause:** Large codebase exceeds memory allocation
-   - **Resolution:** Process in batches or increase memory limit
-   - **Recovery:** Graceful degradation to summary analysis
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 5-20 min (estimated)
-cost_estimated: $0.003-0.015
-token_usage: ~2,000-8,000 tokens
-```
-
-**Optimization Notes:**
-- Iterative analysis with depth limits; cache intermediate results; batch similar operations
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - analysis
-  - metrics
-updated_at: 2025-11-17
-```
-
----
-
-
-## Elicitation
-
-**Prompt user to select analysis type:**
-
-```
-Select performance analysis type:
-
-1. **query** - Analyze specific query execution plan
-2. **hotpaths** - Detect performance bottlenecks across system
-3. **interactive** - Interactive query optimization session
-
-Which type? [query/hotpaths/interactive]:
-```
-
-**Capture:** `{type}`
-
-**If type=query, also prompt:**
-```
-Enter SQL query to analyze (or file path):
-```
-
-**Capture:** `{query}`
-
----
-
-## Process
-
-### Type: Query Analysis (EXPLAIN)
-
-**When:** User selects `query`
-
-**Purpose:** Analyze execution plan for specific query
-
-#### Step 1: Validate Query
-
-```bash
-# Check if query is a file path
-if [[ -f "$QUERY" ]]; then
-  QUERY_SQL=$(cat "$QUERY")
-else
-  QUERY_SQL="$QUERY"
-fi
-
-# Validate SQL syntax (basic)
-echo "$QUERY_SQL" | grep -iE '^(SELECT|WITH|EXPLAIN)' || {
-  echo "❌ Error: Query must start with SELECT, WITH, or EXPLAIN"
-  exit 1
-}
-```
-
-#### Step 2: Run EXPLAIN ANALYZE
-
-```bash
-psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<SQL
-\echo '=== Query Performance Analysis ==='
-\echo ''
-\echo 'Query:'
-\echo '$QUERY_SQL'
-\echo ''
-\echo '=== Execution Plan (EXPLAIN ANALYZE) ==='
-
-EXPLAIN (ANALYZE, BUFFERS, VERBOSE, FORMAT TEXT)
-$QUERY_SQL;
-
-\echo ''
-\echo '=== JSON Format (for tools) ==='
-
-EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)
-$QUERY_SQL;
-
-SQL
-```
-
-#### Step 3: Analyze Results
-
-```bash
-psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<'SQL'
-\echo ''
-\echo '=== Performance Recommendations ==='
-
--- Check for sequential scans on large tables
-SELECT
-  schemaname,
-  tablename,
-  seq_scan,
-  seq_tup_read,
-  idx_scan,
-  CASE
-    WHEN seq_scan > idx_scan THEN '⚠️ Consider adding index'
-    WHEN seq_tup_read > 10000 THEN '⚠️ Large sequential scan detected'
-    ELSE '✓ Looks good'
-  END AS recommendation
-FROM pg_stat_user_tables
-WHERE schemaname = 'public'
-  AND (seq_scan > idx_scan OR seq_tup_read > 10000)
-ORDER BY seq_tup_read DESC
-LIMIT 10;
-
-SQL
-```
-
----
-
-### Type: Hotpaths Analysis
-
-**When:** User selects `hotpaths`
-
-**Purpose:** Detect performance bottlenecks across entire system
-
-```bash
-psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<'SQL'
-\echo '=== Performance Hotpaths Analysis ==='
-\echo ''
-
--- 1. Slowest Queries (requires pg_stat_statements extension)
-\echo '1. Top 10 Slowest Queries:'
-SELECT
-  LEFT(query, 80) AS query_preview,
-  calls,
-  ROUND(total_exec_time::numeric / 1000, 2) AS total_seconds,
-  ROUND(mean_exec_time::numeric, 2) AS avg_ms,
-  ROUND((100 * total_exec_time / SUM(total_exec_time) OVER ())::numeric, 2) AS percent_total
-FROM pg_stat_statements
-WHERE query NOT LIKE '%pg_stat_statements%'
-ORDER BY total_exec_time DESC
-LIMIT 10;
-
-\echo ''
-\echo '2. Most Frequent Queries:'
-SELECT
-  LEFT(query, 80) AS query_preview,
-  calls,
-  ROUND(mean_exec_time::numeric, 2) AS avg_ms,
-  ROUND(total_exec_time::numeric / 1000, 2) AS total_seconds
-FROM pg_stat_statements
-WHERE query NOT LIKE '%pg_stat_statements%'
-ORDER BY calls DESC
-LIMIT 10;
-
-\echo ''
-\echo '3. Tables with Most Sequential Scans:'
-SELECT
-  schemaname,
-  tablename,
-  seq_scan,
-  seq_tup_read,
-  idx_scan,
-  n_live_tup AS approx_rows,
-  ROUND((seq_tup_read::numeric / NULLIF(seq_scan, 0)), 0) AS avg_rows_per_scan
-FROM pg_stat_user_tables
-WHERE schemaname = 'public'
-  AND seq_scan > 0
-ORDER BY seq_tup_read DESC
-LIMIT 10;
-
-\echo ''
-\echo '4. Tables with Bloat (Dead Tuples):'
-SELECT
-  schemaname,
-  tablename,
-  n_live_tup,
-  n_dead_tup,
-  ROUND((n_dead_tup::numeric / NULLIF(n_live_tup, 0) * 100), 2) AS dead_tuple_percent,
-  last_vacuum,
-  last_autovacuum
-FROM pg_stat_user_tables
-WHERE schemaname = 'public'
-  AND n_dead_tup > 100
-ORDER BY n_dead_tup DESC
-LIMIT 10;
-
-\echo ''
-\echo '5. Missing Indexes (Foreign Keys without indexes):'
-SELECT
-  t.tablename,
-  c.column_name,
-  pg_size_pretty(pg_relation_size(t.tablename::regclass)) AS table_size,
-  'CREATE INDEX idx_' || t.tablename || '_' || c.column_name || ' ON ' || t.tablename || '(' || c.column_name || ');' AS suggested_index
-FROM pg_tables t
-JOIN information_schema.columns c ON c.table_name = t.tablename
-LEFT JOIN pg_indexes i ON i.tablename = t.tablename
-  AND i.indexdef LIKE '%' || c.column_name || '%'
-WHERE t.schemaname = 'public'
-  AND c.table_schema = 'public'
-  AND c.column_name LIKE '%_id'
-  AND c.column_name != 'id'
-  AND i.indexname IS NULL
-ORDER BY pg_relation_size(t.tablename::regclass) DESC
-LIMIT 10;
-
-\echo ''
-\echo '6. Index Usage Statistics:'
-SELECT
-  schemaname,
-  tablename,
-  indexname,
-  idx_scan,
-  idx_tup_read,
-  idx_tup_fetch,
-  pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
-  CASE
-    WHEN idx_scan = 0 THEN '❌ Unused - consider dropping'
-    WHEN idx_scan < 100 THEN '⚠️ Low usage'
-    ELSE '✓ Active'
-  END AS usage_status
-FROM pg_stat_user_indexes
-WHERE schemaname = 'public'
-ORDER BY idx_scan ASC, pg_relation_size(indexrelid) DESC
-LIMIT 15;
-
-\echo ''
-\echo '7. Cache Hit Ratio (should be > 99%):'
-SELECT
-  'Index Hit Rate' AS metric,
-  ROUND((SUM(idx_blks_hit) / NULLIF(SUM(idx_blks_hit + idx_blks_read), 0) * 100)::numeric, 2) AS percentage
-FROM pg_statio_user_indexes
-UNION ALL
-SELECT
-  'Table Hit Rate' AS metric,
-  ROUND((SUM(heap_blks_hit) / NULLIF(SUM(heap_blks_hit + heap_blks_read), 0) * 100)::numeric, 2) AS percentage
-FROM pg_statio_user_tables;
-
-\echo ''
-\echo '8. Connection Pool Status:'
-SELECT
-  COUNT(*) AS total_connections,
-  COUNT(*) FILTER (WHERE state = 'active') AS active,
-  COUNT(*) FILTER (WHERE state = 'idle') AS idle,
-  COUNT(*) FILTER (WHERE state = 'idle in transaction') AS idle_in_transaction,
-  MAX(EXTRACT(EPOCH FROM (NOW() - query_start))) AS longest_query_seconds
-FROM pg_stat_activity
-WHERE datname = current_database();
-
-SQL
-```
-
----
-
-### Type: Interactive Optimization
-
-**When:** User selects `interactive`
-
-**Purpose:** Guided query optimization session
-
-```bash
-\echo '=== Interactive Query Optimization Session ==='
-\echo ''
-\echo 'This will guide you through optimizing a slow query.'
-\echo ''
-
-# Prompt for query
-read -p "Paste your slow query: " SLOW_QUERY
-
-# Step 1: Current performance
-psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<SQL
-\echo ''
-\echo 'Step 1: Current Performance Baseline'
-\echo ''
-
-\timing on
-EXPLAIN (ANALYZE, BUFFERS)
-$SLOW_QUERY;
-\timing off
-
-SQL
-
-# Step 2: Analyze table statistics
-psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<'SQL'
-\echo ''
-\echo 'Step 2: Table Statistics'
-\echo ''
-
--- Extract table names from query (basic regex)
--- This is simplified - actual implementation would parse query
-SELECT
-  schemaname,
-  tablename,
-  n_live_tup AS row_count,
-  seq_scan,
-  idx_scan,
-  n_tup_ins,
-  n_tup_upd,
-  n_tup_del,
-  last_vacuum,
-  last_analyze
-FROM pg_stat_user_tables
-WHERE schemaname = 'public'
-ORDER BY n_live_tup DESC;
-
-SQL
-
-# Step 3: Suggest indexes
-\echo ''
-\echo 'Step 3: Index Suggestions'
-\echo ''
-\echo 'Based on your query, consider these indexes:'
-\echo ''
-\echo '  1. Check WHERE clause columns - add index'
-\echo '  2. Check JOIN columns - add composite index'
-\echo '  3. Check ORDER BY columns - add index'
-\echo ''
-read -p "Would you like to see existing indexes? (y/n): " SHOW_INDEXES
-
-if [[ "$SHOW_INDEXES" == "y" ]]; then
-  psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<'SQL'
-  SELECT
-    schemaname,
-    tablename,
-    indexname,
-    indexdef
-  FROM pg_indexes
-  WHERE schemaname = 'public'
-  ORDER BY tablename, indexname;
-SQL
-fi
-
-# Step 4: Optimization recommendations
-\echo ''
-\echo 'Step 4: General Optimization Tips'
-\echo ''
-\echo '  ✓ Use EXPLAIN ANALYZE to understand execution'
-\echo '  ✓ Add indexes on WHERE/JOIN/ORDER BY columns'
-\echo '  ✓ Avoid SELECT * - specify only needed columns'
-\echo '  ✓ Use LIMIT for large result sets'
-\echo '  ✓ Consider materialized views for complex aggregations'
-\echo '  ✓ Use connection pooling (Supabase Pooler)'
-\echo '  ✓ Run VACUUM ANALYZE periodically'
-\echo ''
-
-read -p "Create index now? (y/n): " CREATE_INDEX
-
-if [[ "$CREATE_INDEX" == "y" ]]; then
-  read -p "Enter index SQL: " INDEX_SQL
-  psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<SQL
-  $INDEX_SQL;
-  \echo 'Index created. Re-run EXPLAIN to see improvement.'
-SQL
-fi
-```
-
----
-
-## Output Examples
-
-### Query Analysis Output
-
-```
-=== Query Performance Analysis ===
-
-Query:
-SELECT u.*, COUNT(p.id) FROM users u LEFT JOIN posts p ON p.user_id = u.id GROUP BY u.id;
-
-=== Execution Plan (EXPLAIN ANALYZE) ===
-
- HashAggregate  (cost=1234.56..1234.78 rows=22 width=520) (actual time=12.345..12.456 rows=22 loops=1)
-   ->  Hash Left Join  (cost=45.67..890.12 rows=34567 width=512) (actual time=2.345..10.123 rows=34567 loops=1)
-         Hash Cond: (p.user_id = u.id)
-         ->  Seq Scan on posts p  (cost=0.00..678.90 rows=34567 width=8) (actual time=0.012..5.678 rows=34567 loops=1)
-         ->  Hash  (cost=23.45..23.45 rows=22 width=504) (actual time=0.234..0.234 rows=22 loops=1)
-               ->  Seq Scan on users u  (cost=0.00..23.45 rows=22 width=504) (actual time=0.012..0.123 rows=22 loops=1)
- Planning Time: 1.234 ms
- Execution Time: 12.567 ms
-```
-
-### Hotpaths Output
-
-```
-=== Performance Hotpaths Analysis ===
-
-1. Top 10 Slowest Queries:
- query_preview                                    | calls | total_seconds | avg_ms | percent_total
---------------------------------------------------+-------+---------------+--------+---------------
- SELECT * FROM large_table WHERE complex_cond...  |  1234 |        123.45 | 100.04 |         45.67
- UPDATE users SET last_seen = NOW() WHERE...     |  5678 |         67.89 |  11.95 |         25.12
-
-... (additional output)
-```
-
----
-
-## Recommendations by Analysis Type
-
-### After Query Analysis
-
-- **Seq Scan → Index Scan:** Add index on WHERE clause columns
-- **High execution time:** Consider query rewrite or caching
-- **High buffer reads:** Add indexes to reduce I/O
-
-### After Hotpaths Analysis
-
-- **High seq_scan:** Add indexes on frequently scanned tables
-- **High dead_tup:** Run VACUUM ANALYZE
-- **Unused indexes:** Drop to reduce write overhead
-- **Low cache hit:** Increase shared_buffers or optimize queries
-
-### After Interactive Optimization
-
-- Test index impact with EXPLAIN ANALYZE before/after
-- Monitor query performance over time
-- Document optimization decisions
-
----
-
-## Related Commands
-
-- `*security-audit` - Check for missing indexes on FKs
-- `*verify-order {migration}` - Validate index creation order
-- `*create-migration-plan` - Plan index additions
-- `*explain {query}` - Legacy command (deprecated, use `*analyze-performance query`)
-
----
-
-**Prerequisites:**
-
-- `pg_stat_statements` extension enabled for hotpaths analysis:
-  ```sql
-  CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
-  ```
-
----
-
-**Note:** This consolidated task replaces `db-explain.md` and `db-analyze-hotpaths.md` (deprecated in v3.0)
+# Task: Analyze Performance
+
+**Purpose**: Query performance analysis and optimization (explain plans, hotpath detection, interactive optimization)
+
+**Elicit**: true
+
+**Consolidated From (Story 6.1.2.3):**
+- `db-explain.md` - Query execution plan analysis
+- `db-analyze-hotpaths.md` - Performance bottleneck detection
+- `query-optimization.md` - Interactive query optimization (if existed)
+
+---
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: analyzePerformance()
+responsável: Dex (Builder)
+responsavel_type: Agente
+atomic_layer: Strategy
+
+**Entrada:**
+- campo: target
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Valid path or identifier
+
+- campo: options
+  tipo: object
+  origem: config
+  obrigatório: false
+  validação: Analysis configuration
+
+- campo: depth
+  tipo: number
+  origem: User Input
+  obrigatório: false
+  validação: Default: 1 (0-3)
+
+**Saída:**
+- campo: analysis_report
+  tipo: object
+  destino: File (.ai/*.json)
+  persistido: true
+
+- campo: findings
+  tipo: array
+  destino: Memory
+  persistido: false
+
+- campo: metrics
+  tipo: object
+  destino: Memory
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target exists and is accessible; analysis tools available
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check target exists and is accessible; analysis tools available
+    error_message: "Pre-condition failed: Target exists and is accessible; analysis tools available"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Analysis complete; report generated; no critical issues
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify analysis complete; report generated; no critical issues
+    error_message: "Post-condition failed: Analysis complete; report generated; no critical issues"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Analysis accurate; all targets covered; report complete
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert analysis accurate; all targets covered; report complete
+    error_message: "Acceptance criterion not met: Analysis accurate; all targets covered; report complete"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** code-analyzer
+  - **Purpose:** Static code analysis and metrics
+  - **Source:** .aios-core/utils/code-analyzer.js
+
+- **Tool:** file-system
+  - **Purpose:** Recursive directory traversal
+  - **Source:** Node.js fs module
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** analyze-codebase.js
+  - **Purpose:** Codebase analysis and reporting
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/analyze-codebase.js
+
+---
+
+## Error Handling
+
+**Strategy:** fallback
+
+**Common Errors:**
+
+1. **Error:** Target Not Accessible
+   - **Cause:** Path does not exist or permissions denied
+   - **Resolution:** Verify path and check permissions
+   - **Recovery:** Skip inaccessible paths, continue with accessible ones
+
+2. **Error:** Analysis Timeout
+   - **Cause:** Analysis exceeds time limit for large codebases
+   - **Resolution:** Reduce analysis depth or scope
+   - **Recovery:** Return partial results with timeout warning
+
+3. **Error:** Memory Limit Exceeded
+   - **Cause:** Large codebase exceeds memory allocation
+   - **Resolution:** Process in batches or increase memory limit
+   - **Recovery:** Graceful degradation to summary analysis
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-20 min (estimated)
+cost_estimated: $0.003-0.015
+token_usage: ~2,000-8,000 tokens
+```
+
+**Optimization Notes:**
+- Iterative analysis with depth limits; cache intermediate results; batch similar operations
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - analysis
+  - metrics
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Elicitation
+
+**Prompt user to select analysis type:**
+
+```
+Select performance analysis type:
+
+1. **query** - Analyze specific query execution plan
+2. **hotpaths** - Detect performance bottlenecks across system
+3. **interactive** - Interactive query optimization session
+
+Which type? [query/hotpaths/interactive]:
+```
+
+**Capture:** `{type}`
+
+**If type=query, also prompt:**
+```
+Enter SQL query to analyze (or file path):
+```
+
+**Capture:** `{query}`
+
+---
+
+## Process
+
+### Type: Query Analysis (EXPLAIN)
+
+**When:** User selects `query`
+
+**Purpose:** Analyze execution plan for specific query
+
+#### Step 1: Validate Query
+
+```bash
+# Check if query is a file path
+if [[ -f "$QUERY" ]]; then
+  QUERY_SQL=$(cat "$QUERY")
+else
+  QUERY_SQL="$QUERY"
+fi
+
+# Validate SQL syntax (basic)
+echo "$QUERY_SQL" | grep -iE '^(SELECT|WITH|EXPLAIN)' || {
+  echo "❌ Error: Query must start with SELECT, WITH, or EXPLAIN"
+  exit 1
+}
+```
+
+#### Step 2: Run EXPLAIN ANALYZE
+
+```bash
+psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<SQL
+\echo '=== Query Performance Analysis ==='
+\echo ''
+\echo 'Query:'
+\echo '$QUERY_SQL'
+\echo ''
+\echo '=== Execution Plan (EXPLAIN ANALYZE) ==='
+
+EXPLAIN (ANALYZE, BUFFERS, VERBOSE, FORMAT TEXT)
+$QUERY_SQL;
+
+\echo ''
+\echo '=== JSON Format (for tools) ==='
+
+EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)
+$QUERY_SQL;
+
+SQL
+```
+
+#### Step 3: Analyze Results
+
+```bash
+psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<'SQL'
+\echo ''
+\echo '=== Performance Recommendations ==='
+
+-- Check for sequential scans on large tables
+SELECT
+  schemaname,
+  tablename,
+  seq_scan,
+  seq_tup_read,
+  idx_scan,
+  CASE
+    WHEN seq_scan > idx_scan THEN '⚠️ Consider adding index'
+    WHEN seq_tup_read > 10000 THEN '⚠️ Large sequential scan detected'
+    ELSE '✓ Looks good'
+  END AS recommendation
+FROM pg_stat_user_tables
+WHERE schemaname = 'public'
+  AND (seq_scan > idx_scan OR seq_tup_read > 10000)
+ORDER BY seq_tup_read DESC
+LIMIT 10;
+
+SQL
+```
+
+---
+
+### Type: Hotpaths Analysis
+
+**When:** User selects `hotpaths`
+
+**Purpose:** Detect performance bottlenecks across entire system
+
+```bash
+psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<'SQL'
+\echo '=== Performance Hotpaths Analysis ==='
+\echo ''
+
+-- 1. Slowest Queries (requires pg_stat_statements extension)
+\echo '1. Top 10 Slowest Queries:'
+SELECT
+  LEFT(query, 80) AS query_preview,
+  calls,
+  ROUND(total_exec_time::numeric / 1000, 2) AS total_seconds,
+  ROUND(mean_exec_time::numeric, 2) AS avg_ms,
+  ROUND((100 * total_exec_time / SUM(total_exec_time) OVER ())::numeric, 2) AS percent_total
+FROM pg_stat_statements
+WHERE query NOT LIKE '%pg_stat_statements%'
+ORDER BY total_exec_time DESC
+LIMIT 10;
+
+\echo ''
+\echo '2. Most Frequent Queries:'
+SELECT
+  LEFT(query, 80) AS query_preview,
+  calls,
+  ROUND(mean_exec_time::numeric, 2) AS avg_ms,
+  ROUND(total_exec_time::numeric / 1000, 2) AS total_seconds
+FROM pg_stat_statements
+WHERE query NOT LIKE '%pg_stat_statements%'
+ORDER BY calls DESC
+LIMIT 10;
+
+\echo ''
+\echo '3. Tables with Most Sequential Scans:'
+SELECT
+  schemaname,
+  tablename,
+  seq_scan,
+  seq_tup_read,
+  idx_scan,
+  n_live_tup AS approx_rows,
+  ROUND((seq_tup_read::numeric / NULLIF(seq_scan, 0)), 0) AS avg_rows_per_scan
+FROM pg_stat_user_tables
+WHERE schemaname = 'public'
+  AND seq_scan > 0
+ORDER BY seq_tup_read DESC
+LIMIT 10;
+
+\echo ''
+\echo '4. Tables with Bloat (Dead Tuples):'
+SELECT
+  schemaname,
+  tablename,
+  n_live_tup,
+  n_dead_tup,
+  ROUND((n_dead_tup::numeric / NULLIF(n_live_tup, 0) * 100), 2) AS dead_tuple_percent,
+  last_vacuum,
+  last_autovacuum
+FROM pg_stat_user_tables
+WHERE schemaname = 'public'
+  AND n_dead_tup > 100
+ORDER BY n_dead_tup DESC
+LIMIT 10;
+
+\echo ''
+\echo '5. Missing Indexes (Foreign Keys without indexes):'
+SELECT
+  t.tablename,
+  c.column_name,
+  pg_size_pretty(pg_relation_size(t.tablename::regclass)) AS table_size,
+  'CREATE INDEX idx_' || t.tablename || '_' || c.column_name || ' ON ' || t.tablename || '(' || c.column_name || ');' AS suggested_index
+FROM pg_tables t
+JOIN information_schema.columns c ON c.table_name = t.tablename
+LEFT JOIN pg_indexes i ON i.tablename = t.tablename
+  AND i.indexdef LIKE '%' || c.column_name || '%'
+WHERE t.schemaname = 'public'
+  AND c.table_schema = 'public'
+  AND c.column_name LIKE '%_id'
+  AND c.column_name != 'id'
+  AND i.indexname IS NULL
+ORDER BY pg_relation_size(t.tablename::regclass) DESC
+LIMIT 10;
+
+\echo ''
+\echo '6. Index Usage Statistics:'
+SELECT
+  schemaname,
+  tablename,
+  indexname,
+  idx_scan,
+  idx_tup_read,
+  idx_tup_fetch,
+  pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
+  CASE
+    WHEN idx_scan = 0 THEN '❌ Unused - consider dropping'
+    WHEN idx_scan < 100 THEN '⚠️ Low usage'
+    ELSE '✓ Active'
+  END AS usage_status
+FROM pg_stat_user_indexes
+WHERE schemaname = 'public'
+ORDER BY idx_scan ASC, pg_relation_size(indexrelid) DESC
+LIMIT 15;
+
+\echo ''
+\echo '7. Cache Hit Ratio (should be > 99%):'
+SELECT
+  'Index Hit Rate' AS metric,
+  ROUND((SUM(idx_blks_hit) / NULLIF(SUM(idx_blks_hit + idx_blks_read), 0) * 100)::numeric, 2) AS percentage
+FROM pg_statio_user_indexes
+UNION ALL
+SELECT
+  'Table Hit Rate' AS metric,
+  ROUND((SUM(heap_blks_hit) / NULLIF(SUM(heap_blks_hit + heap_blks_read), 0) * 100)::numeric, 2) AS percentage
+FROM pg_statio_user_tables;
+
+\echo ''
+\echo '8. Connection Pool Status:'
+SELECT
+  COUNT(*) AS total_connections,
+  COUNT(*) FILTER (WHERE state = 'active') AS active,
+  COUNT(*) FILTER (WHERE state = 'idle') AS idle,
+  COUNT(*) FILTER (WHERE state = 'idle in transaction') AS idle_in_transaction,
+  MAX(EXTRACT(EPOCH FROM (NOW() - query_start))) AS longest_query_seconds
+FROM pg_stat_activity
+WHERE datname = current_database();
+
+SQL
+```
+
+---
+
+### Type: Interactive Optimization
+
+**When:** User selects `interactive`
+
+**Purpose:** Guided query optimization session
+
+```bash
+\echo '=== Interactive Query Optimization Session ==='
+\echo ''
+\echo 'This will guide you through optimizing a slow query.'
+\echo ''
+
+# Prompt for query
+read -p "Paste your slow query: " SLOW_QUERY
+
+# Step 1: Current performance
+psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<SQL
+\echo ''
+\echo 'Step 1: Current Performance Baseline'
+\echo ''
+
+\timing on
+EXPLAIN (ANALYZE, BUFFERS)
+$SLOW_QUERY;
+\timing off
+
+SQL
+
+# Step 2: Analyze table statistics
+psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<'SQL'
+\echo ''
+\echo 'Step 2: Table Statistics'
+\echo ''
+
+-- Extract table names from query (basic regex)
+-- This is simplified - actual implementation would parse query
+SELECT
+  schemaname,
+  tablename,
+  n_live_tup AS row_count,
+  seq_scan,
+  idx_scan,
+  n_tup_ins,
+  n_tup_upd,
+  n_tup_del,
+  last_vacuum,
+  last_analyze
+FROM pg_stat_user_tables
+WHERE schemaname = 'public'
+ORDER BY n_live_tup DESC;
+
+SQL
+
+# Step 3: Suggest indexes
+\echo ''
+\echo 'Step 3: Index Suggestions'
+\echo ''
+\echo 'Based on your query, consider these indexes:'
+\echo ''
+\echo '  1. Check WHERE clause columns - add index'
+\echo '  2. Check JOIN columns - add composite index'
+\echo '  3. Check ORDER BY columns - add index'
+\echo ''
+read -p "Would you like to see existing indexes? (y/n): " SHOW_INDEXES
+
+if [[ "$SHOW_INDEXES" == "y" ]]; then
+  psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<'SQL'
+  SELECT
+    schemaname,
+    tablename,
+    indexname,
+    indexdef
+  FROM pg_indexes
+  WHERE schemaname = 'public'
+  ORDER BY tablename, indexname;
+SQL
+fi
+
+# Step 4: Optimization recommendations
+\echo ''
+\echo 'Step 4: General Optimization Tips'
+\echo ''
+\echo '  ✓ Use EXPLAIN ANALYZE to understand execution'
+\echo '  ✓ Add indexes on WHERE/JOIN/ORDER BY columns'
+\echo '  ✓ Avoid SELECT * - specify only needed columns'
+\echo '  ✓ Use LIMIT for large result sets'
+\echo '  ✓ Consider materialized views for complex aggregations'
+\echo '  ✓ Use connection pooling (Supabase Pooler)'
+\echo '  ✓ Run VACUUM ANALYZE periodically'
+\echo ''
+
+read -p "Create index now? (y/n): " CREATE_INDEX
+
+if [[ "$CREATE_INDEX" == "y" ]]; then
+  read -p "Enter index SQL: " INDEX_SQL
+  psql "$SUPABASE_DB_URL" -v ON_ERROR_STOP=1 <<SQL
+  $INDEX_SQL;
+  \echo 'Index created. Re-run EXPLAIN to see improvement.'
+SQL
+fi
+```
+
+---
+
+## Output Examples
+
+### Query Analysis Output
+
+```
+=== Query Performance Analysis ===
+
+Query:
+SELECT u.*, COUNT(p.id) FROM users u LEFT JOIN posts p ON p.user_id = u.id GROUP BY u.id;
+
+=== Execution Plan (EXPLAIN ANALYZE) ===
+
+ HashAggregate  (cost=1234.56..1234.78 rows=22 width=520) (actual time=12.345..12.456 rows=22 loops=1)
+   ->  Hash Left Join  (cost=45.67..890.12 rows=34567 width=512) (actual time=2.345..10.123 rows=34567 loops=1)
+         Hash Cond: (p.user_id = u.id)
+         ->  Seq Scan on posts p  (cost=0.00..678.90 rows=34567 width=8) (actual time=0.012..5.678 rows=34567 loops=1)
+         ->  Hash  (cost=23.45..23.45 rows=22 width=504) (actual time=0.234..0.234 rows=22 loops=1)
+               ->  Seq Scan on users u  (cost=0.00..23.45 rows=22 width=504) (actual time=0.012..0.123 rows=22 loops=1)
+ Planning Time: 1.234 ms
+ Execution Time: 12.567 ms
+```
+
+### Hotpaths Output
+
+```
+=== Performance Hotpaths Analysis ===
+
+1. Top 10 Slowest Queries:
+ query_preview                                    | calls | total_seconds | avg_ms | percent_total
+--------------------------------------------------+-------+---------------+--------+---------------
+ SELECT * FROM large_table WHERE complex_cond...  |  1234 |        123.45 | 100.04 |         45.67
+ UPDATE users SET last_seen = NOW() WHERE...     |  5678 |         67.89 |  11.95 |         25.12
+
+... (additional output)
+```
+
+---
+
+## Recommendations by Analysis Type
+
+### After Query Analysis
+
+- **Seq Scan → Index Scan:** Add index on WHERE clause columns
+- **High execution time:** Consider query rewrite or caching
+- **High buffer reads:** Add indexes to reduce I/O
+
+### After Hotpaths Analysis
+
+- **High seq_scan:** Add indexes on frequently scanned tables
+- **High dead_tup:** Run VACUUM ANALYZE
+- **Unused indexes:** Drop to reduce write overhead
+- **Low cache hit:** Increase shared_buffers or optimize queries
+
+### After Interactive Optimization
+
+- Test index impact with EXPLAIN ANALYZE before/after
+- Monitor query performance over time
+- Document optimization decisions
+
+---
+
+## Related Commands
+
+- `*security-audit` - Check for missing indexes on FKs
+- `*verify-order {migration}` - Validate index creation order
+- `*create-migration-plan` - Plan index additions
+- `*explain {query}` - Legacy command (deprecated, use `*analyze-performance query`)
+
+---
+
+**Prerequisites:**
+
+- `pg_stat_statements` extension enabled for hotpaths analysis:
+  ```sql
+  CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+  ```
+
+---
+
+**Note:** This consolidated task replaces `db-explain.md` and `db-analyze-hotpaths.md` (deprecated in v3.0)