--- name: evidence-query-planning description: Plan bounded observability queries across Clinic, Wetech, and Manus as the Auto-oncall Evidence Agent. Use with the selected Provider Skill for metric scope, source cardinality, evidence-backed selectors, changed query repair, and purpose-specific Slow Query summaries; not diagnosis or Provider execution. --- # Evidence query planning ## Scope and owner The Evidence Agent applies this shared planning Skill together with exactly one selected Provider Skill. It chooses a neutral query for the supplied question and stop condition. This Skill grants no Tool, network, credential, or installation authority. In scope: source-sample versus returned-series limits, incident-bounded query windows, provenance of metric selectors, and changed query planning after a resource-limit rejection or timeout, plus purpose-driven Slow Query evidence selection and neutral result summaries. Apply the planning rules to both Agent9 Managed Tools and the local plan path, regardless of Provider. Out of scope: target/provider selection, diagnosis, mitigation, severity, human handoff, response wording, SQL tuning, authentication, navigation, endpoints, datasource IDs, operation schemas, transport retries/concurrency, and Provider-specific metric availability or label mappings. Keep those in their existing Agent, runner, or Provider contract. A different metric family is not automatically available merely because this Skill discusses it. ## Bound the source work separately from the result Before a PromQL query, consider the source series read by every selector as well as the final returned series. Histograms and multiplicative dimensions such as instance/store, source/target, or instance/address/store can be costly even when the output is tiny. `sum`, `histogram_quantile`, and outer `topk` reduce output; they do not bound the input scan. Use aggregation or a small top-k for useful output, and independently bound expensive source selectors. A coarse `step` is not the primary repair for source-series fan-out and can hide brief spikes. For `tidb_tikvclient_request_seconds_{bucket,sum,count}`, every referenced selector MUST have an exact, non-empty TiDB `instance="..."` or TiKV `store="..."` equality filter with proven provenance. Also use an explicit start/end range of at most 15 minutes inside the authorized incident window. An already shorter incident window is sufficient; do not narrow it merely to make its endpoints different. `type="Cop"`, `store!="0"`, broad regexes, aggregation, and `topk` do not satisfy the endpoint filter requirement. If no trusted endpoint selector is available, do not query this family cluster-wide to discover one. Use an available lower-cardinality signal or a Provider-declared identity mapping first, or preserve the precise acquisition gap when the stop condition cannot be met. Do not guess an endpoint to make the query look valid. This mandatory planning rule is specific to this observed expensive family; it is not an exact-node requirement for every metric, peer comparison, or cluster-level aggregate. For other histogram or multiplicative families, use the same source-work reasoning to choose a short aligned window, proven selectors, or a suitable lower-cardinality signal. Do not create a universal metric allowlist. ## Preserve scope and selector provenance Stay within the runner-owned target and absolute incident or explicitly authorized comparison windows. Start with the smallest interval that answers the supplied question, retaining any required baseline. Provider operation limits are additional ceilings, not default query sizes. Do not widen the window, increase a timeout, or switch Provider to evade a rejected query. A label key/value in a compact result belongs to its producing metric family. Reuse it verbatim as an equality matcher only when the authorized context or same-family result proves that exact key/value. Do not turn a display name, TiDB/TiKV node name, store, address, pod, or host from another family into a guessed selector. Do not construct regexes from observed label values. A Provider-declared deterministic identity mapping or opaque instance handle may supply a cross-surface binding only for its documented destination; the Provider owns that mapping and resolves opaque handles before execution. When compatible labels are unknown, a bounded native-label aggregate or top-k can discover peers only when the source scan is itself bounded. The mandatory TiDB-to-TiKV family rule above still applies. If no safe discovery query can answer the objective, report the missing mapping instead of guessing. ## Changed query after a resource failure A timeout alone does not prove source overload. Inspect the exact operation, window, selectors, and returned error. If source fan-out is apparent and the runner/Provider permits a correction, keep the same objective and query ID, change the expensive scope using proven filters or a suitable alternative, and preserve successful peer results. Do not repeat unchanged calls or raise timeouts as the default fix. Stop on an unsupported objective, absent safe selector, or exhausted runner-owned budget. Authentication and navigation failures stay with the Provider and do not authorize query-shape retries. These are Agent planning requirements. A Skill is not an executable preflight and cannot guarantee enforcement by itself. Existing Provider validations remain owned by the executor; do not infer that every backend implements a hard selector guard merely because it loads this Skill. ## Select Slow Query evidence for the diagnostic question Use the Scenario Diagnostic Agent's `problemSummary` as the overall question and `question` as the current acquisition purpose. Keep both in view when choosing queries and deciding whether the result needs a brief summary or specific execution details. A query returning many rows does not make every row useful for that purpose. Do not routinely query every supported ordering: start with the ordering and incident scope that can identify the relevant execution group, and acquire another view only to resolve a concrete remaining comparison. Different server-side top-N orderings can select different rows; one limited result is not a complete population that can reproduce all ranks. For Agent9 Managed Tool execution, use the runner's `slowQuerySummaries` output to combine selected Slow Query results after observing them. Reference their exact current-round Tool `queryId` values, never invented artifact filenames. Leave the array empty when the original compact facts already suit the purpose. Summaries replace only the referenced Slow Query observations; the runner preserves raw reports, query coverage, errors, and all other Provider facts. The local plan path returns its existing plan acknowledgement before execution and does not produce this post-execution summary. For broad discovery, report the relevant execution groups, observed sample counts, instance and time coverage, and ranges or contrasts that answer the question. Keep provider candidate counts distinct from returned sample counts; do not extrapolate a ranked sample to cluster-wide frequency or contribution. Background rows can be summarized briefly rather than copied individually. For an exact execution comparison, retain the actual contrasting records: identity, plan association, time, instance, latency, rows or scanned keys, and the processing/wait fields needed for that comparison. Select contrasting fast/slow, different-plan, scan, or wait examples based on the purpose, not an arbitrary number of the slowest rows. Do not erase a useful faster control. Missing fields are unavailable, not zero; cumulative task time is not elapsed query time. An empty result states only its exact queried scope and limitation. You may identify relevance, group observations, calculate descriptive statistics, and select representative contrasts. Preserve contrary facts and important missing fields. Do not decide a root cause, prove target identity, assign Scenario status, choose mitigation, or change human ownership; those judgments remain with the Scenario Diagnostic Agent.