tc-version-diff

name	tc-version-diff
description	比對兩個 TC 版本（v0.x → v0.y）的差異，產 changelog + 補測清單 + 自動更新 status sheet 的審查紀錄。當使用者提到「TC 版本 diff / TC 升版 / 比對 v0.2 v0.3 / 哪些 TC 要重跑 / 補測清單」，或剛 review 完一份 TC 升版本（看到「v0.3 補 8 條」這種訊息）時觸發。配套：test-review（升版前審）、test-master（升版時擴張）、tc-to-pytest（API TC 升版同步 pytest）。
disable-model-invocation	false
allowed-tools	Read, Grep, Glob, Write, Edit, Bash, mcp__google__readSpreadsheet, mcp__google__getSpreadsheetInfo, mcp__google__writeSpreadsheet
argument-hint	[v_old Sheet/檔] [v_new Sheet/檔] / 或單一 Sheet（自動從 status sheet 找最近兩版）

tc-version-diff

⚙️ 執行前先讀 modules/config-loader.md。 若 mode = markdown-only，跳過 Sheet 操作，純比對兩個 markdown 檔。

適用場景

• ✅ TC 從 v0.2 升 v0.3，要產 changelog
• ✅ Sprint review 後規格變動，TC 要回頭比對影響哪些 row
• ✅ Release 前確認「上次回歸後新增/改動的 TC 有沒有都 cover」
• ✅ Sheet status 分頁的「審查紀錄」區塊要自動寫入版本對照

不適用場景

• ❌ 完全新版（v0.1 first draft）→ 沒前一版可比，用 test-master 從零生
• ❌ 跨功能模組大重組 → 用 test-master 升級流程
• ❌ 純文字錯字修 → 不需要這個 skill，直接改

Phase 1: 取兩版來源

輸入	動作
兩個 Sheet URL	都用 google MCP readSpreadsheet 抓
兩個 markdown 檔	Read 兩份
單一 Sheet → 自動找前一版	從 status 分頁的「審查紀錄」表撈最近兩個 row 的「測試版本」欄
單一模組名 + 版本號	從 tc-index.md（若存在）找 Sheet → Drive revision API 抓兩個快照

Drive revision 抓法依 google MCP 版本而定；如無，互動式請使用者提供 export 的兩個檔。

Phase 2: 建立 ID-key 對照

從兩版各抽出所有 TC row，建 dict：{id: row_data}。 忽略空行、status 分頁。 分 BB / WB 兩個 sheet 分別處理。

Phase 3: 分類差異

類型	判斷	影響
🆕 Added	id 在 v_new 但不在 v_old	補測必跑
🗑️ Removed	id 在 v_old 但不在 v_new	看是否真的不需要了，還是被改 ID
✏️ Modified	id 同但內容變	看哪欄變決定影響
✅ Unchanged	完全相同	已測過免重測

Modified 細分（依「哪欄變」歸類）：

變動欄	影響等級	補測決策
標題 / 備註	🟢 低	不需重測，僅文字
步驟 J	🟡 中	重測（步驟變了）
預期結果 K	🔴 高	必重測（驗收標準變了）
優先度 G	🟡 中	P 升級 → 必跑；P 降級 → 可緩
自動化 L	🟢 低	標 N→Y 不影響跑；標 Y→N 看為什麼
平台 H	🔴 高	平台拓寬要補跑新平台
分類 F	🟡 中	分類重歸位通常不影響跑
前置 I	🟡 中	前置變了要驗環境

Phase 4: 產 changelog

寫到 <repo>/<feature>/tc-changelog-v{old}-v{new}.md：

# TC Changelog · {feature} v0.2 → v0.3

**生成日期**：2026-MM-DD
**對比基準**：BB v0.2 (79 條 / WB v0.2 33 條) → BB v0.3 (90 條 / WB v0.3 43 條)
**淨變動**：+11 BB / +10 WB / 修改 X / 移除 0

## 🆕 Added（補測必跑）

### Black-box (+11)
- BB-{FEATURE}-086 相容：iOS 16 [P1] [iOS]
- BB-{FEATURE}-087 相容：iOS 17 [P1] [iOS]
...

### White-box (+8)
- WB-{FEATURE}-035 步數 sync 未授權 401 防偽 [P0] [Both]
...

## ✏️ Modified（依影響等級）

### 🔴 高影響（**必重測**）
- BB-{FEATURE}-012：預期結果改（從「應該成功」→「200 + schema XXX」）
  - 改動原因：補強斷言（v0.2 review 找到 Critical#3）

### 🟡 中影響
- BB-{FEATURE}-023：步驟 J 改

### 🟢 低影響
- WB-{FEATURE}-005：標題微調

## 🗑️ Removed（0）

無移除。

## 📋 補測清單

| ID | 優先度 | 平台 | 估時 | 自動化 |
|----|-------|------|------|--------|
| BB-{FEATURE}-086 | P1 | iOS | 30 min | N |
| WB-{FEATURE}-035 | P0 | Both | 10 min | Y (pytest) |
...

**總估時**：M 人時（手動）+ K 自動化（CI 跑）

## 🔗 對應 pytest（如有）

如果 WB Modified / Added 有自動化，列出 pytest function 名：
- WB-{FEATURE}-035 → `tests/test_{feature}_api.py::test_steps_sync_unauth_rejected`

→ 跑 `{FEATURE}_API_LIVE=1 pytest -k "test_steps_sync_unauth_rejected or ..."`

Phase 5: 自動寫 status sheet 審查紀錄

僅在 mode != markdown-only 且 google MCP 可用時執行。

如果輸入是 Sheet（不是純 markdown），呼叫 google MCP 寫入 status 分頁的「審查紀錄」表：

2026-MM-DD | tc-version-diff | — | — | — | — | v0.2 → v0.3 升版：+11 BB / +10 WB / Modified X / 補測 N 條

對應 status sheet 的「綜合評分」欄不動（這不是審查，是版本對照）。

Phase 6: Slack 通知

依 slack.notification_rules.tc_version_diff（若未定義則跳過）：

:arrows_counterclockwise: *TC 升版 {feature} v0.2 → v0.3*
:new: +N · :memo: M Modified · :wastebasket: 0 Removed
:exclamation: *補測必跑*：N 條（含 P0 X 條）
:link: changelog: <local path>

⚠️ 安全護欄

• ✅ 只 Write tc-changelog-*.md（純 documentation）
• ✅ 寫 Sheet 限於 status 分頁的「審查紀錄」追加 row
• ❌ 不動 BB / WB 主分頁
• ❌ 不主動跑補測（使用者看 changelog 後決定）
• ❌ 不動 pytest 程式碼（要動用 tc-to-pytest --incremental）

配套整合

完整 升版 workflow：

1. spec 變動 / TC review 找到缺口
   ↓
2. test-master --mode=quick 補新 TC（v0.2 → v0.3）
   ↓
3. /test-review 跑審查（v0.3 自評）
   ↓
4. /tc-version-diff v0.2 v0.3 ← 本 skill
   ↓
5. /tc-to-pytest --incremental 同步 pytest 三件套
   ↓
6. 跑補測清單 + pytest，回填結果
   ↓
7. status sheet 自動更新（含本 skill 寫的版本紀錄）

設定依賴

設定 Key	用途	缺值時行為
mode = markdown-only	全程模式	只比對 .md，不寫 Sheet
slack.notification_rules.tc_version_diff	通知設定	不發 Slack

範例

詳見 examples.md