# Write Workload Gate Order

<!-- auto-oncall-optimization-record
{
  "schemaVersion": "auto-oncall-optimization-record-v1",
  "optimizationId": "write-workload-gate-order-2026-07-27",
  "problems": [
    {
      "problemId": "write-attribution-mechanism-checks-starve-workload-gate",
      "summary": "A write-path diagnosis with required workload attribution can spend its initial turn on repeated or optional mechanism checks, skip provider TopSQL and Slow Query surfaces, and ask the customer for DML that the provider could have investigated.",
      "status": "candidate",
      "issueKeys": ["APID-29194"],
      "sourceRefs": [
        "https://tidb.atlassian.net/browse/APID-29194#problem:diagnostic_regression:mechanism-checks-starve-workload-gate"
      ],
      "signalTextIncludesAny": [
        "mechanism checks consume workload attribution budget",
        "topsql skipped before asking customer for dml",
        "generic commit returned without write-specific slow query",
        "repeated scheduler checks before workload gate"
      ],
      "observedThrough": "2026-07-27",
      "effectiveAt": null,
      "verifiedAt": null,
      "attemptedAction": "For required workload attribution or transaction shape, allow at most three non-duplicate high-value mechanism checks before mandatory selected-instance TopSQL, forbid optional counterpart and ratio expansion before that gate, and require one narrow write-specific Slow Query lookup after a generic Commit or Prewrite result before requesting DML from the customer.",
      "evidenceUrl": null
    }
  ]
}
-->

- Optimization ID: `write-workload-gate-order-2026-07-27`
- Owner: auto-oncall-services
- Source reference: `APID-29194`
- Implementation status: local candidate; not deployed
- Effective status: `candidate`

## Bounded problem

The workload and transaction objective gates were already required, but their
provider execution order was not hard. The agent could keep refining an
already-sufficient mechanism until the initial-turn budget was consumed, then
request originating DML from the customer without trying TopSQL or Slow Query.

This record owns only that ordering problem. It does not claim that the
Commit/Prewrite mechanism is wrong, that compact provider evidence regressed,
or that every remaining causal gap in the ticket is resolved.

## Regression evidence

Historical-cutoff replay `25755f4a-4f75-4537-b4e9-3732a7dfb3fe` completed on
2026-07-27 with compact provider handling active. Readiness was followed by
five mechanism-oriented queries:

1. broad TiKV scheduler command P99;
2. the same scheduler P99 on the affected store;
3. affected-store latch wait P99;
4. optional TiDB commit transaction P99;
5. an additional scheduler-to-latch ratio.

The replay then ran zero TopSQL and zero Slow Query queries and requested DML
and transaction details from the customer. This is direct branch-local
regression evidence for the problem signal. It is not post-fix verification.

A later replay, `f1322bef-da28-49d7-ac16-fc431bafb43a`, completed at
`2026-07-27T05:53:03.528Z`. It did reach TopSQL and one Slow Query, so it no
longer reproduced the original complete workload-surface skip. However, it
still used a failed `--window 10` TopSQL attempt before retrying, and it spent
the unique Slow Query on a low-confidence INSERT Digest. The result therefore
does not verify this optimization and exposes a separate candidate-ranking
problem recorded by `write-workload-candidate-priority-2026-07-27`.

## Candidate change

For required workload attribution or transaction shape:

- run readiness at most once and exclude it from the diagnostic check count;
- allow at most three high-value, non-duplicate mechanism checks before
  TopSQL, using fewer when customer evidence already identifies the affected
  instance or mechanism;
- force selected single-instance TopSQL before optional TiDB counterparts,
  repeated scheduler checks, extra aligned ratios, or lower-layer expansion;
- when TopSQL returns generic `COMMIT` or Prewrite, force the one post-TopSQL
  refinement to be a narrow write-specific Slow Query lookup for originating
  DML; when a related business table is visible, filter with
  `--text <business table>` and order by `write_keys`;
- do not request DML from the customer until those provider workload surfaces
  return an exact bounded failure.

## Branch-local acceptance evidence

Read-only historical replay `f79d1126-2a24-46ea-b1d8-f0a0a949a735`
returned HTTP 200 in 353.271 seconds and followed the required order:

1. readiness;
2. scheduler command P99;
3. latch P99;
4. one selected TiKV TopSQL Top 10 query using literal `--window 10s`;
5. one table-text Slow Query.

The chain used two non-duplicate mechanism checks before the mandatory
workload surface, did not run optional counterparts or ratios first, and did
not fall back to broad TiDB TopSQL or Statements after generic transaction
wrappers appeared. The Slow Query identified the originating UPDATE and its
68,000-key transaction shape, and the final accepted output was rated
`ai_better`.

This satisfies the branch-local order criterion but does not make the
candidate effective in an auto-oncall runtime. The status therefore remains
`candidate`.

## Unresolved gaps

- The stricter order is only a local candidate.
- The change is not effective in staging or production.
- A selected TiKV does not automatically identify a TiDB request path unless
  the screenshot, provider metadata, or another direct mapping exposes it.
  Missing mapping must be recorded as a bounded provider limitation without
  skipping the available TiKV TopSQL surface.
- No Jira internal comment has been refreshed.

## Next validation action

Publish the candidate to staging through the normal rollout path and rerun the
same historical cutoff through the rendered pod. Confirm the live trace keeps
readiness to one call, uses no more than three non-duplicate pre-TopSQL
mechanism checks, reaches the selected-instance TopSQL and write-specific Slow
Query before any customer DML request, and retains the conservative safety
boundary.