---
name: review-scenario-yaml
description: Review changed TiDB Cloud E2E scenario YAML test cases in APITestGen for correctness, portability, security, resource lifecycle, assertions, retries, placeholders, and runner compatibility. Use when asked to review, inspect, audit, or validate git-diff changes under scenario_testcases/*.yaml, including new or modified Dedicated, BYOC, Essential V2, regional, or provider-specific scenarios.
---

# Review TiDB Cloud E2E Scenario YAML

Review only; do not edit test cases unless the user explicitly requests fixes.

## Collect the review scope

1. Run `git status --short`, `git log -1 --oneline`, and `git diff --stat` from the APITestGen repository root.
2. Use the user-specified base ref when present. Otherwise use `HEAD` for local uncommitted work, or the merge base with the default remote branch when reviewing a feature branch.
3. When the caller supplies explicit YAML paths, restrict findings to those files. Otherwise capture the complete YAML diff with `git diff <base> -- 'scenario_testcases/*.yaml'` and include staged changes automatically by diffing the worktree against `<base>`.
4. Without an explicit file list, add untracked files from `git ls-files --others --exclude-standard -- 'scenario_testcases/*.yaml'`; `git diff` does not include them.
5. Ignore unchanged YAML except when comparing a target case with its closest API-tier/provider variant.

Run the deterministic checks before semantic review:

```sh
ruby --disable-gems skills/review-scenario-yaml/scripts/check_changed_scenarios.rb \
  --base <base> \
  --file scenario_testcases/example.yaml
```

Use `--base HEAD` for ordinary local changes. Repeat `--file` for every caller-specified target, or omit `--file` to review all changed scenario YAML. The checker exits nonzero when it reports findings; a zero exit means only that its deterministic gate found none. Treat script output as evidence, not as the complete review.

## Load review evidence

Read these sources before reporting findings:

1. Read `README.md` for the current schema and runner behavior.
2. Read the canonical workspace rules at `../docs/refs/TiDB Cloud E2E case review rules.md` when available. Otherwise read [baseline-review-rules.md](references/baseline-review-rules.md).
3. Always read [supplemental-review-rules.md](references/supplemental-review-rules.md). It records code-derived checks and recurring defects from historical pull requests.
4. Inspect runner files cited by a rule when the changed YAML depends on that behavior. Resolve `$TIDB_MANAGEMENT_SERVICE_DIR`, then an available `../tidb-management-service` checkout, then the pinned official [`tidb-management-service@ff5c78ac9`](https://github.com/tidbcloud/tidb-management-service/tree/ff5c78ac952849735b14a93ecabcceec4933ea33) source verified on 2026-07-15. Do not require a sibling checkout; prefer a current requested revision over stale documentation.
5. For an unfamiliar file, operation, or API behavior, search repository history with `gh pr list --state all --search '<filename-or-operation>'` and inspect relevant conversations with `gh pr view`. Add historical evidence only when a comment or follow-up change demonstrates a concrete defect.

## Review the diff

Check each changed step and its lifecycle context:

- Validate YAML plus embedded `request`, `expect`, and `save` JSON.
- Trace every produced placeholder to later consumers; verify path, body, command, CEL, and save contexts separately.
- Verify steps are in executable lifecycle order, asynchronous transitions are polled, and destructive or cleanup steps cover every created resource.
- Match API tier, base path, host, auth mode, provider, region, storage URI, identity format, headers, request fields, response casing, and sibling variants.
- Require meaningful status/exit and CEL assertions. Confirm response paths and status codes against the operation being exercised.
- Evaluate retry purpose and worst-case delay. Flag tight retry loops, excessive waits, and readiness checks with no retry window.
- Reject committed secrets and environment-specific resource IDs when placeholders or workflow inputs should be used.
- Check resource names, minimal test specifications, query scoping, cleanup safety, and parallel-run isolation.
- Distinguish definite defects from questions. Report a finding only when the diff and a cited rule, runner behavior, API contract, or historical defect provide concrete evidence.

## Assign priority

- `P0`: exposed credential or a change likely to cause destructive cross-environment impact.
- `P1`: definite parse/runtime failure, wrong endpoint/provider/auth/expectation, broken dependency, or resource leak.
- `P2`: material flakiness, excessive cost/time, weak coverage, unsafe retry behavior, or incomplete isolation.
- `P3`: maintainability, naming, diff-scope, or consistency issue with low immediate execution risk.

## Report findings

Sort findings by priority, then file and line. Use one block per distinct issue and include all required fields exactly:

```markdown
### [P1] Short finding title

- source: `scenario_testcases/example.yaml:123` (`Operation_ID`, order `4.5`)
- 优先级: P1
- 问题点: Explain the concrete failure mode and when it occurs.
- 修改建议: Give the smallest actionable correction.
- 参考: `README.md#placeholder-rules`; `../tidb-management-service/.../actionbuilder.go:293-316`; https://github.com/tidbcloud/APITestGen/pull/114#discussion_r2533022128
```

Use `source` for the changed YAML location. Use `参考` for the rule, runner code, comparable case, API contract, or historical PR that proves the issue. Do not cite a generic document without naming the relevant section.
Write the explanation and suggestion in the user's language while preserving the field labels exactly.

If no findings remain, write `未发现需要修改的问题`, list reviewed files and checks performed, and state any validation gap such as unavailable API documentation or an unexecuted live workflow.