# Clinic Cluster Name Resolution

<!-- auto-oncall-optimization-record
{
  "schemaVersion": "auto-oncall-optimization-record-v1",
  "optimizationId": "clinic-cluster-name-resolution-2026-08-18",
  "problems": [
    {
      "problemId": "cloud-cluster-name-rejected-without-cluster-id",
      "summary": "ST-2898 supplied one Cloud org ID and two explicit cluster aliases, but deterministic classification required clusterId and stopped as human_required before Clinic target resolution or evidence acquisition.",
      "status": "optimized_verified",
      "applicability": "TiDB Cloud read-only diagnostics with an exact orgId, no typed clusterId, and one to three explicit customer-visible cluster names or aliases that can be uniquely resolved inside a bounded same-org Clinic inventory.",
      "issueKeys": ["ST-2898"],
      "sourceRefs": [
        "https://tidb.atlassian.net/browse/ST-2898#problem:cloud-cluster-name-rejected-without-cluster-id"
      ],
      "signalTextIncludesAny": [
        "cloud_target:incomplete",
        "missing cloud_cluster_id despite explicit cluster name",
        "cluster alias should resolve through clinic"
      ],
      "observedThrough": "2026-08-18",
      "effectiveAt": "2026-08-18T11:22:45+08:00",
      "verifiedAt": "2026-08-18T11:42:35+08:00",
      "attemptedAction": "Treat orgId plus an explicit Cloud cluster alias as a complete Clinic routing input, load a bounded same-org cluster inventory, let the Scenario Router resolve every explicit target, validate exact candidate membership, execute the same bounded plan across the resolved target set, and preserve bounded per-target metric facts plus partial-target evidence in the Evidence handoff.",
      "evidenceUrl": "https://tidb.atlassian.net/rest/servicedeskapi/request/7963983/comment/23612999"
    }
  ]
}
-->

- Owner: Scenario Classifier, Scenario Router target resolution, and Clinic
  Provider Executor
- Source: `ST-2898`
- Implementation status: merged in `tidbcloud/aisupport#964` and deployed to
  staging as image `fb50a4a7a212607720b8241141b68292cba98c78`
- Effective status: `optimized_verified`

## Bounded problem

ST-2898 has the typed Cloud `orgId` and explicitly names North America SaaS03
and SaaS05, but it has no typed `clusterId`. The deterministic classifier
previously rewrote that input to `human_required`, removed the Clinic route,
and emitted `missingKeys=["cloud_cluster_id"]`. This stopped before Clinic even
though the exact org inventory uniquely contains both named targets.

## Intended change

- Classify an exact Cloud `orgId` plus an explicit cluster name or alias as an
  executable Clinic route without treating `cloud_cluster_id` as customer-owned
  missing context.
- Load at most 100 non-deleted cluster metadata candidates from that exact org.
- Let the Scenario Router resolve every explicit ticket target to exact
  candidate names, with at most three targets. Any missing or ambiguous target
  yields a bounded internal `human_required` handoff without a Provider query.
- Map the selected names back to exact same-org cluster IDs in deterministic
  code and apply each Evidence Agent plan operation to all resolved targets.
- Preserve successful target facts and an explicit gap when only part of a
  multi-target query succeeds.

## Verification status

Local contract tests cover ST-2898 classification, bounded Clinic inventory,
two-target Router validation, same-org enforcement, query fan-out, bounded
per-target metric facts, and partial target materialization.

A local `mode=read` E2E on 2026-08-18 completed with HTTP 200 as run
`8b18d268-0f1b-4594-8652-d2e0edeea9c4`. It classified ST-2898 as
`cluster_runtime_issue` with Clinic and no missing keys, resolved SaaS03 and
SaaS05 to their exact same-org cluster IDs, and completed one evidence round
for both targets. The capacity scenario finished `confirmed` and the region
movement/scale scenario finished `ruled_out`; bounded highest- and
lowest-series labels reached the diagnostic handoff. The final
`human_required` decision was retained only for production-capacity approval
and Support follow-up, not for missing target identity or absent Provider
facts. Read mode requested no Jira, database, evaluation, or Feishu
publication.

The source change was merged as `tidbcloud/aisupport#964`, and
`tidbcloud/app-delivery#77493` deployed image
`fb50a4a7a212607720b8241141b68292cba98c78`. The live Deployment observed that
generation and its replacement Pod was Ready with zero restarts.

A staging `mode=write` replay completed on 2026-08-18 as run
`a2f21589-9a7e-418f-8a14-e5a88562109d`, persisted DB run `150084`, with Clinic
evidence acquisition and response generation both complete. The current exact
org inventory uniquely maps SaaS03 to cluster `10754652599988043412` and
SaaS05 to cluster `10698648422638660035`. The deployed run issued the same 11
capacity queries for both resolved targets: all 22 Clinic HTTP attempts returned
200, and the final reply reported distinct utilization and headroom ranges for
SaaS03 and SaaS05.

The final decision remains `human_required`, but only because the escalated
ticket has continuing capacity risk that requires Support trend follow-up and
cannot authorize or promise a production capacity change. It is no longer
caused by a missing cluster ID, target-resolution failure, or absent Provider
evidence.

Write publication succeeded without errors. It persisted the analysis,
evaluation, and dashboard projection, then wrote Jira internal comment
`23612999`. Direct readback of that exact comment confirmed `public=false`,
author `TiDB Support Assistant`, and an exact body match with the replay result.

## Unresolved gaps

No unresolved gap remains for this bounded target-resolution problem. Missing
write, compaction, and snapshot telemetry remains an explicit case-level
diagnostic limitation and is not evidence that either cluster target failed to
resolve.

## Next validation action

Monitor later tickets with an exact org ID plus cluster aliases for ambiguous or
missing inventory matches; treat any recurrence of missing-ID short-circuiting
as a regression of this verified problem.