Skip to content

feat(ai): compact terminal output for /explain and /optimize #742

@NikolayS

Description

@NikolayS

Problem

/explain and /optimize output is too verbose for terminal use. The AI response streams full prose paragraphs that are hard to scan quickly in a terminal session.

Goal

Make both commands feel like a senior DBA giving you a quick answer at the terminal, not a blog post. Compact, high-signal, immediately actionable.

Proposed output format

/explain

-- EXPLAIN ANALYZE output (shown as today) --

[AI]
Bottleneck: Seq Scan on orders (cost=0.00..4821.00, 98K rows) — consider index on status
Est. error: 12x overestimate on nested loop (est 1 vs actual 12)
Time: planning 2ms, execution 847ms

Rules for AI section:

  • Max 4 lines, no headers, no markdown bullet lists
  • Lead with the single most expensive node
  • One line per finding (bottleneck / row-estimate error / wait correlation if present)
  • End with planning + execution time summary
  • No prose, no "In this query...", no restating what the user can already see

/optimize

-- EXPLAIN ANALYZE output --

[AI]
1. CREATE INDEX orders_status_idx ON orders(status); -- seq scan → index scan, est. 10x speedup
2. Rewrite: replace correlated subquery in line 3 with LEFT JOIN
3. Vacuum orders — 40K dead tuples, last vacuum 14 days ago

Rules for AI section:

  • Ordered list of concrete actions, highest impact first
  • Each line: action + single-line rationale
  • CREATE INDEX suggestions must be copy-pasteable SQL
  • No prose intro, no "Based on the plan...", no section headers

Implementation

  • Modify system prompts in handle_ai_explain and handle_ai_optimize in src/repl/ai_commands.rs
  • Update max_tokens budget for explain/optimize (current default likely too high for compact output — suggest 300-400 tokens)
  • Add unit tests for the prompt structure
  • Test with real queries against local Postgres and paste evidence in PR

Acceptance criteria

  • /explain AI section fits in ≤4 terminal lines for a typical query
  • /optimize returns ≤5 numbered items, each ≤1 line
  • No change to the raw EXPLAIN ANALYZE output shown before the AI section
  • Existing tests pass

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions