/diagnose-clickhouse-errors

name: diagnose-clickhouse-errors
description: Diagnose ClickHouse runtime query failures when the user wants database-level cause and fix guidance from an error or numeric error code, not source-code root cause analysis.
metadata:
  author: DataStoria

When Not To Use

Do not use this skill when the user's primary goal is:

• investigating application or repository source code
• tracing where failing SQL was constructed in code
• finding code paths that produced the ClickHouse error

In those cases, prefer `source-code-inspection`. Do not start this skill's error-code intake flow unless the user is asking for database-level diagnosis.

Workflow

1. Determine whether the user is asking for database-level diagnosis or source-code investigation. If the primary goal is source-code investigation or file-cited code analysis, stop and prefer `source-code-inspection`. 2. Extract the numeric ClickHouse error code from the conversation or error text (e.g. `Code: 60`). 3. If no numeric error code is detected and the user is asking for database-level diagnosis, call `ask_user_question` with exactly one question. Do NOT reply with natural-language text before the tool call.

• `header`: `Please provide a ClickHouse error code for diagnosis`
• `options`: `[ { "id": "error_code", "label": "error code", "input": "text" } ]`
• Treat the returned `value` as the numeric error code and continue.

4. Load `references/<code>.md` with `skill_resource` (e.g. `references/60.md`) and follow its workflow. 5. If the orchestrator provides database context facts, use them when they materially change the cause or fix. 6. If `skill_resource` returns nothing, use your ClickHouse knowledge to provide a best-effort response.

Response format

• **Section 1 (Cause)** — One short sentence explaining why the error occurred.
• **Section 2 (Fix)** — Bullet list of concrete steps.
• **Section 3 (Example)** — A single fenced SQL block with the corrected query; omit if not applicable.

Heading rules:

• Default (English): use headings `## Cause`, `## Fix`, and optional `## Example`.
• If a response language is specified by system policy or user message (`Response language (BCP-47): …`), localize the heading text to that language while keeping the same 3-section structure.
• Keep SQL, codes, and identifiers as-is.

Keep answers brief and action-first. Do not repeat the raw error verbatim. Do not add extra headings.