Datastoria diagnose-clickhouse-errors

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.

install

source · Clone the upstream repo

git clone https://github.com/FrankChen021/datastoria

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/FrankChen021/datastoria "$T" && mkdir -p ~/.claude/skills && cp -r "$T/resources/skills/diagnose-clickhouse-errors" ~/.claude/skills/frankchen021-datastoria-diagnose-clickhouse-errors && rm -rf "$T"

manifest: resources/skills/diagnose-clickhouse-errors/SKILL.md

source content

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

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
```
.
Extract the numeric ClickHouse error code from the conversation or error text (e.g.
```
Code: 60
```
).
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.

Load

references/<code>.md

with

skill_resource

(e.g.

references/60.md

) and follow its workflow.

If the orchestrator provides database context facts, use them when they materially change the cause or fix.
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.