---
name: diagnose-clickhouse-clusters
description: Diagnose ClickHouse cluster health and provide concrete remediation.
---

# Tool Usage Rules

- Call `collect_cluster_status` before health conclusions about current cluster health.
- For RCA questions, call `collect_rca_evidence` directly when the symptom and target are already clear. Use `collect_cluster_status` first only when you need current health context, severity/outliers, or help choosing the RCA symptom/scope.
- Use only supported Phase 1 RCA symptoms: `high_part_count` and `unknown`.
- For bounded-time questions, use `status_analysis_mode="windowed"` and reuse the same time window in follow-up calls.
- If user asks for a chart, use the `visualization` skill. Do not emit chart specs directly from this skill.
- Do not invent custom health-check SQL. Use tool outputs as the source of truth.

# Workflow (MANDATORY)

1. Determine whether the user asks for status only, or root cause ("why", "root cause", "reason", "caused by", "explain").
2. For RCA questions, pick one supported canonical symptom key based on user wording, explicit target details, and, when needed, status findings.
3. Explain from tool output only: top candidates, support score, evidence lists, gaps, and prioritized actions.

# Severity Thresholds (Guidance)

- CRITICAL: replication lag > 300s, disk usage > 90%
- WARNING: replication lag > 60s, disk usage > 80%
- OK: metrics within normal ranges

Do not hardcode parts thresholds in responses. Use the thresholds and severities returned by `collect_cluster_status`.

# Output Format (MANDATORY)

Use one of these two formats:

## A) Status-only question

1. Summary table:
   Always print a table title line exactly before the table: `### Summary`.
   | Status | Nodes with Issues | Checks Run | Timestamp |
   |--------|-------------------|------------|-----------|
   | 🟢 OK / 🟠 WARNING / 🔴 CRITICAL | N | categories | ISO8601 |
2. Findings by category:
   Always print a table title line exactly before the table: `### Findings by Category`.
   Use a markdown table (not bullets) with one row per category.
   Required columns:
   | Category | Status | Key Metrics | Top Outlier / Scope | Notes |
   |----------|--------|-------------|----------------------|-------|
   | parts / errors / replication / ... | 🟢 OK / 🟠 WARNING / 🔴 CRITICAL | concise metric values with thresholds | node/table if present, else `-` | one short phrase |

   Table rules:
   - Include all categories returned by `collect_cluster_status` in stable order.
   - Status must include both emoji and text (for example `🟠 WARNING`), never emoji-only.
   - Markdown table cells do not reliably support line breaks in this UI. Do not try to render multi-line bullets in a cell.
   - In `Key Metrics`, put the 1-2 most important metrics only (single-line, semicolon-separated if needed).
   - Put additional metrics in `Notes` as compact key/value items (single-line).
   - Put numeric values first (for example `max_parts_per_table=533 (>500)`), avoid prose-heavy sentences.
   - Always wrap database/table identifiers in backticks (for example `` `db.table` `` or `` `db` ``) in all table cells.
   - If category has sub-findings (for example top errors), keep them in `Notes` as compact comma-separated items.
   - If no outlier exists, set `Top Outlier / Scope` to `-`.

3. Recommendations (max 3 items; each item = title + why + concrete SQL/command if needed).

## B) RCA question ("why", "cause", "reason", "explain")

Use compact structure only:

1. **RCA Verdict**: one sentence, max 30 words.
2. **Top Candidates**: markdown table with max 3 rows: `cause | support_score | evidence`.
   In `evidence`, render up to 3 `evidence_for` items prefixed with `✓` and up to 2 `evidence_against` items prefixed with `✗`, separated by `<br/>`.
   When `excluded_candidates` is non-empty, include at least one excluded reason as a `✗` item for the most relevant row.
   Evidence fidelity rules:
   - Use only `candidate.evidence_for` and `candidate.evidence_against` from `collect_rca_evidence` for that row.
   - Do not pull extra lines from top-level `observations`, other candidates, or status output into the evidence cell.
   - Do not restate raw metrics unless they already appear inside `candidate.evidence_for` or `candidate.evidence_against`.
   - Preserve the candidate/tool counts: if helpful, you may mention `indicators_matched/indicators_checked`, but never imply more matched checks than the tool returned.
3. **Possible Actions**: max 3 numbered items, sorted by impact.
   Formatting rule: print the line `3. **Possible Actions**`, then a blank line, then an indented nested numbered list using exactly `   1.`, `   2.`, `   3.`.
   Do not continue the outer top-level numbering for action items.
4. **Gaps / Next Checks**: max 2 bullets.
   Formatting rule: print the line `4. **Gaps / Next Checks**`, then a blank line, then indented bullets using exactly `   -`.

RCA brevity limits:

- Keep total RCA response under 220 words (excluding SQL command blocks).
- Do not add long background/theory paragraphs.
- Use direct statements and numeric evidence.

# Critical Rules

- ALWAYS call `collect_cluster_status` before giving any opinion on current health.
- Use `status_analysis_mode="windowed"` when user asks for a bounded time window or historical context.
- For RCA questions, MUST call `collect_rca_evidence`. `collect_cluster_status` is optional unless current health context is needed.
- Do NOT state root causes without RCA evidence output.
- If `gaps[]` is non-empty, explicitly state what evidence is missing.
- If all candidates have `support_score < 0.3`, state that the RCA is inconclusive and use candidate `next_checks` plus `gaps` to explain what to inspect next.
- If best candidate is weak (`0.30-0.39`), present it as a possibility with caveats and emphasize candidate `next_checks`.
- Never fabricate or merge evidence lines across candidates. Candidate rows must be traceable directly to that candidate's `evidence_for` and `evidence_against`.
- If `collect_rca_evidence.related_symptoms` is non-empty, include a line `Related symptoms:` and list them.
- When follow-up questions omit time range, reuse the most recent explicit time window/range from prior turns.
- Never assume schema or table names; use only what tools return.
- Do not invent custom health-check SQL; use tool outputs as source of truth.
- Be concise and focus on remediation, not theory.