---
name: alibabacloud-migration-cas-cutover-review
description: >
  自动审查应用迁云、大数据搬栈等场景的割接手册（.xlsx），
  围绕 5 大核心维度 Review：停机公告、切流方式（阻流层）、
  源端数据库只读与会话管理、阿里云应用重启策略、回滚决策条件。
  默认仅审查「割接执行步骤」与「回滚步骤」两个 Sheet
  （CheckList / 域名清单 / 数据迁移需 --sheets 打开），
  输出「重点确认项 + 需关注项」两段式 Markdown / JSON 报告（含评分与风险等级）。
  当用户给出割接手册 / 割接方案 / 割接计划 / cutover plan 的 xlsx，
  或说"审查割接手册"、"review 割接方案"、"评估割接风险"、"检查回滚方案"、
  "割接 checklist 评审"、"看看这个割接方案有什么问题"时触发。
  以下情形同样由本 skill 处理，禁止自行写脚本解析 Excel：
  要列出 / 查看手册里有哪些 Sheet、工作表、页签名称用 --list-sheets；
  分批割接（含用户显式指定过程 Sheet / 回滚 Sheet 名称）用 --scenario batch
  配合 --process-sheet / --rollback-sheet；全量割接 / 一次性切流用 --scenario full；
  场景不确定或属纯 DNS 切换 / 域名切换 / 配置变更等其他类型用 --scenario other；
  未给路径时先用 find / ls 定位文件再审查。
  不适用于：MongoDB / MySQL / Redis 等数据迁移任务配置、
  非结构化文档（Word / PDF）、英文关键词主导的手册、业务语义级深度评审。
  纯 DNS 方案审查深度有限（仅通告、回滚决策等基本维度）。
  本 skill 仅做结构匹配与关键词检测，不理解业务语义，评分仅供参考。
  适用于任意支持本地 shell 执行的 Agent 平台（Qoder / Claude Code 等）。
---

# Cutover Manual Review Skill v4.4

Based on the guide "Dissecting Cloud Migration - Cutover Plan Review Guide", this skill automatically reviews the completeness and standardization of cutover manuals (.xlsx), identifies potential risks, and provides remediation recommendations. It applies to cutover scenarios such as application cloud migration and big-data stack migration.

> This skill works on any Agent platform that supports local shell execution (Qoder / Claude Code, etc.).
> v4.0 refactor: reorganized around 5 core review dimensions (maintenance notice, traffic-switching method, source-database read-only, Alibaba Cloud application restart, rollback decision conditions), while preserving the v3.3 checks for message middleware, scheduled jobs, target-side initial state, service restart strategy, Nginx configuration changes, big-data consumption links, and process consistency.
> v4.1 additions: based on real-world retrospectives, six core-risk checks were added for the full-cutover scenario (remove maintenance notice action, source-database read-only, OSS mirror back-to-source, dedicated-line switch timing, database read-write recovery method, traffic recovery plan), corresponding to script checks full_2_7 ~ full_2_12.
> v4.2 additions: an interactive flow to **confirm the Sheet mapping with the customer first**, then run the review. Explicitly specify `--checklist-sheet / --process-sheet / --rollback-sheet / --domains-sheet / --data-migration-sheet` to avoid missed detections caused by fuzzy matching. It also improves header-row detection (among the first few rows, pick the row hitting the most header keywords as the header, skipping a first row that contains only a single title cell such as "Cutover Steps" or "CheckList"), fixing the past problem where the whole cutover-process Sheet was missed because the first row was treated as the header (typical case: the "Production Environment Cutover Process" Sheet in the Shenxin Zhimei 0820 manual).
> v4.3 changes (**narrowed review scope + report restructure**):
> 1. **Only two Sheets are reviewed by default**: "Cutover Execution Steps" (process) and "Rollback Steps" (rollback). CheckList / domain list / data migration **no longer participate by default** in analysis, keyword scanning, or scoring; open them explicitly with `--sheets` when needed.
> 2. **Keyword scanning scope narrowed accordingly**: the global keyword scan only reads the Sheets actually under review, preventing text in non-reviewed Sheets from causing false hits that mask real risks. The report appendix outputs the `keyword scan scope` for traceability.
> 3. **Dynamic weight normalization**: only the dimensions actually under review are counted and normalized into the weights (`overall_score = Σ(score×w) / Σw`), so placeholder 50-point dimensions no longer pollute the total. In narrow-scope mode the three dimensions that depend on CheckList content (owners / times / monitoring items) — "monitoring & verification", "resource configuration", "organizational assurance" — do not participate in scoring, avoiding penalizing them for "missing" content.
> 4. **Report restructured into two sections**: "I. Key Items to Confirm" (CRITICAL + HIGH) and "II. Items to Note" (MEDIUM + LOW), each listing the issue title, the specific problem, and the remediation suggestion, removing redundant tables and sections.
>
> v4.3.1 changes (**Sheet auto-recognition enhancement**): the synonym table was supplemented with common real-world manual names (cutover plan / cutover steps / cutover process / implementation steps / operation manual / switch process / rollback plan / rollback steps / fallback plan, etc.); fuzzy matching changed from "first dictionary-order hit" to **longest-hit-first**, and a new `SHEET_NAME_EXCLUSIONS` exclusion list was added (a Sheet containing "rollback / fallback / cutback / rollback" is never judged as process), fixing the past problem where "rollback process" was grabbed by the process generic pattern "process", causing rollback steps to be recognized as 0. Therefore most manuals no longer need explicit `--process-sheet / --rollback-sheet`; the explicit parameters degrade to "a correction means when auto-recognition is wrong".
>
> v4.4 changes (**issue aggregation + conditional suppression, report readability restructure**):
> 1. **Issue aggregation layer (`ISSUE_TOPICS`)**: a non-intrusive post-processing step added between collecting `self.issues` and rendering the report. The same underlying risk (e.g., "source-database read-only" hit separately by 6 checks) is merged into one entry, taking the highest severity within the group, and echoing the original hit items with "hit checks: N (…)" at the end of the entry — both de-duplicating and preserving traceability. Total risk entries compressed from 44 to 16.
> 2. **Topic matching uses short identifier phrases**: `_match_topic` only matches on `category` + `_issue_key_phrase(message)` (the content inside `[square brackets]`, otherwise the first sentence), no longer matching the full message that contains a lengthy `check_logic`, fixing past **topic-bleed** issues where "maintenance notice" swallowed "traffic recovery plan" and "traffic switching" swallowed rollback decision / source read-only. Note that `ISSUE_TOPICS` is **order-sensitive** (first hit wins): `topic_redis` / `topic_aliyun_db` must precede `topic_src_readonly`, which contains the bare keyword "read-only".
> 3. **Conditional suppression (`SUPPRESSION_RULES`)**: when a `when_any` keyword hits the full text of the Sheets actually under review, the reminders matched by `only_messages_any` are suppressed. Typical scenario: the manual already contains an "Alibaba Cloud application startup" action, which means the target-side application is shut down before the cutover and there is no risk of being written dirty in advance, so the group of reminders "Alibaba Cloud database read-only in advance / restore read-write during cutover" is exempted; similarly the keyword-based false positive of "missing service restart node" is exempted. Exempted items are echoed in the report appendix "Suppressed Items" as "N item(s) exempted — <reason>".
> 4. **Cap on key items to confirm**: only topics with `core: True` and severity CRITICAL / HIGH enter "I. Key Items to Confirm", truncated by `MAX_MUST_CONFIRM_ITEMS = 10`; the rest all fall into "II. Items to Note". This prevents the key section from being diluted by dozens of homogeneous reminders.
> 5. **Full-scenario category prefix rewrite (`CATEGORY_PREFIX_REWRITE`)**: in the full-cutover scenario, "Batch Cutover-" is uniformly displayed as "General Cutover-", to avoid users mistakenly thinking the scenario was misidentified.
> 6. **Wording optimization for rollback decision, etc.**: when the manual does not mention rollback decisions, the suggested wording changes to "list a dedicated section of rollback decision basis in the manual (do not mix it into the operation-step table)", and provides two suggested decision points (before traffic is officially forwarded, before DNS switch).
>
> v4.4.3 changes (**turn-completion contract + trigger coverage**):
> 1. **Turn-completion decision table** added under "Command Invocation Convention (MUST)". Ending a turn with a question is now legal in exactly one case — a review was requested, the user wants the Sheet mapping pinned explicitly, and the Sheet names are unknown. A list-only request prints the Sheet list and stops; a user-supplied Sheet name that triggers the fallback warning is reported together with the mapping actually used and the turn finishes; an unknown manual path is located with `find` / `ls`; an unclear scenario falls back to `--scenario other`. Hard rule 5 was reworded accordingly ("let the user decide" removed) because it contradicted this contract and caused turns to hang waiting for a human reply.
> 2. **Trigger coverage strengthened** in the YAML `description`: listing Sheet / worksheet / tab names now routes to `--list-sheets`; batch cutover with explicitly named process / rollback Sheets routes to `--scenario batch` plus `--process-sheet` / `--rollback-sheet`; uncertain scenarios and pure DNS / domain / configuration-change reviews route to `--scenario other`; a missing manual path is located first. An explicit "never hand-roll an Excel-parsing script" instruction was added.

## Core Review Dimensions (v4.0)

The following 5 dimensions are the core focus of cutover-plan review; every review must check each one and output a conclusion:

### Dimension 1: Maintenance Notice

**Check logic**:
- Check whether the cutover manual configures maintenance-notice content.
- If **not configured** → remind the user to configure a maintenance notice and inform users of the maintenance time window.
- If **already configured** → further confirm the mounting method (WeChat mini-program auto-interception / Alipay does not intercept / Nginx mounting) and clarify the deployment location (source / target).

**Keywords**: maintenance notice, maintenance announcement, cutover notice, maintenance notification, mini-program notice, Nginx notice mounting

### Dimension 2: Traffic-Switching Method (Blocking Layer)

**Check logic**:
- Check whether the cutover manual configures a blocking layer.
- If **no blocking layer** and switching only via DNS resolution → remind: DNS resolution is affected by carrier caching, its effective time is uncontrollable, it is affected by Local DNS hijacking and cannot take effect 100%, and there will continually be sporadic traffic hitting the source, causing access exceptions.
- If **there is a blocking layer** → check whether there is a corresponding blocking-function verification item, and remind that the blocking function must be verified in advance.

**Keywords**: blocking layer, blocking, traffic forwarding, DNS switch, DNS effectiveness, Local DNS, traffic interception, sporadic traffic

### Dimension 3: Source-Database Read-Only

**Check logic**:
- If the manual **only stops the application and does not set the database to read-only** → remind: even if the application stops, there may be other requests (scheduled jobs, background services, direct-connect scripts, etc.) writing to the database, causing the increment to be unable to catch up.
- If the manual **sets the database to read-only but does not kill sessions** → remind: sessions must be killed to ensure existing long connections are cleared, otherwise existing connections may still write data.
- Supplementary check: the read-only setting should be at the account level rather than the instance level, and must not affect DTS incremental synchronization.

**Keywords**: database read-only, ReadOnly, kill session, kill session (Chinese), terminate session, long connection, incremental catch-up, account level

### Dimension 4: Alibaba Cloud Application Restart

**Check logic**:
- If the Alibaba Cloud application **has no restart action** → remind: after the Alibaba Cloud database restores read-write, note whether the application reconnects automatically, and suggest verifying the application connection-pool state.
- If the Alibaba Cloud application **has a restart action** → remind: pay attention to application startup time and the interdependencies between different applications, suggest a two-phase startup (verify with a single Pod first, then batch scale-out), and start base services first.

**Keywords**: application restart, service restart, auto-reconnect, reconnect, startup time, service dependency, two-phase startup, Pod, rolling restart

### Dimension 5: Rollback Decision Conditions

**Check logic**:
- If the manual **has no rollback decision conditions** → remind: whether a rollback plan design and rollback contingency preparation have been properly carried out.
- Rollback decision conditions should be independent of operation steps; suggest setting two key decision points: before traffic forwarding (can roll back quickly) / after traffic forwarding (rollback complexity rises significantly).
- After a DNS switch, rollback is generally no longer performed; suggest deferring the DNS switch to the next day.

**Keywords**: rollback decision, rollback condition, rollback contingency, rollback plan, trigger condition, before traffic forwarding, after traffic forwarding, decision point

## Six Core-Risk Checks (added in v4.1, real-world retrospective)

The following 6 items come from real cutover-project retrospectives and are built in as dedicated checks for the full-cutover scenario (script full_2_7 ~ full_2_12); every review must verify each one:

1. **Remove-maintenance-notice action** (CRITICAL): if there is a maintenance notice, there must be a corresponding "remove notice" action. After the blocking layer forwards traffic to Alibaba Cloud, the maintenance notice is usually mounted on the Alibaba Cloud load balancer; when recovering traffic, there must be an action to "switch traffic from the maintenance-notice backend servers back to the formal production application", otherwise users will still see the maintenance page after the cutover completes. Keywords: remove notice, take down notice, remove announcement, restore production backend, switch back to production backend.
2. **Source-database read-only** (CRITICAL): merely closing the traffic entry / blocking cannot achieve no write requests to the database — scheduled jobs, background services, direct-connect scripts, and existing long connections may still write. The source database must be set to read-only (account level, not affecting DTS incremental) and sessions killed. Keywords: source database read-only, source read-only, source library read-only.
3. **OSS mirror back-to-source** (HIGH): when starting OSS incremental migration only during the cutover, you must answer "how long does the incremental catch-up take". A better solution is to configure OSS mirror back-to-source (back-to-source to the source-side object storage) in advance, so uncached objects are automatically fetched back-to-source and no incremental catch-up is needed on cutover day. Keywords: mirror back-to-source, back-to-source rule, OSS back-to-source.
4. **Dedicated-line / network switch timing** (HIGH): network-change actions (switching dedicated line / route) within the cutover window easily extend the cutover downtime. It is recommended to pre-switch and verify the dedicated line in advance, and only do the traffic switch on cutover day; if it must be executed within the window, the duration, verification method, and fallback action must be clarified. Keywords: dedicated-line pre-switch, switch dedicated line in advance, route pre-switch.
5. **Database read-write recovery method** (HIGH): you must clarify whether read-write recovery uses the "whitelist method" or "account-level read-only release" method — the two differ in impact scope and fallback path; after account-level recovery, it is recommended to kill sessions to trigger reconnection. Keywords: read-write recovery method, whitelist recovery, account read-only recovery.
6. **Traffic recovery plan** (CRITICAL): you must clarify the specific path for recovering traffic — switch DNS directly? remove the blocking layer? or switch the load-balancer backend back to the production application? Different methods differ in effective time and rollback-ability, and must be written into the manual with verification steps. Keywords: recover traffic, traffic recovery, release blocking, close blocking layer.

## Security Red Lines

- **Strictly forbid leaking manual data**: all IPs, domains, hostnames, accounts, and business keys in the review report must be desensitized (manual secondary confirmation recommended).
- **Strictly forbid auto-upload**: never upload the cutover manual or the review report to any external service (SkillHub / DingTalk / cloud drive, etc.).
- **Strictly forbid making decisions on behalf of others**: scores and suggestions are for reference only and do not constitute the final decision basis; the cutover may be executed only after passing manual review and an on-site expert review meeting.
- **Strictly forbid modifying the author's files**: except for the review report, do not modify the user-provided cutover-manual source file.
- When the report involves customer cases, desensitize (use expressions like "a certain enterprise"); if `--format json` is enabled, remind the user to store it encrypted.
- **PII is not within this skill's data scope**: within the business definition of a cutover manual, end-user PII such as ID numbers / bank-card numbers / medical-insurance numbers / customers' real names should not appear; the script's desensitization engine only covers ops-level sensitive fields. If a manual is unexpectedly found to carry customer PII, the Agent must note in the termination summary that "the report may contain unrecognized PII; please perform manual desensitization review before external release". See the "Data Scope Declaration" section in [references/ram-policies.md](references/ram-policies.md) for the full statement.

## MCP Tool List

| Chinese name | Tool ID | Purpose |
|--------|---------|------|
| None | — | This skill is a pure local CLI-script type; it does not depend on any MCP tool or external interface, and only executes `scripts/cutover_reviewer.py` via the local Python interpreter. |

**RAM permissions: `required_permissions: []` (no Alibaba Cloud RAM permissions required)** — see [references/ram-policies.md](references/ram-policies.md) for the full statement.

## Prerequisites

- **Runtime**: Python 3.8+
- **Dependency installation**: `pip install openpyxl==3.1.5` (the only third-party dependency)
- **Operating system**: macOS / Linux / Windows all supported
- **Agent platform permission**: local shell execution is required (subprocess invocation of Python)
- **Network**: no internet connection required

See [references/usage-guide.md](references/usage-guide.md) for detailed installation steps.

## Command Invocation Convention (MUST)

The review is always performed by running the bundled script directly in the shell. The following two forms are mandatory and must be reproduced literally:

```bash
python3 scripts/cutover_reviewer.py <manual path> --scenario <full|batch|other> [--process-sheet "<name>"] [--rollback-sheet "<name>"] [--sheets <types>] [-o <output dir>]
```

```bash
python3 scripts/cutover_reviewer.py <manual path> --list-sheets
```

Hard rules:

1. **`python3` plus a relative script path only.** Always invoke the interpreter as `python3` (never `python`, `py`, or a path into a virtualenv). Change the working directory to the skill root first (the directory that contains `SKILL.md`), then invoke exactly `python3 scripts/cutover_reviewer.py`. Never write the script argument as an absolute path, and never substitute a shell variable or command substitution (`$SKILL_DIR/...`, `"$(dirname ...)"`, `${VAR}`) for it — the executed command must literally read `python3 scripts/cutover_reviewer.py`.
2. **Fixed argument order.** The manual path comes immediatel