Query Explainer Protocol

This skill bridges the gap between raw database optimizer output and human-readable performance tuning. It reads EXPLAIN (ANALYZE, BUFFERS) and translates the nodes and costs into concrete actions.

Core assumption: A developer should not need to be a DBA to understand why their query takes 3 seconds and what to do about it.

1. Plan Ingestion & Translation (Static vs Dynamic)

• Default (Static): Analyze based on user-provided EXPLAIN text/JSON outputs.
• Dynamic (On-Demand): Only connect to a live database to execute EXPLAIN (ANALYZE, BUFFERS) directly if the user explicitly authorizes it and provides the target query.
• When evaluating the plan structurally:
  • Cost vs Actual: Differentiate between planner estimates (cost=0.00..10.00) and reality (actual time=0.015..0.020).
  • Data Volume: Note discrepancies between rows=1000000 (estimated) and loops=1 actual rows fetched (this indicates bad statistics).