aios-core 2.1.0

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

@@ -0,0 +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)