---
name: o11y-alert-rule-lookup
description: |
  Locate the runbook alert rule for a TiDB Cloud O11Y alert by alert name.
  Use when an O11Y Jira issue or workspace alert context includes an alertname
  and later analysis needs the matching Prometheus rule under runbooks/rules.
  Read-only. Returns exact matches first, then fuzzy candidates if no exact rule
  name match is found.
---

# O11Y Alert Rule Lookup

Use this skill when the workspace contains an O11Y alert ticket and you need the
corresponding alert rule definition from the TiDB Cloud runbooks repository.

This skill is most useful before deeper diagnosis, because the matched rule gives
you the exact `expr`, `for`, labels, and annotations behind the alert.

## Workflow

1. Get the alert name.
   If the source is an O11Y Jira issue, prefer the bundled Jira skill:

```bash
python3 .opencode/skills/builtin/jira/scripts/jira_api.py get-alert-info --issue-key O11Y-1956041
```

Use the returned `alert_name`. If the workspace already contains the alert name
in prepared files or source metadata, reuse that value instead of re-querying Jira.

2. Resolve the runbooks checkout.

The search script looks for the runbooks repository in this order:

- `--runbooks-dir <path>` if you pass it explicitly
- `TIDBCLOUD_RUNBOOKS_DIR`
- `runbooks/` under the current workspace
- `../runbooks`
- `../../runbooks`

The repository root must contain `rules/`.

3. Search for the matching rule.

```bash
python3 .opencode/skills/builtin/o11y-alert-rule-lookup/scripts/find_alert_rule.py \
  --alert-name HighCPUUsage
```

Or with an explicit checkout:

```bash
python3 .opencode/skills/builtin/o11y-alert-rule-lookup/scripts/find_alert_rule.py \
  --alert-name HighCPUUsage \
  --component tidb \
  --message "Memory usage exceeded 90%" \
  --runbooks-dir ../runbooks
```

If `issue_meta.json` includes `component` and `messages`, pass them to the script
when multiple rules share the same alert name. `messages` can be repeated:

```bash
python3 .opencode/skills/builtin/o11y-alert-rule-lookup/scripts/find_alert_rule.py \
  --alert-name HighCPUUsage \
  --component tidb \
  --message "server is running out of memory" \
  --message "RSS exceeded threshold"
```

## Output Contract

The script prints JSON with:

- `exact_matches`: rules whose `alert:` field exactly matches the alert name
- `fuzzy_matches`: nearby candidates when exact match is missing
- `top_match`: the highest-ranked rule after optional `component/messages` scoring
- `searched_files`: number of YAML files scanned under `rules/`

Each match includes:

- `file`: path relative to the runbooks repo
- `alert`: rule alert name from YAML
- `match_type`: `exact`, `case_insensitive_exact`, `normalized_exact`, `substring`, or `token_overlap`
- `score`: ranking score for fuzzy candidates
- `context_score`: extra score from `component/messages`
- `expr`: first line of the rule expression when present
- `for`: alert `for` duration when present
- `snippet`: compact nearby excerpt for quick inspection

## Usage Rules

- Treat `exact_matches` as authoritative for alert-name grounding.
- If there are multiple exact matches, use `component` and `messages` to rank them
  first, then inspect the top candidates' file path, labels, annotations, and expr.
- If there is no exact match, present the top fuzzy candidates as candidates only.
- Do not invent a rule mapping when the script finds nothing.
- This skill is read-only. Do not edit the runbooks repository from this workflow.