[H1][PROMQL-GENERATOR]

Dictum: Query generation follows metric type, then pattern, then optimization.

Generate PromQL for Prometheus 3.8-3.10 (native histograms stable, feature flag no-op since 3.9). Cross-references: promql-validator for validation, observability-stack for deployment.

Tasks:

1. Gather goal, use case, metric context via AskUserQuestion (skip if provided).
2. Identify metric names, types, labels -- confirm with user.
3. Read relevant reference: references/promql_functions.md, references/promql_patterns.md, references/best_practices.md.
4. Present plain-English plan; confirm via AskUserQuestion.
5. Generate query citing applicable pattern.
6. Invoke promql-validator skill; fix and re-validate until all checks pass.
7. Deliver: final query + explanation + usage context + customization notes.

[1][METRIC_IDENTIFICATION]

Dictum: Metric type determines function selection.

Guidance:

• Range >= 4x scrape interval. Label filters: exact =, negative !=, regex =~.
• Aggregation: sum by (labels) to keep, sum without (labels) to drop.
• Native histograms eliminate le label and _bucket suffix -- single opaque series per histogram.

[2][VERSION_MATRIX]

Dictum: Version awareness prevents deprecated patterns.

Guidance:

• Activate native histograms: scrape_native_histograms: true in scrape config (not a feature flag).
• Three experimental gates remain: promql-experimental-functions, promql-duration-expr, promql-extended-range-selectors.

[3][NATIVE_HISTOGRAMS]

Dictum: Native histograms replace classic for all new instrumentation.

No _bucket suffix or le label. Reduces series cardinality 10-100x. NHCB (3.4+): classic-to-native conversion via convert_classic_histograms_to_nhcb: true.

# Classic: histogram_quantile(0.95, sum by (job, le) (rate(metric_bucket[5m])))
# Native:  histogram_quantile(0.95, sum by (job) (rate(metric[5m])))

Best-Practices:

• Prefer histogram_avg() over manual _sum/_count division -- single function, single series.
• Use histogram_fraction(0, 0.2, rate(m[5m])) for latency SLOs -- precise without bucket interpolation.
• rate(), increase(), delta() on native histograms produce gauge histograms (3.9+).

[4][EXPERIMENTAL_FUNCTIONS]

Dictum: Experimental functions expand analysis under explicit feature flags.

Guidance:

• info() replaces manual * on (...) group_left (...) for metadata joins.
• mad_over_time enables z-score anomaly detection: m > avg_over_time(m[1h]) + 3 * mad_over_time(m[1h]).
• limitk/limit_ratio use deterministic hash-based sampling -- same series across evaluations.

[5][LOOKUP_STRATEGY]

Dictum: Lookup strategy prioritizes authoritative sources.

context7 MCP (preferred): resolve "prometheus" -> get-library-docs with topic. WebSearch fallback: "Prometheus PromQL [topic] documentation examples".

[6][RESOURCES]

Dictum: Reference files provide detailed function, pattern, and optimization guidance.