flaggems-pr-review-flagos

FlagGems PR Review Skill

作为 reviewer 角色审查 FlagGems 算子 PR。支持审查别人的 PR，也支持提交前自审。

Rules

1. 先拉取完整 diff — 必须获取 PR 所有变更文件和完整内容后再开始审查
2. 逐文件检查 — 按 kernel → 注册 → yaml → test → benchmark 顺序检查
3. 标注严重级别 — error（必须修）、warning（应该修）、suggestion（建议）
4. 不重复标记 — 同一位置的同一问题只标记一次
5. 给出修复建议 — 每条 finding 附带具体的修复方式
6. 原子提交 — 所有 inline comments 合并为一个 review 提交（一次通知）
7. 只审格式规范，不审算子正确性 — Skill 聚焦于格式、命名、注册、文件结构等规范性问题。算子实现的正确性（Triton API 用法、数学逻辑、backward 实现等）不在 scope 内，由 CI 测试覆盖

Environment

环境变量	必需	说明	默认值
GH_TOKEN	是	GitHub Personal Access Token	—
FLAGGEMS_REPO	否	FlagGems 仓库本地路径（未设置时使用当前目录）	—

每次新会话需确保环境已配置（禁止硬编码路径）。

Workflow

Phase -1: 环境验证（每次会话必须执行）

在开始审查前，必须按顺序验证以下配置。任何一项失败都要询问用户，不要自己做决策（如自动克隆仓库）。

1. 验证 GH_TOKEN

gh auth status

• 成功：继续下一步
• 失败：提示用户 请先运行 gh auth login 或设置 GH_TOKEN 环境变量，停止执行

2. 验证仓库位置

# 优先使用 FLAGGEMS_REPO
if [ -n "$FLAGGEMS_REPO" ]; then
  cd "$FLAGGEMS_REPO" && git rev-parse --show-toplevel
else
  # 否则检查当前目录
  git rev-parse --show-toplevel 2>/dev/null || echo "not in git repo"
fi

• 成功：记录仓库路径，继续下一步
• 失败：询问用户提供仓库路径，提供以下选项：
  • 输入 FlagGems 仓库的绝对路径
  • 如果 /tmp/FlagGems 存在且是有效仓库，询问是否使用
  • 不要自动克隆仓库

3. 验证 remote 配置

cd <repo_path>
git remote -v | grep -iE "FlagGems|flaggems"

• 成功：确认这是 FlagGems 仓库，继续
• 失败：警告用户 当前仓库不是 FlagGems，请确认路径是否正确，询问是否继续

4. 记录工作目录

export REVIEW_WORK_DIR=<validated_repo_path>
cd "$REVIEW_WORK_DIR"

只有所有验证通过后，才进入 Phase 0。

---

Phase 0: 确定目标 + 选择模式

# 审查别人的 PR（传入 PR number）
gh pr view <PR_NUMBER> --json title,headRefName,files

# 自审模式（从当前分支 diff）
git log --oneline upstream/master..HEAD

必须询问用户选择发布模式：

模式	说明
直接发送	Review 完成后自动发布到 GitHub（适合已确认规则无误时）
预览确认（默认）	先展示 findings 给用户，用户确认后再发布到 GitHub
仅本地	只输出到 terminal，不发布到 GitHub（适合自审）

如果用户未明确指定，默认使用预览确认模式。

Phase 1: 获取数据

# PR 模式
python scripts/fetch_pr_diff.py <PR_NUMBER>

# 自审模式
python scripts/fetch_pr_diff.py --local --base upstream/master

输出 JSON 包含：operator name、changed files（path + patch + full content）、commits

Phase 2: 格式检查

# PR 模式
python scripts/review_operator.py <PR_NUMBER> --json > findings.json

# 自审模式
python scripts/review_operator.py --local --json > findings.json

运行 31 条结构化规则（详见 references/review-rules-structural.md），输出 findings JSON。

这是 skill 的核心功能，只检查格式规范，不检查算子正确性。

模型不需要做任何额外的人工判断或代码分析，直接使用脚本输出的 findings 即可。

Phase 3: 发布 Review（必须执行）

此步骤为 workflow 的必要终点，不可跳过。

预览确认模式（默认）：

1. 先向用户展示完整的 findings 报告（表格形式）
2. 询问用户："确认发送到 GitHub？" 或 "需要修改？"
3. 用户确认后执行发布：

python scripts/post_review.py <PR_NUMBER> --findings findings.json

直接发送模式：

python scripts/post_review.py <PR_NUMBER> --findings findings.json

仅本地模式：

python scripts/post_review.py <PR_NUMBER> --findings findings.json --dry-run

展示结果后结束，不发布到 GitHub。

发布行为：

• 脚本将 findings 映射为 GitHub review：
  • 有 file + line 的 → inline comment（定位到 diff 具体位置）
  • 无具体 line 的 → review body
  • 有 error → 自动 REQUEST_CHANGES；无 error → COMMENT
• 所有 comments 合并为一个 review 原子提交（PR 作者只收一个通知）

检查规则速览

结构化检查（31 条）

所有检查由 review_operator.py 自动执行，模型只需使用脚本输出的结果。

类别	Rule ID	检查内容
Kernel	KERNEL_HEADER	KernelGen 首行
Kernel	KERNEL_NO_PRINT	无 print()
Kernel	KERNEL_NO_DUP_FUNC	无重复函数
Kernel	KERNEL_NO_FALLBACK	无 torch.op() 递归
Kernel	KERNEL_NO_PRIVATE_API	无 torch._xxx
Kernel	KERNEL_NO_IS_CUDA	禁止 is_cuda，用 flag_gems.device
Kernel	KERNEL_AUTOTUNE_CONFIG	autotune config 不硬编码
Kernel	KERNEL_LOGGER_FORMAT	logger 须用 "GEMS OP_NAME" 格式
注册	REG_OPS_INIT	ops/init.py 注册 + 字母序
注册	REG_FULL_CONFIG	_FULL_CONFIG 正确注册
注册	REG_YAML_COMPLETE	yaml 字段完整
注册	REG_YAML_UNIQUE	yaml id 不重复
注册	REG_CONSISTENCY	yaml ↔ _FULL_CONFIG 一致
测试	TEST_MARK	mark 与 yaml id 一致
测试	TEST_IMPORT	相对导入
测试	TEST_ASSERT	使用 gems_assert_close/equal
测试	TEST_NO_RTOL	无 rtol 参数
测试	TEST_NO_PRINT	无 print()
测试	TEST_TO_REFERENCE	ref 计算须用 to_reference()
Bench	BENCH_MARK	mark 与 yaml id 一致
Bench	BENCH_OP_NAME	op_name 与 yaml id 一致
Bench	BENCH_CLASS	使用标准封装类
Bench	BENCH_DTYPE	dtype 用常量或加注释
Bench	BENCH_FAIRNESS	torch/gems 测量范围一致
跨文件	DTYPE_HARDCODE	dtype 硬编码无注释
跨文件	SINGLE_OP	单算子 PR
跨文件	GIT_COAUTHOR	无 Co-Authored-By
跨文件	HYPERPARAMS	魔法数字须有注释
跨文件	CODE_QUALITY	行长/尾空白/EOF
完整性	TEST_EXISTS	注册算子必须有 test 文件
完整性	BENCH_EXISTS	注册算子必须有 benchmark 文件

References

• references/review-rules-structural.md — 31 条结构化规则详情 + 正反示例
• references/naming-conventions.md — 完整命名规则速查表
• references/registration-patterns.md — 三处注册的正确/错误 pattern
• references/benchmark-patterns.md — benchmark class 选择 + dtype 规则
• references/test-patterns.md — 测试文件规范