name: pr-review-release description: PR Code Review 評估與完整發布流程。當使用者提到 code review、PR 審查、review 建議處理、merge PR、發布版本、release、squash merge、版本標籤時自動啟用。包含評估 Copilot/人工 review 建議、程式碼修正、Git 合併、語意化版本更新、CHANGELOG、打包發布的完整工作流程。PR review evaluation and release workflow for processing code review comments, merging PRs, semantic versioning, and publishing releases. metadata: author: singular-blockly version: '1.6.0' category: release license: Apache-2.0

PR Code Review 評估與發布流程 PR Review & Release Workflow

以專案開發者角度評估 PR Code Review，並執行完整發布流程。 Evaluate PR code reviews from a project developer's perspective and execute the complete release workflow.

適用情境 When to Use

需要處理 PR 上的 code review 建議
評估 Copilot review 或人工審查意見
合併 PR 後需要發布新版本
執行完整的發布流程（版本號、CHANGELOG、標籤、Release）
需要 squash merge 並清理已合併的分支
定期清理已合併到 master 的舊本地分支

工作流程 Workflow

Phase 0: 等待 Copilot Review（必須）Wait for Copilot Review (REQUIRED)

⚠️ 阻塞型步驟：此步驟必須完成才能進入 Code Review 評估階段。

💡 Copilot Code Review 已在 GitHub 倉庫設定中配置為自動觸發，無需手動請求。

方法 A：直接使用 gh CLI（推薦）

直接使用 gh CLI 查詢最可靠，避免 PowerShell 跳脫問題。

查詢 Review 狀態

# 查詢 PR 的所有 reviews（JSON 陣列）
gh pr view {PR_NUMBER} --json reviews --jq ".reviews"

# 過濾 Copilot review（看 author.login）
# Copilot reviewer login: "copilot-pull-request-reviewer" 或 "Copilot"

回傳的 JSON 中找 author.login 為 copilot-pull-request-reviewer 的項目，取最後一筆的 state 欄位。完成狀態為 COMMENTED、APPROVED 或 CHANGES_REQUESTED。

取得 Line Comments（逐行建議）

# 先取得 repo 全名
$repo = gh repo view --json nameWithOwner --jq ".nameWithOwner"

# 取得 Copilot 的 line comments
gh api "repos/$repo/pulls/{PR_NUMBER}/comments" --jq '.[] | select(.user.login == "copilot-pull-request-reviewer" or .user.login == "Copilot") | {path, line, body}'

Agent 整合用法（必須執行）

// 步驟 1: 查詢 PR review 狀態
run_in_terminal({
  command: 'gh pr view {PR_NUMBER} --json reviews --jq ".reviews"',
  isBackground: false,
  goal: '查詢 Copilot Review 狀態',
});
// 步驟 2: 解析 JSON 輸出，檢查是否有 copilot-pull-request-reviewer
// 步驟 3: 若尚未出現，等待 60 秒後重試（最多 30 分鐘）
// 步驟 4: Review 完成後，取得 line comments
run_in_terminal({
  command: '$repo = gh repo view --json nameWithOwner --jq ".nameWithOwner"; gh api "repos/$repo/pulls/{PR_NUMBER}/comments" --jq \'[.[] | select(.user.login == "copilot-pull-request-reviewer" or .user.login == "Copilot") | {path, line, body, id}]\'',
  isBackground: false,
  goal: '取得 Copilot line comments',
});

若 Copilot Review 未自動觸發

使用 MCP 工具手動請求：

mcp_github_request_copilot_review({
  owner: "{OWNER}",
  repo: "{REPO}",
  pullNumber: {PR_NUMBER}
});

方法 B：使用輪詢腳本（背景執行）

若偏好背景輪詢，可使用已修復的腳本（v2.0.0）：

# 背景模式執行
.\.github\skills\pr-review-release\scripts\poll-review.ps1

# 自訂參數
.\.github\skills\pr-review-release\scripts\poll-review.ps1 -PrNumber 123 -TimeoutMinutes 60 -PollIntervalSeconds 30

腳本行為：

每 60 秒查詢一次 Copilot review 狀態
使用 PowerShell 原生 Where-Object 過濾（避免 jq 跳脫問題）
動態取得 owner/repo（避免文字佔位符問題）
COMMENTED / APPROVED：exit 0 | CHANGES_REQUESTED：exit 1 | 逾時：exit 2

Phase 1: Code Review 評估 Review Evaluation

讀取 PR Review 評論

# 取得目前分支的 PR 資訊
gh pr view --json reviews,comments,number

# 取得詳細的 review 評論
gh pr view --json reviews --jq '.reviews[] | {author: .author.login, state: .state, body: .body}'

評估每條建議，以專業開發者角度判斷：

判斷結果	標準	範例
✅ 採納	真正有價值、能改善程式碼品質	修復潛在 bug、改善效能、增強可讀性
❌ 忽略	基於錯誤理解或不符合專案架構	過度工程化、不了解上下文、風格偏好

記錄評估結果，清楚說明每條建議的採納/忽略理由

Phase 2: 程式碼修正 Code Fixes

若有採納的建議：

修正程式碼
- 根據採納的建議進行修改
- 確保符合專案規範（參考 copilot-instructions.md）

驗證修正

# 執行測試
npm test

# 執行 lint
npm run lint

Phase 3: 程式碼簡化（必須）Code Simplification (REQUIRED)

⚠️ 阻塞型步驟：此步驟必須完成才能進入 Git 操作階段。

修正 Code Review 建議後，必須使用 code-simplifier 技能進行程式碼簡化：

執行程式碼簡化檢查

# 取得本次變更的檔案
git diff --name-only origin/master | grep -E '\.(ts|js)$'

強制簡化流程
- 閱讀 code-simplifier 技能文件
- 對所有變更的 TypeScript/JavaScript 檔案執行簡化
- 確保遵循專案的 coding standards
簡化完成標準
- 減少不必要的巢狀結構
- 移除冗餘程式碼和抽象
- 變數和函式命名清晰
- 無描述顯而易見程式碼的註解
- 測試通過且功能不變

提交簡化變更

git add .
git commit -m "refactor: simplify code before release"

💡 Agent 整合：輸入「簡化程式碼」、「refactor」或 @code-simplifier 觸發技能。

❌ 禁止跳過：未完成程式碼簡化不得進入 Phase 4。

Phase 4: Git 操作 Git Operations

提交變更（若有修正）

git add .
git commit -m "fix: address code review feedback"

推送並合併

# 推送到功能分支
git push origin HEAD

# Squash merge PR（--delete-branch 會自動刪除遠端分支）
gh pr merge --squash --delete-branch

Agent 使用 MCP 工具合併時：mcp_github_merge_pull_request 不會自動刪除遠端分支，必須在步驟 4 手動刪除。

同步主分支
```
git checkout master
git pull origin master
git status -sb
```
確認主分支已同步且工作目錄乾淨，再進入發布流程。

清理已合併分支 Branch Cleanup

# 刪除遠端功能分支（若未被 --delete-branch 自動刪除）
git push origin --delete feature-branch-name

# 更新遠端分支資訊，移除已刪除的遠端分支
git fetch --prune

# 刪除本地功能分支（若尚未刪除）
git branch -d feature-branch-name

# 批次刪除所有已合併到 master 的本地分支
git branch --merged master | grep -v "master" | xargs -r git branch -d

# 列出並清理標記為 [gone] 的分支（遠端已刪除）
git branch -vv | grep ': gone]' | awk '{print $1}' | xargs -r git branch -d

清理 Worktrees（如有使用）

# 列出所有 worktrees
git worktree list

# 移除關聯已刪除分支的 worktree
git worktree remove path/to/worktree

Phase 5: 發布流程 Release Process

按照專案憲法（constitution.md）或發布規範執行：

5.1 版本管理 Version Management

決定版本號（遵循語意化版本）
- patch: Bug 修復、小改進 (0.0.X)
- minor: 新功能、向後相容 (0.X.0)
- major: 破壞性變更 (X.0.0)

更新版本號（避免自動建立輕量 tag）

npm version patch --no-git-tag-version  # 或 minor / major

更新 CHANGELOG.md
- 新增雙語條目（中英文）
- 格式遵循 Keep a Changelog

提交版本更新

git add package.json package-lock.json CHANGELOG.md
git commit -m "chore(release): 發布版本 {VERSION}"

5.2 品質驗證 Quality Verification

# 完整測試
npm test

# Lint 檢查
npm run lint

# 建置驗證
npm run compile

5.3 建置與打包 Build & Package

# 生產建置
npm run package

# 打包 VSIX（若為 VS Code 擴充功能）
npx @vscode/vsce package

5.4 Git 標籤 Git Tagging

⚠️ 重要：所有版本標籤必須使用 Annotated Tags（-a 參數）

Annotated tags 包含建立者、日期、訊息等元資料，是正式發布的標準做法。

# 建立 Annotated Tag（必須使用 -a 參數）
git tag -a v{VERSION} -m "Release v{VERSION}"

# 推送標籤到遠端
git push origin v{VERSION}

# 驗證標籤類型（應顯示 tag 而非 commit）
git cat-file -t v{VERSION}

❌ 禁止使用 Lightweight Tags：

# 錯誤示範 - 不要這樣做！
git tag v{VERSION}  # 缺少 -a 參數，會建立 lightweight tag

5.5 GitHub Release（必要步驟 REQUIRED）

⚠️ 重要：此步驟不可省略！Git tag 不等於 GitHub Release。

注意：Release 公告容易因 CLI 字串轉義導致跑版，建議使用臨時檔（release-notes.md）輸入。

@'
## ✨ New Features | 新功能

### Feature Name | 功能名稱
- English description | 中文說明

## 🐛 Bug Fixes | 修復
- Fixed issue | 修正問題

## 📦 Download | 下載
- **VSIX**: singular-blockly-{VERSION}.vsix

---
**Full Changelog | 完整變更日誌**: https://github.com/{owner}/{repo}/blob/master/CHANGELOG.md
'@ | Set-Content -Path "release-notes.md" -Encoding UTF8

gh release create v{VERSION} -t "v{VERSION}" -F release-notes.md ./singular-blockly-{VERSION}.vsix

Remove-Item -Force release-notes.md

Release 版面檢核與修正：

gh release view v{VERSION} --json body
gh release view v{VERSION} --web

若格式跑掉，修正 release-notes.md 後重新更新：

gh release edit v{VERSION} -F release-notes.md

5.6 清理 Cleanup

# 移除 VSIX 安裝包（必須執行！）
Remove-Item -Force singular-blockly-{VERSION}.vsix

# 移除暫時發布說明檔（若未在 5.5 步驟中移除）
Remove-Item -Force release-notes.md -ErrorAction SilentlyContinue

# 驗證發布連結可存取
gh release view v{VERSION} --web

⚠️ 必須移除 VSIX：VSIX 是建置產物，不應留在工作目錄中。GitHub Release 已附加此檔案，本地保留無意義且會造成混亂。

檢查清單 Checklist

等待 Review 階段（阻塞型）

使用 gh pr view 查詢 Copilot Review 狀態（或使用輪詢腳本）
Review 狀態已確認（COMMENTED / APPROVED / CHANGES_REQUESTED）
已取得 line comments（gh api repos/{owner}/{repo}/pulls/{n}/comments）

❌ 禁止跳過：未取得 Copilot Review 結果不得進入 Phase 1。

Code Review 階段

讀取所有 PR review 評論
評估每條建議並記錄理由
完成採納建議的程式碼修正
測試通過

程式碼簡化階段（阻塞型）

已識別所有變更的 TS/JS 檔案
已執行 code-simplifier 技能
無不必要的巢狀結構
無冗餘程式碼和抽象
變數和函式命名清晰
無描述顯而易見程式碼的註解
測試通過且功能不變
簡化變更已提交

Git 操作階段

變更已提交並推送
PR 已 squash merge
主分支已同步
遠端功能分支已刪除（git push origin --delete 或 --delete-branch）
本地功能分支已刪除（git branch -d）
已清理其他舊的已合併分支

發布階段

輸出格式 Output Format

完成後提供執行摘要：

## 執行摘要 Execution Summary

| 項目             | 狀態                            |
| ---------------- | ------------------------------- |
| Code Review 評估 | ✅ 完成（採納 X 條，忽略 Y 條） |
| 程式碼修正       | ✅/⏭️ 完成/無需修正             |
| PR 合併          | ✅ Squash merged                |
| 版本更新         | ✅ vX.Y.Z                       |
| 發布             | ✅ 完成                         |

### 變更檔案 Changed Files

- `package.json`
- `CHANGELOG.md`
- ...

### 發布連結 Release Link

https://github.com/{owner}/{repo}/releases/tag/v{VERSION}

pr-review-release

SKILL.md