WORKFLOW (MANDATORY ORDER)

a) Generate or obtain SQL:

• CHECK CONTEXT FIRST: If valid SQL exists in the context (explicitly provided by the user or from a previous message), USE IT DIRECTLY and skip to step (b).
• IF NO SQL FOUND: You must generate it.
  • Dependency: Valid SQL generation REQUIRES the

    sql-expert

    skill.
  • Action: Check if

    sql-expert

    skill is loaded.
    • If NOT loaded: Call the

      skill

      tool with

      ['sql-expert']

      IMMEDIATELY. Do not proceed to generate SQL until the skill is loaded.
    • If ALREADY loaded: Generate the SQL strictly following the rules in the

      sql-expert

      skill (including Schema Discovery, Schema Fidelity, ProfileEvents handling, and Performance Optimization).
• For

  system.query_log

  visualization requests: Do NOT call

  search_query_log

  . Load the

  clickhouse-system-queries

  skill, then load

  references/system-query-log.md

  via

  skill_resource

  , generate the SQL, and validate it.

b) VALIDATION (MANDATORY):

• ALWAYS call

  validate_sql

  with the SQL before including the chart spec in your response.
• RETRY LOGIC: If validation fails, retry up to 3 times by fixing the SQL (referring to

  sql-expert

  skill rules) and validating again.
• Only proceed to step (c) if validation returns success: true.

c) After validation passes:

• Include the full chart spec in your response using a markdown code block with language

  chart-spec

  . The content must be valid JSON matching the OUTPUT FORMAT below, and must include

  datasource: { "sql": "<the validated SQL>" }

  . Derive type, titleOption, legendOption, etc. from the CHART TYPE RULES and OUTPUT FORMAT above. Do not call any tool for this—put the complete spec in your reply.

d) Execution:

• PROHIBITED: Do NOT call

  execute_sql

  . The chart component in the client will automatically execute the query found in the

  chart-spec

  . Calling it here wastes tokens and causes duplicate execution.

CHART TYPE RULES

STEP 1: CHECK USER'S EXPLICIT CHART REQUEST (HIGHEST PRIORITY)

If user question contains ANY of these keywords, use the corresponding chart type:

• "line chart" → type: "line" (MANDATORY)
• "bar chart" → type: "bar" (MANDATORY)
• "pie chart" → type: "pie" (MANDATORY)
• "timeseries" or "time series" → type: "line" (MANDATORY)
• "trend" → type: "line" (MANDATORY)

STEP 2: ANALYZE SQL (Only if no explicit chart request in Step 1)

• "line" - Time-based data with trends (DateTime/Date + GROUP BY time dimension; "over time", "by day/month/hour").
• "bar" - Categorical comparisons (GROUP BY categories; "compare", "by category").
• "pie" - Categorical distribution, proportions (single categorical dimension; "distribution", "breakdown", "proportion"; 2 columns: category + numeric value; best for 3-15 categories).
• "table" - Raw data listing (LAST RESORT): user asks for "table" or "list" with NO chart keywords; no numeric aggregations.

CRITICAL RULES

• When legendOption.placement is "bottom" or "right", you MUST include a "values" array: base ["min", "max"]; add "sum"/"count" if SQL uses SUM/COUNT; add "avg" if SQL uses AVG.
• Line/Bar: Use "bottom" for GROUP BY with non-time dimensions, "none" for single metric.
• Pie: legendOption.placement "right"|"bottom"|"inside" (no "none"); omit legendOption.values; use labelOption (show, format) and valueFormat as needed.

OUTPUT FORMAT (include in your response as a

chart-spec

code block)

Put the full chart spec in a markdown code block with language chart-spec. The JSON must include

datasource.sql

(the validated SQL). The client parses this block to render the chart.

Line/Bar Chart example:

{
  "type": "line",
  "titleOption": { "title": "Descriptive chart title", "align": "center" },
  "width": 6,
  "legendOption": { "placement": "bottom", "values": ["min", "max", "sum"] },
  "datasource": { "sql": "SELECT ..." }
}

Pie Chart example:

{
  "type": "pie",
  "titleOption": { "title": "Distribution by Category", "align": "center" },
  "width": 6,
  "legendOption": { "placement": "right" },
  "labelOption": { "show": true, "format": "name-percent" },
  "valueFormat": "short_number",
  "datasource": { "sql": "SELECT ..." }
}

• ❌ NEVER include a chart spec before validate_sql has succeeded.
• ❌ NEVER skip SQL generation if no SQL exists in context.
• ❌ NEVER write SQL in your text response—ALWAYS use the instructions in

  sql-expert

  skill.
• ✅ ALWAYS follow: Check for SQL → If missing, Load

  sql-expert

  Skill → Validation → Include chart spec in response.
• ✅ If validation fails, retry up to 3 times.