@routerhub/agent-rules 1.5.86 → 1.5.88

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/package.json +2 -1
  2. package/skills/create-doc/SKILL.md +70 -0
  3. package/skills/create-pr/SKILL.md +95 -0
  4. package/skills/deploy-test/SKILL.md +74 -0
  5. package/skills/figma-to-code/SKILL.md +60 -0
  6. package/skills/github-pr-review/SKILL.md +233 -0
  7. package/skills/github-pr-review/references/coderabbit_parsing.md +206 -0
  8. package/skills/github-pr-review/references/severity_guide.md +222 -0
  9. package/skills/tdd-workflow/SKILL.md +85 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@routerhub/agent-rules",
3
- "version": "1.5.86",
3
+ "version": "1.5.88",
4
4
  "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
5
5
  "main": "AGENTS.base.md",
6
6
  "bin": {
@@ -9,6 +9,7 @@
9
9
  "files": [
10
10
  "AGENTS.base.md",
11
11
  "rules/",
12
+ "skills/",
12
13
  "merge.js",
13
14
  "AGENTS.private.example.md",
14
15
  "PULL_REQUEST_TEMPLATE.md",
package/skills/create-doc/SKILL.md ADDED
@@ -0,0 +1,70 @@
1
+ ---
2
+ name: create-doc
3
+ description: >-
4
+ 创建/生成符合项目规范的 HTML 文档或报告。触发场景包括但不限于：
5
+ 「写文档」「写个文档」「写一个文档」「写报告」「写个报告」「写一个报告」「写需求文档」「写需求」「写说明」「写说明文档」「写方案」「写方案文档」「写设计文档」「写技术文档」「写接口文档」「写API文档」「写总结」「写总结报告」「写复盘」「写复盘报告」「写周报」「写日报」「写月报」。
6
+ 「出文档」「出个文档」「出一个文档」「出报告」「出个报告」「出一个报告」「出需求文档」「出方案」「出方案文档」「出设计文档」「出说明」「出说明文档」「出总结」「出总结报告」「出复盘」「出复盘报告」。
7
+ 「生成文档」「生成报告」「生成需求文档」「生成方案」「生成说明」「生成设计文档」「生成总结」「生成复盘」「生成汇报」。
8
+ 「做文档」「做个文档」「做报告」「做个报告」「做汇报」「做个汇报」「做方案」「做个方案」「做总结」「做个总结」。
9
+ 「搞文档」「搞个文档」「搞报告」「搞个报告」「整文档」「整个文档」「整报告」「整个报告」「弄文档」「弄个文档」「弄报告」「弄个报告」。
10
+ 「文档」「报告」「需求文档」「汇报」单独说且上下文在讨论产出物时也应触发。
11
+ 自动生成符合项目规范（HTML格式、中文文件名、base64内嵌图片、lightbox图片放大、截图为主文字为辅）的中文HTML文档，存放到docs/目录。
12
+ ---
13
+
14
+ # 创建 HTML 文档
15
+
16
+ ⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `create-doc`，按规范生成 HTML 文档...」然后严格按照以下步骤执行，不得跳过。**
17
+
18
+ 生成符合项目规范的中文 HTML 文档/报告。
19
+
20
+ ## 文档规范
21
+
22
+ ### 格式要求
23
+
24
+ - 所有新建文档使用 HTML 格式（`.html`），禁止 Markdown（`.md`）
25
+ - 文件名使用中文命名，存放到项目 `docs/` 目录
26
+ - 标题、正文、章节、说明文字全部中文
27
+ - 代码、命令、专有名词、接口字段可保留英文
28
+
29
+ ### 可视化优先
30
+
31
+ - ⚠️ 核心内容优先用截图、图片、流程图、对比图等可视化形式表达
32
+ - ⚠️ 截图为主、文字为辅（截图占主导版面，文字仅作简要说明）
33
+ - ⚠️ 每段说明文字紧挨其对应截图（「说明→配图」紧密组合）
34
+
35
+ ### 图片处理
36
+
37
+ - ⚠️ 所有图片以 base64 data URI 形式内嵌到 HTML 中，禁止引用外部图片文件
38
+ - ⚠️ 所有图片必须支持点击放大、全屏查看（lightbox 遮罩层）
39
+ - lightbox 实现：图片绑定 click → 弹出半透明黑色遮罩 → 图片居中自适应 → ESC/点击背景关闭
40
+
41
+ ### 报告结构
42
+
43
+ ```html
44
+ <!DOCTYPE html>
45
+ <html lang="zh-CN">
46
+ <head>
47
+ <meta charset="UTF-8">
48
+ <title>文档标题</title>
49
+ <style>
50
+ /* lightbox 样式 */
51
+ /* 正文排版样式 */
52
+ </style>
53
+ </head>
54
+ <body>
55
+ <h1>文档标题</h1>
56
+ <!-- 说明文字 + 配图 紧密组合 -->
57
+ <!-- 重复：说明 → 配图 → 说明 → 配图 -->
58
+ <script>
59
+ // lightbox 交互脚本
60
+ </script>
61
+ </body>
62
+ </html>
63
+ ```
64
+
65
+ ### 截图规范
66
+
67
+ - 截取整页（full page），不是可视区域
68
+ - 截图结果必须包含当前页面 URL
69
+ - 标注（箭头、提示文字等）放在页面空白区域，不覆盖页面内容
70
+ - 制作过程中产生的中间截图文件统一放到 `screenshots/` 目录
package/skills/create-pr/SKILL.md ADDED
@@ -0,0 +1,95 @@
1
+ ---
2
+ name: create-pr
3
+ description: >-
4
+ 创建 / 提交 / 发起 Pull Request。触发场景包括但不限于：
5
+ 「提PR」「提个PR」「提一个PR」「提交PR」「创建PR」「发起PR」「开PR」「开个PR」「搞个PR」「弄个PR」「弄一个PR」「来一个PR」「帮我PR」「帮我提PR」「帮我提交PR」「帮我创建PR」「帮我开PR」「帮我弄PR」「帮我搞PR」「创建pull request」「提交pull request」「发起pull request」「新建PR」「新建pull request」「生成PR」「生成pull request」「做PR」「做个PR」「做一下PR」「做下PR」「整PR」「整个PR」「整一个PR」「出PR」「出个PR」「出一个PR」「搞PR」「来PR」「上PR」「上一下PR」「帮我上PR」。
6
+ 任何包含「PR」「Pull Request」「pull request」且表达创建/提交/发起语义的说法都应触发。
7
+ 以及：「把这个提交一下」「把这个提了」「提上去」「提交上去」「推到远程」「推到仓库」「发到仓库」「合到主线」「合入主线」「合并到main」「合并到master」「合并请求」「创建合并请求」「发起合并请求」「帮我合一下」「帮我合并」「帮我合了」「把这个合了」「合一下」「合了」。
8
+ 自动生成中文Title/Description/TestPlan、制作效果截图（前后对比）、上传到GitHub CDN、内嵌到Description中。
9
+ ---
10
+
11
+ # 创建 Pull Request
12
+
13
+ ⚠️ **本 Skill 已触发。在用户回复中第一句话必须输出：「🔧 已触发 `create-pr`，按流程创建 PR...」然后严格按照以下步骤执行，不得跳过。**
14
+
15
+ 从当前分支创建 PR，自动完成：中文 Description、效果截图制作、GitHub CDN 上传。
16
+
17
+ ## 核心流程
18
+
19
+ ### 1. 收集改动信息
20
+
21
+ ```bash
22
+ git diff origin/main...HEAD --stat
23
+ ```
24
+
25
+ 确认改动范围，判断 PR 类型（UI 改动 / 接口改动 / 修 bug / 新功能）。
26
+
27
+ ### 2. 查找关联需求文档
28
+
29
+ 自动搜索 `docs/` 目录下对应的需求文档（HTML 格式），匹配当前分支名关键词。
30
+
31
+ ### 3. 生成 PR 内容（全部中文）
32
+
33
+ **Title**：`[模块] 动词 + 改了什么`，祈使句，一行说清。
34
+
35
+ **Description** 模板：
36
+ ```markdown
37
+ ## 背景
38
+ （为什么要改，解决什么问题）
39
+
40
+ ## 改动
41
+ （改了什么，采用什么方案）
42
+
43
+ ## 方案取舍
44
+ （为什么选这个方案，考虑过什么替代方案）
45
+
46
+ ## 不在本 PR 范围
47
+ （有意不做的事、已知局限、后续 follow-up）
48
+
49
+ Closes #issue编号
50
+ ```
51
+
52
+ **Test Plan**：写明验证步骤，禁止「测了没问题」类敷衍描述。
53
+
54
+ ### 4. 制作效果截图
55
+
56
+ 仅对有 UI 改动/修 bug 的 PR 执行：
57
+
58
+ 1. **截修复后**：浏览器打开改动页面 → 滚动到改动区域 → 全页截图
59
+ 2. **截修复前**：临时注释/回退改动代码 → 等 hot reload → 同位置截图 → 恢复代码
60
+ 3. **生成对比图**：用 sharp 拼接 → 上方红/绿色标注条（❌修复前 / ✅修复后）→ 下方左右并排截图 → 关键改动区域矩形框圈选
61
+ 4. **上传 GitHub CDN**：打开 PR 页面 → 评论区 file input 上传 → 获取 `user-attachments` CDN URL
62
+ 5. **写入 Description**：`![](CDN_URL)` 内嵌，清理临时评论
63
+
64
+ **截图规范**：
65
+ - ⚠️ 截图禁止提交到 Git 仓库
66
+ - ⚠️ 必须展示前后对比（修复前红框，修复后绿框）
67
+ - ⚠️ 标注不遮挡页面内容
68
+ - ⚠️ 只截改动相关区域，裁掉无关内容
69
+
70
+ ### 5. 创建 PR
71
+
72
+ ```bash
73
+ gh pr create \
74
+ --title "中文标题" \
75
+ --body "中文 Description（含截图 CDN URL）" \
76
+ --base main \
77
+ --head "$(git branch --show-current)"
78
+ ```
79
+
80
+ ### 6. 补充元数据
81
+
82
+ - Assignees：填自己
83
+ - Labels：按类型/模块添加
84
+ - 关联 issue：如有
85
+ - Milestone：如有
86
+
87
+ ## 重要规则
88
+
89
+ - ⚠️ 一个 PR 只做一件事
90
+ - ⚠️ PR 所有文字内容必须中文
91
+ - ⚠️ 必须附截图作为可视化证据
92
+ - ⚠️ 截图禁止提交到 Git 仓库
93
+ - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）
94
+ - 先开 Draft PR，准备好再标记 Ready for review
95
+ - 作者不能 Approve 自己的 PR
package/skills/deploy-test/SKILL.md ADDED
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: deploy-test
3
+ description: >-
4
+ 部署 / 发布到测试环境。触发场景包括但不限于：
5
+ 「部署测试环境」「部署test」「部署测试」「部署到测试」「部署到test」「发布测试」「发布test」「发布到测试」「发布到test」「上线测试」「上线test」「测试环境部署」「测试环境发布」「测试环境上线」「部署测试服」「发布测试服」「上线测试服」「推到测试」「推到test」「推测试」「推test」。
6
+ 「帮我部署」「帮我发布」「帮我上线」「部署一下」「发布一下」「上线一下」「部署吧」「发布吧」「上线吧」「部署了」「发布了」「上线了」「搞部署」「做部署」「弄部署」。
7
+ 「打测试」「打test」「打一下测试」「打个测试包」「打包测试」「打包到测试」「发版测试」「发版到测试」。
8
+ 「部署」「发布」「上线」单独说且上下文在讨论测试环境时也应触发。
9
+ 自动完成：记录当前分支→合并到test→推送→部署→发版→切回原分支。
10
+ ---
11
+
12
+ # 部署测试环境
13
+
14
+ ⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `deploy-test`，按流程部署测试环境...」然后严格按照以下步骤执行，不得跳过。**
15
+
16
+ 将当前功能分支部署到测试环境，完成后自动切回原分支。
17
+
18
+ ## 核心流程
19
+
20
+ ### 1. 记录当前分支
21
+
22
+ ```bash
23
+ ORIGINAL_BRANCH=$(git branch --show-current)
24
+ echo "当前分支: $ORIGINAL_BRANCH"
25
+ ```
26
+
27
+ ### 2. test 分支检查
28
+
29
+ 如果 `test` 分支不存在，从主分支创建：
30
+
31
+ ```bash
32
+ git fetch origin
33
+ if ! git show-ref --verify --quiet refs/heads/test; then
34
+ MAIN=$(git remote show origin | grep 'HEAD branch' | cut -d: -f2 | tr -d ' ')
35
+ git checkout -b test "origin/${MAIN:-main}"
36
+ git push origin test
37
+ fi
38
+ ```
39
+
40
+ ### 3. 合并当前分支到 test
41
+
42
+ ```bash
43
+ git checkout test
44
+ git pull origin test
45
+ git merge "$ORIGINAL_BRANCH"
46
+ ```
47
+
48
+ ### 4. 推送 test 分支
49
+
50
+ ```bash
51
+ git push origin test
52
+ ```
53
+
54
+ ### 5. 部署 test 分支
55
+
56
+ 按项目自己的部署方式执行（Cloud Run / 容器 / npm publish 等）。
57
+
58
+ ### 6. 发新版本
59
+
60
+ 按项目发版规则执行（如 `./release.sh`）。
61
+
62
+ ### 7. 切回原功能分支
63
+
64
+ ```bash
65
+ git checkout "$ORIGINAL_BRANCH"
66
+ ```
67
+
68
+ ## 重要规则
69
+
70
+ - ⚠️ 推送 test 后必须立即执行 `git push origin test`
71
+ - ⚠️ 部署完成后必须立即切回原功能分支
72
+ - ⚠️ 部署必须自包含：migration、配置变更、依赖检查全部脚本化自动执行，禁止部署后人工补操作
73
+ - 禁止直接往 test 分支提交代码
74
+ - 敏感信息（密钥、Token）必须从 Nacos 配置中心拉取，不得写死
package/skills/figma-to-code/SKILL.md ADDED
@@ -0,0 +1,60 @@
1
+ ---
2
+ name: figma-to-code
3
+ description: >-
4
+ Figma 设计稿还原为代码 / 实现 Figma 设计。触发场景包括但不限于：
5
+ 「figma」「Figma」「FIGMA」出现时。
6
+ 「实现这个设计」「还原这个设计」「按照设计稿」「按设计稿」「照着设计稿」「根据设计稿」「设计稿还原」「设计还原」「Figma还原」「figma还原」。
7
+ 「把这个页面做出来」「实现这个页面」「还原这个页面」「做这个页面」「写这个页面」「开发这个页面」「切这个页面」「切图」「切页面」。
8
+ 「figma链接」「Figma链接」「设计稿链接」「figma地址」「Figma地址」。
9
+ 「从Figma」「从figma」「看下设计稿」「看下设计」「看设计」「看Figma」。
10
+ 任何提供 Figma URL 或提及 Figma 设计稿并要求生成/实现代码的场景都应触发。
11
+ 使用MCP三步验证法：get_design_context（设计意图）→get_metadata（精确坐标）→坐标反推布局，禁止直接使用get_design_context生成的Tailwind代码。
12
+ ---
13
+
14
+ # Figma 设计还原
15
+
16
+ ⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `figma-to-code`，按 MCP 三步验证法还原设计...」然后严格按照以下步骤执行，不得跳过。**
17
+
18
+ 将 Figma 设计稿还原为代码，以 Figma 文件为唯一事实源。
19
+
20
+ ## MCP 三步验证法
21
+
22
+ ⚠️ **禁止直接使用 `get_design_context` 生成的代码**。`get_design_context` 的输出是大模型推导的近似值，数值和结构均不可信。
23
+
24
+ ### 第 1 步：`get_design_context` → 获取设计意图
25
+
26
+ 用 `mcp__figma__get_design_context` 了解组件整体结构、颜色、字体、视觉效果。
27
+ ⚠️ 仅用于理解设计意图，数值和结构不可信。
28
+
29
+ ### 第 2 步：`get_metadata` → 获取精确坐标（唯一事实源）
30
+
31
+ 用 `mcp__figma__get_metadata` 获取每个节点的真实 x/y/width/height 坐标。
32
+ 这是所有尺寸、间距、定位的唯一事实源。
33
+
34
+ ### 第 3 步：坐标反推规则
35
+
36
+ | 场景 | 反推方法 |
37
+ |------|----------|
38
+ | Section 上下 padding | 子元素 y 坐标 = 上 padding；父级高度 - 子元素 y - 子元素高度 = 下 padding |
39
+ | 元素间距（gap） | 兄弟元素之间的 y 差值（纵向）或 x 差值（横向） |
40
+ | 元素是 flex 还是 absolute | 子元素 x 超出父元素左边界 → absolute；子元素在父元素范围内 → flex |
41
+ | 固定宽度还是自适应 | metadata 有明确 width 值 → 固定宽度；否则 → 自适应 |
42
+
43
+ ## 常见踩坑
44
+
45
+ 1. **`get_design_context` padding 不准** → 以 metadata 坐标为基准重新计算
46
+ 2. **按钮被嵌套在文字区域内** → metadata 中同级 x 不同、y 相近 = 横向并排，不应嵌套
47
+ 3. **固定宽度容器被改成全宽** → metadata 中有明确 width 的容器不能去掉固定宽度
48
+ 4. **装饰图片被当成 flex 子元素** → metadata 中 x 坐标超出父元素范围 = absolute 定位
49
+
50
+ ## 交付验收
51
+
52
+ - 交付前对照 Figma 做视觉和交互验收
53
+ - 发现无法完全还原的素材、字体、数据或平台限制时，明确说明差异和原因
54
+ - 逐项验证：布局、尺寸、间距、颜色、字体、层级、组件状态、响应式规则
55
+
56
+ ## 代码实现规范
57
+
58
+ - 所有尺寸单位使用 `rem`（1rem = 16px）
59
+ - 使用 Tailwind CSS utility classes，禁止原生 CSS
60
+ - 禁止硬编码数字，常量/枚举统一定义
package/skills/github-pr-review/SKILL.md ADDED
@@ -0,0 +1,233 @@
1
+ ---
2
+ name: github-pr-review
3
+ description: >-
4
+ PR Code Review 评论处理 / 解决 Review 反馈 / 处理 Reviewer 意见。触发场景包括但不限于：
5
+ 「处理review」「处理review评论」「处理review意见」「处理review反馈」「处理PR评论」「处理PR review」。
6
+ 「解决review」「解决PR评论」「解决PR review」「解决review评论」「解决review意见」「解决review反馈」。
7
+ 「修复review」「修复PR评论」「修复review评论」「修复review意见」「修复review反馈」「修复review问题」。
8
+ 「回复review」「回复review评论」「回复review意见」「回复PR评论」「回复reviewer」「回复审阅」「回复审阅意见」。
9
+ 「看review」「看下review」「看一下review」「看看review」「查看review」「查看review评论」「查看PR review」「查看PR评论」。
10
+ 「review一下」「review下」「看一下PR」「看看PR」「审阅一下」「审一下」「Code Review」「code review」。
11
+ 「处理审查」「解决审查」「修复审查」「回复审查」「查看审查」「审查一下」。
12
+ 「评审」「评审一下」「处理评审」「看一下评审」「看看评审」「回复评审」。
13
+ 「有人review了」「有人审阅了」「有人评论了」「有review了」「有review评论」「有新的review」「有新review」「来review了」。
14
+ 「review怎么改」「review要我改」「review让我改」「review说了」「review提到」「review指出的」「review提到的问题」。
15
+ 「reviwer说了」「reviwer让我改」「reviwer要我改」「reviwer提到」。
16
+ 「re-request」「重新请求review」「重新请求审阅」「发起re-review」。
17
+ 「PR反馈」「PR审阅」「PR审查」「PR评审」。
18
+ 通过 GitHub CLI 拉取评论 → 按严重程度分类 → 逐条提出修复 → 用户确认后提交 → 回复对应 thread。
19
+ ---
20
+
21
+ # GitHub PR review
22
+
23
+ ⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `github-pr-review`，按流程拉取 Review 评论并逐条处理...」然后严格按照以下步骤执行，不得跳过。**
24
+
25
+ Resolves Pull Request review comments with severity-based prioritization, fix application, and thread replies.
26
+
27
+ ## Current PR
28
+
29
+ !`gh pr view --json number,title,state,milestone -q '"PR #\(.number): \(.title) (\(.state)) | Milestone: \(.milestone.title // "none")"' 2>/dev/null`
30
+
31
+ ## Core workflow
32
+
33
+ ### 1. Fetch, filter, and classify comments
34
+
35
+ ```bash
36
+ REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
37
+ PR=$(gh pr view --json number -q '.number')
38
+ LAST_PUSH=$(git log -1 --format=%cI HEAD)
39
+
40
+ # Inline review comments - filter out replies (keep only originals)
41
+ gh api repos/$REPO/pulls/$PR/comments?per_page=100 --jq '
42
+ [.[] | select(.in_reply_to_id == null) |
43
+ {id, path, user: .user.login, created_at, body: .body[0:200]}]
44
+ '
45
+
46
+ # PR-level reviews with non-empty body (CodeRabbit sections, Gemini, etc.)
47
+ gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq '
48
+ [.[] | select(.body | length > 0) |
49
+ {id, user: .user.login, state, submitted_at, body: .body[0:500]}]
50
+ '
51
+ ```
52
+
53
+ **Cross-check review-attached comments**: CodeRabbit's review body states "Actionable comments posted: N". If the general `pulls/$PR/comments` endpoint returns fewer than N new originals from that reviewer, some comments are only available via the review-specific endpoint. Fetch them and merge by comment ID:
54
+
55
+ ```bash
56
+ # $REVIEW_ID from the reviews fetch above; $EXPECTED from parsing "Actionable comments posted: N"
57
+ gh api repos/$REPO/pulls/$PR/reviews/$REVIEW_ID/comments?per_page=100 --jq '
58
+ [.[] | select(.in_reply_to_id == null) |
59
+ {id, path, user: .user.login, created_at, body: .body[0:200]}]
60
+ '
61
+ ```
62
+
63
+ Deduplicate by `id` before continuing. Comments found only via the review-specific endpoint are valid inline comments and should be treated identically (same classification, same `in_reply_to` reply mechanism).
64
+
65
+ **Filter new vs already-seen**: compare `created_at`/`submitted_at` with `$LAST_PUSH`. Comments posted after the last push are new. Mark older comments as "previous round" in the summary table.
66
+
67
+ **Parse CodeRabbit review bodies**: the initial fetch truncates bodies for classification. For reviews from CodeRabbit (`user.login` starts with `coderabbitai`), fetch the full body separately:
68
+
69
+ ```bash
70
+ gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq '
71
+ [.[] | select(.user.login | startswith("coderabbitai")) |
72
+ {id, submitted_at, body}]
73
+ '
74
+ ```
75
+
76
+ CodeRabbit posts structured `<details>` blocks containing outside-diff, duplicate, and nitpick comments. Each block includes file path, line range, severity, and optionally a "Prompt for AI Agents" with pre-built context. See `references/coderabbit_parsing.md` for full parsing guide.
77
+
78
+ **Use CodeRabbit AI prompts when available**: if a comment (or the review body) contains a "Prompt for AI Agents" `<details>` block, use it to understand the issue and suggested approach. Always read the actual code before proposing a fix. If the review body contains a "Prompt for all review comments with AI agents" block, read it first for cross-comment context before processing individual comments.
79
+
80
+ Classify all comments by severity and process in order: CRITICAL > HIGH > MEDIUM > LOW.
81
+
82
+ | Severity | Indicators | Action |
83
+ |----------|------------|--------|
84
+ | CRITICAL | `critical.svg`, `_🔒 Security_`, `_🚨 Critical_`, `_🔴 Critical_`, "security", "vulnerability" | Must fix |
85
+ | HIGH | `high-priority.svg`, `_⚠️ Potential issue_`, `_🐛 Bug_`, `_⚡ Performance_`, `_🟠 Major_`, "High Severity" | Should fix |
86
+ | MEDIUM | `medium-priority.svg`, `_🛠️ Refactor suggestion_`, `_💡 Suggestion_`, "Medium Severity" | Recommended |
87
+ | LOW | `low-priority.svg`, `_🧹 Nitpick_`, `_🔧 Optional_`, `_🟡 Minor_`, `_🔵 Trivial_`, `_⚪ Info_`, "style", "nit" | Optional |
88
+
89
+ When a comment has both a type label and a secondary color badge (e.g., `_💡 Suggestion_ | _🟠 Major_`), the color badge is the **binding** severity and overrides the type-based default.
90
+
91
+ See `references/severity_guide.md` for full detection patterns (Gemini badges, CodeRabbit emoji, Cursor comments, keyword fallback, related comments heuristics).
92
+
93
+ ### 2. Show review summary table
94
+
95
+ Before processing, display a structured overview of all comments:
96
+
97
+ ```
98
+ | # | ID | Severity | File:Line | Type | Status | Summary |
99
+ |---|------------|----------|--------------------|----------|----------|--------------------|
100
+ | 1 | 123456789 | CRITICAL | src/auth.py:45 | inline | new | SQL injection risk |
101
+ | 2 | 987654321 | HIGH | src/db.py:346-350 | outside | new | Missing join cond |
102
+ | 3 | 555555555 | HIGH | src/chunk.py:188 | duplicate| previous | Stale metadata |
103
+ | 4 | 444444444 | LOW | tests/test_q.py:12 | nitpick | previous | Naming convention |
104
+ ```
105
+
106
+ - **Type**: `inline`, `outside` (outside diff), `duplicate`, `minor`, `nitpick` (from CodeRabbit sections), or `review` (generic PR-level)
107
+ - **Status**: `new` (posted after last push) or `previous` (from earlier rounds)
108
+ - Group related comments (same file, same root cause, "also applies to" ranges) and note clusters
109
+ - Deduplicate: if the same issue appears both as an inline comment and in a CodeRabbit review body section (e.g., duplicate), keep one entry and note both sources
110
+
111
+ If there are **more than 10 comments**, suggest saving a review summary to Claude's memory for tracking across sessions. The summary should include: PR number, comment IDs, severity, status (new/addressed/deferred/won't fix), and brief description. This helps maintain continuity when new comments arrive after subsequent pushes.
112
+
113
+ ### 3. Process each comment
114
+
115
+ For each comment, in severity order:
116
+
117
+ 1. **Show context**: comment ID, severity, file:line, quote
118
+ 2. **Check for AI prompt**: if CodeRabbit "Prompt for AI Agents" is available for this comment, use it to understand the issue and suggested approach
119
+ 3. **Check for proposed fix**: if CodeRabbit includes a "Proposed fix" or "Suggested fix" code block, use it as a starting point (but verify correctness)
120
+ 4. **Read affected code** and propose fix (always read the actual code, even when an AI prompt or proposed fix provides context)
121
+ 5. **Handle "also applies to"**: if the comment references additional line ranges, include all locations in the fix
122
+ 6. **Confirm with user** before applying
123
+ 7. **Apply fix** if approved
124
+ 8. **Verify ALL issues** in the comment are addressed (multi-issue comments are common)
125
+
126
+ ### 4. Commit changes
127
+
128
+ Use git-commit skill format. Functional fixes get separate commits, cosmetic fixes are batched:
129
+
130
+ | Change type | Strategy |
131
+ |-------------|----------|
132
+ | Functional (CRITICAL/HIGH) | Separate commit per fix |
133
+ | Cosmetic (MEDIUM/LOW) | Single batch `style:` commit |
134
+
135
+ Reference the comment ID in the commit body.
136
+
137
+ ### 5. Reply to threads
138
+
139
+ #### Inline comments
140
+
141
+ **Important**: use `--input -` with JSON. The `-f in_reply_to=...` syntax does NOT work.
142
+
143
+ ```bash
144
+ COMMIT=$(git rev-parse --short HEAD)
145
+ gh api repos/$REPO/pulls/$PR/comments \
146
+ --input - <<< '{"body": "Fixed in '"$COMMIT"'. Brief explanation.", "in_reply_to": 123456789}'
147
+ ```
148
+
149
+ #### Non-inline comments (CodeRabbit review body)
150
+
151
+ Comments embedded in the review body (outside diff, duplicate, nitpick) do not have inline threads. The GitHub API does not support replying to a review body directly. Post a general PR comment referencing the specific issue:
152
+
153
+ ```bash
154
+ gh pr comment $PR --body "Fixed in $COMMIT. Addresses outside-diff comment on file/path.py:346-350."
155
+ ```
156
+
157
+ **Reply templates** (no emojis, minimal and professional):
158
+
159
+ | Situation | Template |
160
+ |-----------|----------|
161
+ | Fixed | `Fixed in [hash]. [brief description of fix]` |
162
+ | Won't fix | `Won't fix: [reason]` |
163
+ | By design | `By design: [explanation]` |
164
+ | Deferred | `Deferred to [issue/task]. Will address in future iteration.` |
165
+ | Acknowledged | `Acknowledged. [brief note]` |
166
+
167
+ ### 6. Run tests and push
168
+
169
+ Run the project test suite. All tests must pass before pushing. Push all fixes together to minimize review loops.
170
+
171
+ ### 7. Submit review (optional)
172
+
173
+ After addressing all comments, formally submit a review:
174
+
175
+ - `gh pr review $PR --approve --body "..."` - all comments addressed, PR is ready
176
+ - `gh pr review $PR --request-changes --body "..."` - critical issues remain
177
+ - `gh pr review $PR --comment --body "..."` - progress update, no decision yet
178
+
179
+ ### 8. Verify milestone
180
+
181
+ ```bash
182
+ gh pr view $PR --json milestone -q '.milestone.title // "none"'
183
+ ```
184
+
185
+ If the PR has no milestone, check for open milestones:
186
+
187
+ ```bash
188
+ REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
189
+ gh api repos/$REPO/milestones --jq '[.[] | select(.state=="open")] | .[] | "\(.number): \(.title)"'
190
+ ```
191
+
192
+ If open milestones exist, inform the user and suggest assigning:
193
+
194
+ ```bash
195
+ gh pr edit $PR --milestone "[milestone-title]"
196
+ ```
197
+
198
+ Do **not** assign automatically. This is a reminder only.
199
+
200
+ ## Avoiding review loops
201
+
202
+ When bots (Gemini, Codex, etc.) review every push:
203
+
204
+ 1. **Batch fixes**: accumulate all fixes, push once
205
+ 2. **Draft PR**: convert to draft during fixes
206
+ 3. **Commit keywords**: some bots respect `[skip ci]` or `[skip review]`
207
+
208
+ ## Important rules
209
+
210
+ - **ALWAYS** fetch both inline comments (`pulls/$PR/comments`) and review bodies (`pulls/$PR/reviews`)
211
+ - **ALWAYS** cross-check "Actionable comments posted: N" against found originals; fetch `pulls/$PR/reviews/$REVIEW_ID/comments` when count mismatches
212
+ - **ALWAYS** parse CodeRabbit review bodies for all section types (outside diff, duplicate, minor, nitpick)
213
+ - **ALWAYS** use CodeRabbit "Prompt for AI Agents" as primary context when available
214
+ - **ALWAYS** show the review summary table before processing
215
+ - **ALWAYS** confirm before modifying files
216
+ - **ALWAYS** verify ALL issues in multi-issue comments are fixed, including "also applies to" ranges
217
+ - **ALWAYS** run tests before pushing
218
+ - **ALWAYS** reply to resolved threads using standard templates
219
+ - **ALWAYS** submit formal review (`gh pr review`) after addressing all comments
220
+ - **ALWAYS** check milestone at the end and remind if missing
221
+ - **ALWAYS** suggest saving a review summary to memory when there are more than 10 comments
222
+ - **NEVER** use emojis in commit messages or thread replies
223
+ - **NEVER** skip HIGH/CRITICAL comments without explicit user approval
224
+ - **NEVER** assign milestone automatically - suggest only
225
+ - **Functional fixes** -> separate commits (one per fix)
226
+ - **Cosmetic fixes** -> batch into single `style:` commit
227
+ - **Duplicate comments** -> treat as higher priority than their label (issue was already flagged before)
228
+ - **Related comments** -> group and fix together when they share root cause or file context
229
+
230
+ ## References
231
+
232
+ - `references/severity_guide.md` - Severity detection patterns (Gemini badges, CodeRabbit emoji, Cursor comments, keyword fallback, related comments heuristics)
233
+ - `references/coderabbit_parsing.md` - CodeRabbit review body structure, section parsing, "Prompt for AI Agents" usage, duplicate and "also applies to" handling
package/skills/github-pr-review/references/coderabbit_parsing.md ADDED
@@ -0,0 +1,206 @@
1
+ # CodeRabbit review parsing
2
+
3
+ Guide for extracting and processing all comment types from CodeRabbit PR reviews.
4
+
5
+ ## Review body structure
6
+
7
+ CodeRabbit posts a single PR-level review (via `pulls/$PR/reviews` API) containing multiple sections as collapsible `<details>` blocks. The body follows this structure:
8
+
9
+ ```
10
+ Actionable comments posted: N
11
+
12
+ > [!CAUTION]
13
+ > Some comments are outside the diff and can't be posted inline...
14
+
15
+ <details>
16
+ <summary>⚠️ Outside diff range comments (N)</summary>
17
+ (actionable comments on code outside the PR diff)
18
+ </details>
19
+
20
+ <details>
21
+ <summary>♻️ Duplicate comments (N)</summary>
22
+ (issues already flagged in a previous review)
23
+ </details>
24
+
25
+ <details>
26
+ <summary>🟡 Minor comments (N)</summary>
27
+ (lower severity comments grouped to reduce inline noise)
28
+ </details>
29
+
30
+ <details>
31
+ <summary>🧹 Nitpick comments (N)</summary>
32
+ (style/convention issues, lowest priority)
33
+ </details>
34
+
35
+ <details>
36
+ <summary>🤖 Prompt for all review comments with AI agents</summary>
37
+ (global prompt covering all comments in this review)
38
+ </details>
39
+
40
+ <!-- Informational sections (not actionable, ignore): -->
41
+ <details><summary>ℹ️ Review info</summary></details>
42
+ <details><summary>⚙️ Run configuration</summary></details>
43
+ <details><summary>📥 Commits</summary></details>
44
+ <details><summary>⛔ Files ignored due to path filters (N)</summary></details>
45
+ <details><summary>📒 Files selected for processing (N)</summary></details>
46
+ <details><summary>🚧 Files skipped from review as they are similar to previous changes (N)</summary></details>
47
+ ```
48
+
49
+ Not all sections are always present. CodeRabbit only includes sections that have comments. Other severity-based sections (e.g., "🔴 Critical comments", "🟠 Major comments") may also appear.
50
+
51
+ ## Fetching CodeRabbit reviews
52
+
53
+ ```bash
54
+ REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')
55
+ PR=$(gh pr view --json number -q '.number')
56
+
57
+ # Get all CodeRabbit review bodies (may be multiple reviews across pushes)
58
+ gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq '
59
+ [.[] | select(.user.login | startswith("coderabbitai")) |
60
+ {id, submitted_at, body}]
61
+ '
62
+ ```
63
+
64
+ The `id` field is the review ID (visible in the GitHub URL as `#pullrequestreview-<id>`). Use this as the stable identifier for tracking.
65
+
66
+ ## Parsing sections from the body
67
+
68
+ Each section is a `<details>` block. Extract them by matching the summary text:
69
+
70
+ | Summary pattern | Comment type | Default severity |
71
+ |----------------|--------------|-----------------|
72
+ | `⚠️ Outside diff range comments` | Code outside the PR diff | Use per-comment severity |
73
+ | `♻️ Duplicate comments` | Already flagged in previous reviews | Use per-comment severity |
74
+ | `🟡 Minor comments` | Lower severity, grouped to reduce noise | MEDIUM/LOW (use per-comment) |
75
+ | `🧹 Nitpick comments` | Style/convention issues | LOW |
76
+ | `🤖 Prompt for all review comments with AI agents` | Global AI context prompt | N/A (not a comment) |
77
+
78
+ Other severity-based sections like "🔴 Critical comments" or "🟠 Major comments" may appear. Treat any unrecognized `<details>` section with comments as actionable and classify by per-comment severity.
79
+
80
+ Informational sections (`ℹ️ Review info`, `⚙️ Run configuration`, `📥 Commits`, `⛔ Files ignored due to path filters`, `📒 Files selected for processing`, `🚧 Files skipped from review as they are similar to previous changes`) are not actionable. Ignore them.
81
+
82
+ ### Per-comment structure inside sections
83
+
84
+ Each file group is wrapped in a `<details>` block. The summary format varies:
85
+
86
+ ```
87
+ <!-- Outside diff / Duplicate sections: file path + count -->
88
+ <details>
89
+ <summary>file/path.ext (N)</summary>
90
+
91
+ <!-- Minor / Nitpick sections: file path + line range + count -->
92
+ <details>
93
+ <summary>file/path.ext-X-Y (N)</summary>
94
+ ```
95
+
96
+ Inside each file group, individual comments follow this pattern:
97
+
98
+ ```
99
+ `X-Y`: _<emoji> <type>_ | _<color> <severity>_
100
+
101
+ **Title text**
102
+
103
+ Description paragraph(s)...
104
+
105
+ As per coding guidelines, `path/**`: "quote..." (optional, references project rules)
106
+
107
+ Also applies to: X-Y, X-Y (optional, other line ranges with same issue)
108
+
109
+ <details><summary>Proposed fix</summary>
110
+ ```lang
111
+ code suggestion
112
+ ```
113
+ </details>
114
+
115
+ <details><summary>Prompt for AI Agents</summary>
116
+ prompt text...
117
+ </details>
118
+ ```
119
+
120
+ Key fields to extract:
121
+ - **File path**: from the `<details><summary>` wrapping the file group
122
+ - **Line range**: backtick-formatted `` `X-Y` `` at the start of each comment (may also appear in the file summary as `path.ext-X-Y`)
123
+ - **Severity**: emoji + type label and optional color severity (see severity_guide.md)
124
+ - **Title**: bold text after the severity line
125
+ - **"Also applies to"**: additional line ranges in the same file with the same issue
126
+ - **Proposed fix / Suggested fix**: code suggestion inside `<details>`. Summary text varies widely, with optional emoji prefix and description. Examples: `Proposed fix`, `Suggested fix`, `🔧 Proposed fix (...)`, `💡 Proposed fix`, `🔒 Suggested direction`, `✨ Optional: ...`, `♻️ Suggested cleanup`, `🔎 Suggested assertion hardening`, `♻️ Suggested diff`. Match any `<details>` block whose summary contains "fix", "suggest", "proposed", or "optional"
127
+ - **Prompt for AI Agents**: per-comment context prompt inside `<details>`
128
+
129
+ ## Using the "Prompt for AI Agents"
130
+
131
+ CodeRabbit provides two levels of AI prompts:
132
+
133
+ ### Per-comment prompt
134
+ Inside each comment's `<details><summary>Prompt for AI Agents</summary>` block. Contains:
135
+ - The specific file and line range
136
+ - The issue description with context
137
+ - References to coding guidelines or project conventions
138
+ - The suggested fix approach
139
+
140
+ ### Global prompt
141
+ At the bottom of the review body, inside `<details><summary>Prompt for all review comments with AI agents</summary>`. Contains:
142
+ - Aggregated context for all comments in the review
143
+ - File paths, line ranges, and descriptions for every comment
144
+ - Useful for batch processing multiple comments at once
145
+
146
+ **How to use these prompts**:
147
+ 1. When processing a comment, check if it has a per-comment prompt
148
+ 2. If present, use it to understand the issue and suggested approach
149
+ 3. Always read the actual code before proposing a fix, even when the prompt provides context
150
+ 4. For batch processing, use the global prompt to understand all issues at once before diving into individual fixes
151
+
152
+ ## Inline comments vs review body comments
153
+
154
+ CodeRabbit posts comments in two ways:
155
+
156
+ | Type | API endpoint | When used |
157
+ |------|-------------|-----------|
158
+ | Inline review comments | `pulls/$PR/comments` | Comments on lines within the PR diff |
159
+ | Review body sections | `pulls/$PR/reviews` | Outside diff, duplicate, nitpick comments |
160
+ | Review-attached inline comments | `pulls/$PR/reviews/$REVIEW_ID/comments` | Fallback for inline comments not yet surfaced by the general endpoint |
161
+
162
+ **ALWAYS** fetch both endpoints to get the complete picture. Inline comments may reference issues also mentioned in the review body (especially duplicates).
163
+
164
+ ### Review-attached comment gap
165
+
166
+ CodeRabbit's "actionable comments" are posted as part of a review object. The general `pulls/$PR/comments` endpoint may not surface these comments, or may surface them with a delay. When the review body states "Actionable comments posted: N" but the general endpoint returns fewer than N new originals from CodeRabbit, fetch the missing comments via the review-specific endpoint:
167
+
168
+ ```bash
169
+ gh api repos/$REPO/pulls/$PR/reviews/$REVIEW_ID/comments?per_page=100 --jq '
170
+ [.[] | select(.in_reply_to_id == null) |
171
+ {id, path, user: .user.login, created_at, body: .body[0:200]}]
172
+ '
173
+ ```
174
+
175
+ Deduplicate by `id` against the general endpoint results. Comments found only via this endpoint are standard inline comments and support the same `in_reply_to` reply mechanism.
176
+
177
+ ## "Also applies to" handling
178
+
179
+ Some comments include `Also applies to: 258-266, 291-296`. These indicate the same issue exists at multiple locations in the same file. When fixing:
180
+
181
+ 1. Fix the primary location (the one with the full description)
182
+ 2. Apply the same fix pattern to all "also applies to" ranges
183
+ 3. Verify each location, as the exact code may differ slightly
184
+
185
+ ## Duplicate comments
186
+
187
+ Comments in the "Duplicate comments" section were already flagged in a previous review. They reappear because the underlying issue was not fixed. Treat them as:
188
+
189
+ - Same severity as indicated in their label
190
+ - Higher actual priority than their label suggests (reviewer is repeating themselves)
191
+ - Check if they were previously deferred or missed
192
+
193
+ ## Configuration reference
194
+
195
+ CodeRabbit behavior is controlled via `.coderabbit.yaml` in the repo root:
196
+
197
+ ```yaml
198
+ reviews:
199
+ profile: "chill" # chill (default) or assertive (includes nitpicks)
200
+ enable_prompt_for_ai_agents: true # includes "Prompt for AI Agents" in comments
201
+ ```
202
+
203
+ - `chill`: lighter feedback, nitpick sections are hidden
204
+ - `assertive`: full feedback, includes nitpick and minor comments
205
+
206
+ Official docs: https://docs.coderabbit.ai/guides/code-review-overview
package/skills/github-pr-review/references/severity_guide.md ADDED
@@ -0,0 +1,222 @@
1
+ # Severity guide
2
+
3
+ Reference guide for interpreting severity levels from automated review comments (Gemini, CodeRabbit, Cursor, and others).
4
+
5
+ ## Severity Badges
6
+
7
+ Gemini uses visual badges in review comments to indicate severity:
8
+
9
+ ### CRITICAL
10
+ **Badge**: `![critical](https://www.gstatic.com/codereviewagent/critical.svg)`
11
+
12
+ **Visual**: Red badge with "critical" text
13
+
14
+ **Meaning**: Must be fixed before merge. Indicates:
15
+ - Security vulnerabilities
16
+ - Data loss risks
17
+ - Logic errors causing incorrect behavior
18
+ - Infinite loops or deadlocks
19
+ - Memory leaks or resource exhaustion
20
+
21
+ **Action**: Stop and fix immediately. These block merge.
22
+
23
+ ---
24
+
25
+ ### HIGH
26
+ **Badge**: `![high](https://www.gstatic.com/codereviewagent/high-priority.svg)`
27
+
28
+ **Visual**: Orange badge
29
+
30
+ **Meaning**: Should be fixed. Indicates:
31
+ - Performance issues
32
+ - Error handling gaps
33
+ - Potential race conditions
34
+ - Missing validation on important paths
35
+
36
+ **Action**: Address before merge unless there's a strong reason not to.
37
+
38
+ ---
39
+
40
+ ### MEDIUM
41
+ **Badge**: `![medium](https://www.gstatic.com/codereviewagent/medium-priority.svg)`
42
+
43
+ **Visual**: Yellow badge
44
+
45
+ **Meaning**: Recommended fix. Indicates:
46
+ - Code style issues
47
+ - Minor refactoring opportunities
48
+ - Unreachable code (dead code)
49
+ - Duplicate logic
50
+ - Missing edge case handling
51
+
52
+ **Action**: Address if time permits, or create follow-up issue.
53
+
54
+ ---
55
+
56
+ ### LOW
57
+ **Badge**: `![low](https://www.gstatic.com/codereviewagent/low-priority.svg)`
58
+
59
+ **Visual**: Blue/gray badge
60
+
61
+ **Meaning**: Optional improvement. Indicates:
62
+ - Import ordering
63
+ - Naming conventions
64
+ - Documentation suggestions
65
+ - Minor style preferences
66
+
67
+ **Action**: Optional. Can be skipped with justification.
68
+
69
+ ---
70
+
71
+ ## Detection Patterns
72
+
73
+ ### Gemini Badge Detection (Primary for Gemini)
74
+ ```python
75
+ # In comment body, look for:
76
+ "critical.svg" → CRITICAL
77
+ "high-priority.svg" → HIGH
78
+ "medium-priority.svg" → MEDIUM
79
+ "low-priority.svg" → LOW
80
+ ```
81
+
82
+ ### CodeRabbit Detection
83
+
84
+ CodeRabbit does **not** use SVG badges. It uses emoji + italic text in the comment body.
85
+ The pattern is: `_<emoji> <label>_` or `_<emoji> <label>_ | _<color> <severity>_`
86
+
87
+ CodeRabbit classifies comments along two axes: **type** (what kind of issue) and **severity** (how impactful).
88
+
89
+ #### Comment types (primary label)
90
+
91
+ | Comment pattern | Severity |
92
+ |----------------|----------|
93
+ | `_🔒 Security_` or `_🚨 Critical_` | CRITICAL |
94
+ | `_⚠️ Potential issue_` | HIGH |
95
+ | `_🐛 Bug_` | HIGH |
96
+ | `_⚡ Performance_` | HIGH |
97
+ | `_🛠️ Refactor suggestion_` | MEDIUM |
98
+ | `_💡 Suggestion_` | MEDIUM |
99
+ | `_🧹 Nitpick_` | LOW (only in assertive mode) |
100
+ | `_🔧 Optional_` | LOW (skip by default) |
101
+
102
+ #### Severity levels (secondary color badge)
103
+
104
+ When a secondary color badge is present, use it as the **binding** severity indicator
105
+ (it overrides the type-based default above):
106
+
107
+ | Secondary badge | Official name | Maps to |
108
+ |----------------|---------------|---------|
109
+ | `_🔴 Critical_` | Critical | CRITICAL |
110
+ | `_🟠 Major_` | Major | HIGH |
111
+ | `_🟡 Minor_` | Minor | LOW |
112
+ | `_🔵 Trivial_` | Trivial | LOW (skip by default) |
113
+ | `_⚪ Info_` | Info | LOW (informational, no action needed) |
114
+
115
+ Note: some older reviews may use `_🔵 Info_` instead of `_🔵 Trivial_`. Treat both as LOW.
116
+
117
+ #### Assertive vs chill mode
118
+
119
+ CodeRabbit has two profiles configured via `.coderabbit.yaml`:
120
+ - `profile: chill` (default) - lighter feedback, nitpicks are hidden
121
+ - `profile: assertive` - full feedback, includes nitpick comments
122
+
123
+ When reviewing a repo in `chill` mode, nitpick sections will not appear in the review body.
124
+
125
+ **CodeRabbit non-inline comments** (outside diff, duplicate, nitpick) are not posted
126
+ as inline review comments. They are embedded in the PR-level review body
127
+ (`pulls/$PR/reviews`) inside structured `<details>` blocks. Each section type
128
+ has its own block with file paths, line ranges, severity, and optional AI prompts.
129
+
130
+ See `coderabbit_parsing.md` for the full body structure and parsing guide.
131
+
132
+ **Duplicate comments** from CodeRabbit indicate an issue was already flagged in a
133
+ previous review and not fixed. Treat these as higher actual priority than their
134
+ severity label suggests.
135
+
136
+ ### Cursor Comments
137
+ ```
138
+ <!-- **High Severity** --> → HIGH
139
+ <!-- **Medium Severity** --> → MEDIUM
140
+ ```
141
+
142
+ ### Keyword Detection (Fallback)
143
+ When badges or HTML comments aren't present, infer from keywords:
144
+
145
+ | Keywords | Severity |
146
+ |----------|----------|
147
+ | security, vulnerability, injection, XSS, SQL | CRITICAL/HIGH |
148
+ | dangerous, unsafe, exploit | CRITICAL |
149
+ | performance, slow, O(n²) | HIGH |
150
+ | error handling, exception, catch | HIGH |
151
+ | unreachable, dead code, unused | MEDIUM |
152
+ | refactor, simplify, consolidate | MEDIUM |
153
+ | style, formatting, PEP, naming | LOW |
154
+ | import order, whitespace | LOW |
155
+
156
+ ---
157
+
158
+ ## Related Comments Detection
159
+
160
+ Comments are often related when:
161
+
162
+ 1. **Consequence relationship**: Comment B is a consequence of fixing Comment A
163
+ - Keywords: "consequence", "result of", "as mentioned above"
164
+
165
+ 2. **Same root cause**: Multiple comments about the same underlying issue
166
+ - Keywords: "root cause", "same issue", "related to"
167
+
168
+ 3. **Unreachable code**: After an exception handling fix, related `except` blocks may become unreachable
169
+ - Pattern: CRITICAL exception handling → MEDIUM unreachable code
170
+
171
+ 4. **Same function/method**: Comments within ~100 lines in the same file, where one is CRITICAL and others are MEDIUM/LOW
172
+
173
+ ---
174
+
175
+ ## Example: Exception Handling Pattern
176
+
177
+ Common scenario from Gemini reviews:
178
+
179
+ **Comment 1 (CRITICAL)**: Exception handling in `method_x()` needs refactoring:
180
+ - FileNotFoundError should fail-fast, not retry
181
+ - Generic exceptions need sleep to avoid busy-loop
182
+
183
+ **Comment 2 (MEDIUM)**: `except FileNotFoundError` block at line 186 is unreachable
184
+ → This is a CONSEQUENCE of fixing Comment 1
185
+
186
+ **Comment 3 (MEDIUM)**: `except FileNotFoundError` block at line 473 is unreachable
187
+ → Also a CONSEQUENCE of fixing Comment 1
188
+
189
+ **Resolution**: Fix Comment 1 first. Comments 2 and 3 will be automatically resolved.
190
+
191
+ ---
192
+
193
+ ## Gemini Config Reference
194
+
195
+ Gemini behavior is controlled by `.gemini/config.yaml`:
196
+
197
+ ```yaml
198
+ code_review:
199
+ threshold: LOW # Minimum severity to report
200
+ auto_fix: false # Whether to suggest auto-fixes
201
+ blocking: false # Whether reviews block merge
202
+ ```
203
+
204
+ When `threshold: LOW`, all severities are reported.
205
+ When `blocking: false`, reviews are advisory only.
206
+
207
+ ---
208
+
209
+ ## Workflow Integration
210
+
211
+ 1. **Fetch comments**: Parse severity from badge URLs in comment body
212
+ 2. **Sort by severity**: CRITICAL → HIGH → MEDIUM → LOW
213
+ 3. **Group related**: Use heuristics above
214
+ 4. **Process CRITICAL first**: These often resolve MEDIUM/LOW comments
215
+ 5. **Skip LOW if needed**: They're optional by definition
216
+
217
+ ---
218
+
219
+ ## References
220
+
221
+ - [Gemini Code Assist Documentation](https://cloud.google.com/gemini/docs/discover/code-assist)
222
+ - [GitHub PR Review API](https://docs.github.com/en/rest/pulls/comments)
package/skills/tdd-workflow/SKILL.md ADDED
@@ -0,0 +1,85 @@
1
+ ---
2
+ name: tdd-workflow
3
+ description: >-
4
+ 新需求 / 新功能 / 功能开发的 TDD 全流程。触发场景包括但不限于：
5
+ 「新需求」「新功能」「新特性」「新模块」「新增」「添加功能」「加功能」「加个功能」「加一个功能」「做一个功能」「开发一个功能」「实现一个功能」。
6
+ 「帮我开发」「帮我实现」「帮我写」「帮我做」「帮我搞」「帮我弄」「开发一下」「实现一下」「写一下」「做一下」「搞一下」「弄一下」。
7
+ 「需求来了」「有个需求」「来了个需求」「接到需求」「需求是」「要做」「需要做」「需要开发」「需要实现」「需要写」「要开发」「要实现」「要写」「要做」。
8
+ 「功能开发」「功能实现」「业务开发」「业务实现」「代码开发」「代码实现」。
9
+ 「修改代码」「改代码」「改一下」「改一改」「改一版」「改功能」「改一下功能」「修改功能」「调整一下」「调整功能」「优化一下」「重构一下」。
10
+ 「需求文档」「需求分析」「写需求」「需求设计」「方案设计」「设计方案」「出方案」。
11
+ 「开始开发」「开始写」「开始写代码」「开始编码」「开始做」「开工」「动手」「动手吧」「开始吧」「搞起」「开搞」。
12
+ 严格按：需求记录→确认版本→测试先行→基线回归→实现代码→全量回归→上线前回归，七步不可跳过。
13
+ ---
14
+
15
+ # TDD 开发流程
16
+
17
+ ⚠️ **本 Skill 已触发。第一句话必须输出：「🔧 已触发 `tdd-workflow`，按 TDD 七步流程开发...」然后严格按照以下步骤执行，不得跳过。**
18
+
19
+ 测试驱动开发，每次接收新需求时强制遵循。
20
+
21
+ ## 七步流程
22
+
23
+ ### 第 1 步：需求记录（留痕）
24
+
25
+ 在 `docs/` 目录下新建需求文档（HTML 格式，中文命名），记录：
26
+ - 需求背景
27
+ - 功能范围
28
+ - 验收标准
29
+ - 所属版本号（未说明则归「全量测试」）
30
+
31
+ ### 第 2 步：确认归属版本
32
+
33
+ 明确写入：「归属版本：XXX」或「归属范围：全量测试」。
34
+
35
+ ### 第 3 步：测试先行
36
+
37
+ ⚠️ 先写测试用例，再写业务代码：
38
+
39
+ | 类型 | 位置 |
40
+ |------|------|
41
+ | Go 后端 | `app/supply/`、`app/controller/` 下写 `_test.go` |
42
+ | 前端 UI | `admin_web/e2e/` 或 `user_web/e2e/` 下写 Playwright E2E |
43
+ | API 接口 | `scripts/regression-api-smoke.js` 加冒烟子命令 |
44
+
45
+ 然后在 `scripts/superpowers-regression-runner.js` 的 `TEST_CASES` 中注册新用例。
46
+ 测试用例描述、断言必须使用中文。
47
+
48
+ **测试用例编写规范**：
49
+ - 先写主流程（happy path），再写边界情况
50
+ - 必须模拟真实用户操作：打开页面 → 查看状态 → 点击/填写 → 提交 → 验证结果
51
+ - 覆盖：新建、编辑、删除、查看/搜索、状态流转、异常操作
52
+ - 每条测试用例必须附带对应步骤的截图
53
+
54
+ ### 第 4 步：跑基线回归
55
+
56
+ ⚠️ 改代码之前，先跑一次全量回归建立基线：
57
+
58
+ ```bash
59
+ pnpm run regression:open
60
+ ```
61
+ 确认改动前所有已有用例全部通过。
62
+
63
+ ### 第 5 步：实现业务代码
64
+
65
+ 按需求文档和测试用例实现功能，持续跑新增测试用例。
66
+
67
+ ### 第 6 步：跑全量回归
68
+
69
+ ⚠️ 改完代码后跑全量回归，确认：
70
+ - 新增用例全部通过
71
+ - 所有已有用例仍然通过
72
+
73
+ ### 第 7 步：上线前回归
74
+
75
+ ⚠️ 每次部署生产前，必须跑：
76
+ ```bash
77
+ node 上线回归测试点.js
78
+ ```
79
+
80
+ ## 重要规则
81
+
82
+ - ⚠️ AI 第一反应不是写代码，而是写需求文档 + 设计测试用例
83
+ - ⚠️ 改动必须有迹可循：需求文档 → 测试用例 → 回归报告 → 代码改动
84
+ - 如果用户说「直接改就行不用测试」，必须提醒测试是安全网
85
+ - 测试用例命名含需求关键词，方便追溯