initial commit

skills/academic-figure-reviewer.md

@@ -0,0 +1,75 @@
+# Academic Figure Reviewer
+
+用于审查或生成论文、技术报告、正式 slide 中的静态学术图。目标是让图可读、可复现、风格一致，并且能直接进入 LaTeX 或 slide。
+
+## Core Contract
+
+- 一个脚本只产出一张论文图。
+- 每张图同时输出 `.pdf` 和 `.png`。
+- 图中所有样式来自 named constants，不在 draw 函数里写 magic numbers。
+- 每个 Axes 都经过统一样式函数。
+- 不在 committed script 中调用 `plt.show()`。
+
+## Canonical Script Shape
+
+```python
+# Section 1: Imports
+# Section 2: Style Config
+# Section 3: Helpers
+# Section 4: Draw Functions
+# Section 5: Main
+```
+
+## Style Rules
+
+- 字体格式最多三种。大小变化、bold、italic 都算一种格式。
+- 不重叠。legend、tick label、axis label、subplot 之间必须有可见 whitespace。
+- 最小文字插入论文后应接近正文或 caption 可读大小。
+- 颜色和 marker 从固定 palette 顺序取，不临时发明颜色。
+- top/right spine 隐藏，保留 thin left/bottom spine。
+- 图例默认无边框，用 whitespace 组织，而不是画框。
+- 保存时使用 `bbox_inches="tight"` 和高 dpi PNG。
+
+## Review Inputs
+
+- 图像文件、matplotlib 脚本、或 figure description。
+- 目标载体：paper single-column / double-column / slide。
+- 图要支撑的 claim。
+
+## Output
+
+```md
+# Academic Figure Review
+
+## Claim
+
+## Blocking Issues
+
+## Major Issues
+
+## Minor Issues
+
+## Required Edits
+
+## Reproducibility Notes
+```
+
+## Checklist
+
+- 图的第一视觉焦点对应主 claim。
+- caption/title 说结论，不只说图类型。
+- 轴标签含单位。
+- legend 不遮挡数据。
+- tick label 不贴边、不挤、不旋转到难读。
+- palette 对色盲友好；不用只靠颜色编码。
+- 多子图共享风格、尺度和命名。
+- 脚本可重跑，输入数据路径清楚。
+- 输出 PDF 用于 LaTeX，PNG 用于预览或 slide。
+
+## Suggested Defaults
+
+- `FONTSIZE = 6.5` for single-column paper figures, then按目标模板微调。
+- line width 约 `0.7`。
+- marker size 约 `1.5`。
+- 颜色顺序：blue, red, green, purple, orange。
+- 对 CDF/line 图，优先清晰展示趋势和 tail，不用装饰性网格。

skills/benchmark-crime-auditor.md

@@ -0,0 +1,385 @@
+# Benchmark Crime Auditor
+
+用于审计计算机系统论文、技术报告、实验设计或具体性能 claim。核心参考 Gernot Heiser 的 “Systems Benchmarking Crimes”：https://gernot-heiser.org/benchmarking-crimes.html
+
+立场：误导性 benchmark 不是写作瑕疵，而是会破坏科研结论。没有证据时判定 `NEEDS EVIDENCE`，不要替作者假设实验是公平的。
+
+## Inputs
+
+必填：
+
+- 待审 artifact：论文 evaluation、实验设计、图表集合、日志摘要、或具体性能 claim。
+- 审查目的之一：
+  - `experiment-design-review`
+  - `pre-submission`
+  - `pre-release`
+  - `claim-spot-check`
+
+可选：
+
+- 目标 venue / 读者。
+- 原始实验脚本、日志、CSV、配置、机器规格。
+- context depth: `Low | Medium | High`，默认 `Medium`。
+
+## Output
+
+必须输出：
+
+- 1-3 条 headline claims。
+- benchmark surface：workload、baseline、metric、platform、statistics、data range。
+- 逐条 crime 审计表。
+- 按严重度排序的修复清单。
+- 总体建议：`Ship | Revise (Major) | Block`。
+
+判定：
+
+- `PASS`：artifact 中有足够证据支撑。
+- `FAIL`：artifact 明确违反。
+- `NEEDS EVIDENCE`：可能没问题，但 artifact 看不到证据。
+- `N/A`：不适用，必须写理由。
+
+严重度：
+
+- `Blocking`：影响 headline claim 的 FAIL；或 baseline/公平性/选择性 benchmark 伤害主结论。
+- `Major`：影响支撑性 claim 的 FAIL；或 headline claim 的 NEEDS EVIDENCE。
+- `Minor`：信息缺失但不改变主要结论；或支撑性 claim 的 NEEDS EVIDENCE。
+
+## Audit Table Template
+
+```md
+| Crime | Verdict | Severity | Evidence | Fix |
+|---|---|---|---|---|
+| 1.1 Not evaluating degradation | FAIL | Blocking | Fig. 6 only shows winning workloads | Add adversarial workload where mechanism predicts overhead |
+```
+
+## Crimes
+
+### 1. Selective Benchmarking
+
+#### 1.1 Not Evaluating Potential Performance Degradation
+
+气味：
+
+- 只展示新方法赢的场景。
+- 没有展示机制上可能会输的反向场景。
+- 只证明 progressive criterion，不证明 conservative criterion。
+
+应有证据：
+
+- 新方法提升目标场景性能。
+- 新方法不显著伤害其他重要场景；若伤害，说明 tradeoff 是否可接受。
+
+修复：
+
+- 补一个按机制预测会输的 workload。
+- 明确收益和退化的适用边界。
+
+#### 1.2 Benchmark Subsetting Without Strong Justification
+
+气味：
+
+- “representative subset”, “typical results”, “we report selected benchmarks”。
+- 用 benchmark suite 子集却报告 suite-level 平均。
+- 排除 benchmark 的原因是“跑不动”，但没有解释这如何限制结论。
+
+应有证据：
+
+- 被排除项清单。
+- 每个排除项的技术理由。
+- 不从子集推出全 suite claim。
+
+修复：
+
+- 跑全套；或逐项报告，不给整体平均。
+- 明确 claim 只覆盖已运行子集。
+
+#### 1.3 Selective Data Set Hiding Deficiencies
+
+气味：
+
+- x 轴刚到系统快崩前停止。
+- 负载范围不覆盖真实运行区间。
+- 只画低并发、低争用、低内存压力、低尾延迟区间。
+
+应有证据：
+
+- 参数范围覆盖真实 workload。
+- 覆盖 scaling knee 两侧。
+
+修复：
+
+- 延伸数据范围，报告崩点或收益消失区间。
+
+### 2. Improper Handling of Benchmark Results
+
+#### 2.1 Pretending Microbenchmarks Represent Overall Performance
+
+气味：
+
+- 用 IPC、syscall、memcpy、cache hit rate 等 micro metric 证明系统端到端更快。
+
+应有证据：
+
+- macro benchmark 或真实 workload。
+- micro result 只作为机制证据，而不是主结论。
+
+修复：
+
+- 补端到端 workload。
+- 将 micro result 降级为 breakdown/mechanism。
+
+#### 2.2 Throughput Degradation Is Not Equal to Overhead
+
+气味：
+
+- throughput 下降 x%，就写 overhead 是 x%。
+- 吞吐不变，就说 overhead 为 0。
+- 把额外 core、加速器、远端节点、batch window 当成免费资源。
+
+原则：
+
+- throughput 是外部观察量。
+- overhead 是单位有用工作的资源消耗。
+- 只有资源同等饱和时，吞吐变化才可能近似资源 overhead。
+
+应有证据：
+
+- CPU load、cycles/op、processing time per request、memory bandwidth、IOPS、queue depth、tail latency、energy/op 等资源账。
+- 对所有被使用的资源计费。
+
+修复：
+
+- 用 per unit useful work 重算 overhead。
+- 报告吞吐时同时报告完整资源利用率。
+
+#### 2.3 Downplaying Overheads
+
+子罪：
+
+- 2.3a 混淆百分比和百分点。`6% -> 13%` 不是增加 7% overhead，而是 overhead 超过翻倍。
+- 2.3b 分母选错。baseline 必须在分母中。`60s -> 80s` 是 `+33%` degradation，不是 `25%`。
+- 2.3c 创意算法。`0.39us -> 2.28us` 接近 6x，不应写成 82.89% slowdown。
+
+应有证据：
+
+- 写清公式。
+- 分母使用 baseline。
+- 同时给绝对数和相对数。
+
+修复：
+
+- 从原始数重算所有百分比。
+- 删除二阶相对数或 ratio of ratios。
+
+#### 2.4 No Indication of Significance
+
+气味：
+
+- 只有平均值。
+- 没有标准差、置信区间、error bar、trial 数。
+- 拟合线没有回归质量。
+
+应有证据：
+
+- 多次重复。
+- 标准差或置信区间。
+- 边界 claim 使用统计检验。
+- 确定性结果也应说明方差足够小。
+
+修复：
+
+- 重跑多 trial。
+- 报告 variance 和 trial protocol。
+
+#### 2.5 Arithmetic Mean Across Normalized Scores
+
+气味：
+
+- 对 normalized speedup/slowdown 用算术平均。
+
+应有证据：
+
+- normalized benchmark score 使用几何平均。
+- 或逐项报告，不聚合。
+
+修复：
+
+- 改用 geometric mean。
+- 报告每个 sub-benchmark。
+
+### 3. Using the Wrong Benchmarks
+
+#### 3.1 Benchmarking a Simplified Simulated System
+
+气味：
+
+- 模拟器假设刚好对方法有利。
+- 在模型中验证模型自己。
+
+应有证据：
+
+- 说明简化假设不影响被测指标。
+- 最好有真机验证或外部 sanity check。
+
+修复：
+
+- 上真实系统验证关键结果。
+- 明确模拟结论的迁移边界。
+
+#### 3.2 Inappropriate or Misleading Benchmarks
+
+气味：
+
+- 用单核 workload 证明多核 scalability。
+- 用 CPU-intensive benchmark 测网络栈/NIC overhead。
+- 使用没有线性或因果意义的指标。
+
+应有证据：
+
+- workload 的压力向量与 claim 对齐。
+- metric 与系统问题有因果关系或合理解释。
+
+修复：
+
+- 换成能压到目标瓶颈的 benchmark。
+- 删除科学意义不明的指标。
+
+#### 3.3 Calibration Set Equals Evaluation Set
+
+气味：
+
+- 模型标定和模型评估使用同一批 workload/data。
+
+应有证据：
+
+- calibration set 与 validation/evaluation set 完全不相交。
+
+修复：
+
+- 留 hold-out workload。
+- 重新报告预测准确性。
+
+### 4. Improper Comparison of Benchmark Results
+
+#### 4.1 No Proper Baseline
+
+气味：
+
+- 只比较两个虚拟化系统，不给 native baseline。
+- 只给新系统不同变体。
+- 没有 SOTA、理论上限、硬件上限或 unperturbed baseline。
+
+应有证据：
+
+- baseline 是读者判断好坏所需的真实参照。
+
+修复：
+
+- 补 native/SOTA/optimal/hardware-limit baseline。
+- 若无法补，缩小 claim。
+
+#### 4.2 Only Evaluate Against Yourself
+
+气味：
+
+- 只和自己旧版本比较。
+- 只和自己的 ablation 比较，却声称总体优越。
+
+应有证据：
+
+- 与 accepted standard 或当前外部最佳方法比较。
+
+修复：
+
+- 补外部 baseline。
+- 把 claim 改成 internal improvement。
+
+#### 4.3 Unfair Benchmarking of Competitors
+
+气味：
+
+- competitor 配置不详。
+- competitor 跑在 debug/default/suboptimal 配置。
+- 结果与公开数据不一致却没有解释。
+
+应有证据：
+
+- competitor 版本、commit、配置、参数、编译 flag。
+- 尽可能使用作者推荐配置；必要时联系原作者确认。
+
+修复：
+
+- 用公平配置重跑。
+- 公开配置和脚本。
+
+#### 4.4 Inflating Gains by Not Comparing Against SOTA
+
+气味：
+
+- 新论文仍锚定旧 baseline，忽略已有工作已经在该 baseline 上改进。
+- 声称 22% improvement，但当前 SOTA 已经有 20%。
+
+应有证据：
+
+- 与当前 SOTA 的 delta。
+
+修复：
+
+- 重新锚定到 SOTA。
+- 把 headline claim 改成真实增量。
+
+### 5. Missing Information
+
+#### 5.1 Missing Platform Specification
+
+应给：
+
+- CPU 型号、microarchitecture、core 数、频率。
+- 内存容量、配置、cache 层级。
+- NIC、switch、disk、accelerator 规格。
+- OS、kernel、hypervisor、compiler、runtime、library 版本。
+- 编译 flag、关键系统参数。
+
+#### 5.2 Missing Sub-Benchmark Results
+
+气味：
+
+- 只给 suite-level 几何平均。
+- 不展示每个 benchmark，掩盖 regression。
+
+修复：
+
+- 表格或 appendix 给每项结果。
+- 标出退化项。
+
+#### 5.3 Relative Numbers Only
+
+气味：
+
+- 只给 speedup、ratio、normalized value，没有绝对值。
+- 比较两个 overhead ratio。
+
+修复：
+
+- 相对数旁边给绝对数。
+- 删除 ratio of overheads 这类二阶相对。
+
+## Best Practice Checklist
+
+用于 `experiment-design-review`。
+
+- 系统开始计时前处于 quiescent 状态。
+- benchmark rig 纳入 regression test。
+- 文档记录命令、参数、版本、机器、时间。
+- 写入数据后读回校验；读取数据时验证正确性。
+- 每次 run 使用不同数据，避免 stale cache 或旧 block。
+- 同一数据点既连续测，也隔开测，检查缓存和干扰。
+- 测量顺序正向和反向都跑。
+- 不只用规则 stride 或 2 的幂；加入随机点和病理点，如 `2^n-1`, `2^n`, `2^n+1`。
+- 比较不同配置时使用完全相同的数据点。
+- 多次运行，检查标准差；异常方差要解释。
+- outlier 剔除必须有预先规则或统计程序。
+- 计时前有 warmup。
+- 用足够迭代次数降低时钟粒度影响。
+- 消除 loop overhead。
+- 必要时检查机器码，确认计时 loop 与预期一致。

skills/evaluation-narrative-reviewer.md

@@ -0,0 +1,58 @@
+# Evaluation Narrative Reviewer
+
+用于审查论文、报告或 slide deck 中 evaluation 的组织顺序。目标是让读者先看到端到端结论，再理解收益来源、机制、边界和成本。
+
+## Rule
+
+Evaluation 默认顺序：
+
+1. `headline`：端到端结果，读者真正关心的 outcome。
+2. `breakdown`：收益来自哪里。
+3. `mechanism`：为什么会发生，例如 predictor accuracy、cache hit、queueing delay。
+4. `ablation`：哪个设计选择有用。
+5. `sensitivity`：在什么条件下成立或失效。
+6. `cost`：overhead、资源消耗、tradeoff、failure case。
+
+不要从内部 metric 开始。内部 metric 只有在读者已经知道它服务于哪个端到端 claim 后才有意义。
+
+## Inputs
+
+- Evaluation 章节、图表列表、slide outline 或 PDF 摘要。
+- 论文主 claim。
+- 可选：目标 venue、读者、页数限制。
+
+## Output
+
+```md
+# Evaluation Narrative Review
+
+## Diagnosis
+
+## Recommended Order
+
+| Position | Artifact | Role | Question Answered | Edit |
+|---|---|---|---|---|
+
+## Missing Bridges
+
+## Concrete Edits
+```
+
+## Workflow
+
+1. 写出主 claim。
+2. 列出所有 evaluation artifact：figure、table、paragraph、slide。
+3. 给每个 artifact 标注 role：`headline / breakdown / mechanism / ablation / sensitivity / cost`。
+4. 检查第一个 artifact 是否是 `headline`。
+5. 对每个后续 artifact，写出它回答的自然追问。
+6. 检查标题和 caption 是否说发现，而不只是说 metric 名。
+7. 推荐更紧的顺序和具体修改动作。
+
+## Checklist
+
+- 第一张图或第一个结果是端到端或 reader-visible outcome。
+- 每个后续结果回答一个自然 follow-up question。
+- 内部 metric 出现前，它和主 claim 的关系已经建立。
+- ablation 不早于 headline。
+- sensitivity 和 cost 不被隐藏在 appendix，除非主文已承认边界。
+- title/caption 说 finding，例如 “X reduces p99 TTFT by 2.1x”，而不是 “TTFT CDF”。

skills/goal-first-tech-doc.md

@@ -0,0 +1,58 @@
+# Goal-First Tech Doc
+
+用于新写或重构技术文档。目标是让读者最快知道：这份文档为谁解决什么问题，做到什么算完成，如何最小复现。
+
+## Use When
+
+- 写 README、runbook、design note、tool usage、实验复现说明。
+- 把抽象说明改成可执行文档。
+- 压缩一份过长但重要的技术文档。
+
+不要用于：
+
+- 只修错别字。
+- 论文/slide/marketing 文案。
+- 技术正确性审查。
+
+## Required Inputs
+
+- 文档目标或现有草稿。
+- 目标读者。
+- 相关命令、配置、代码、路径或接口。
+
+## Output
+
+重写后的文档或提纲，必须包含：
+
+- Goal。
+- Prerequisites / Context。
+- Steps or Design。
+- 一个最小例子。
+- Caveats / Failure Modes。
+
+## Rules
+
+- 目标先于背景。
+- 信息先于修辞。
+- 删除不增加行动能力的句子。
+- 保留前提、约束、错误处理和边界条件。
+- 只要提到命令、接口、数据格式、目录结构，优先给最小例子。
+- 如果信息缺失但不阻塞，明确写假设。
+- 如果信息缺失会误导，先请求补充。
+
+## Preferred Shapes
+
+短任务文档：
+
+1. Goal
+2. Steps
+3. Example
+4. Caveats
+
+短设计文档：
+
+1. Goal
+2. Constraints
+3. Design
+4. Example
+5. Tradeoffs

skills/research-paper-reviewer.md

@@ -0,0 +1,129 @@
+# Research Paper Reviewer
+
+用于审查计算机系统方向论文、proposal、技术报告或单个 section。默认不做全面泛审；用户应声明 review purpose。未声明时，先问 purpose。
+
+## Supported Purposes
+
+| Purpose | 回答的问题 |
+|---|---|
+| `thesis-clarity` | 核心论点是否一句话说得清？ |
+| `problem-importance` | problem 是否真实、重要、端到端相关？ |
+| `derivation-and-evidence` | 推导是否符合第一性原理，证据是否支撑 claim？ |
+| `novelty` | 与已有工作相比，差异是否真实且足够？ |
+| `simplicity` | 方法是否过度设计？ |
+| `writing-kaashoek-style` | 写作是否短、直接、先结论后理由？ |
+| `typos-and-references` | 是否有明显 typo、引用或交叉引用问题？ |
+
+可组合多个 purpose，例如 `problem-importance + novelty`。按顺序分别输出。
+
+## Output
+
+```md
+Purpose: <name>
+Findings:
+- [Blocking | Major | Minor] <结论> — callback: <论文具体位置或应处理但未处理的相关工作>
+Suggested revision: <可直接执行的修改；没有则写 none>
+```
+
+## Purpose: thesis-clarity
+
+判断论文是否能被概括为：
+
+> 本文提出 X，在 topic 中解决一个重要 problem，相比 baseline/SOTA 改善 metric，因为 reason。
+
+检查：
+
+- 是否能从 abstract/intro 抽出 X、topic、problem、baseline/SOTA、metric、reason。
+- X 是否真的针对该 problem。
+- 是否在讲清 problem 前过早讲 solution。
+- research question 是否具体，而不是“提升性能/效率/准确率”。
+
+任一核心要素缺失，默认 `Blocking`。
+
+## Purpose: problem-importance
+
+检查：
+
+- topic 是否具体，而不是过大的领域标签。
+- problem 是否真实存在于实际系统、工作负载或资源约束中。
+- 没有解决该 problem 会造成什么实际后果。
+- problem 是否是端到端 bottleneck，还是只优化占比极小的组件。
+- metric 是否真正量化了该 problem。
+- 影响范围是否足够：系统、应用、用户、工作负载、部署场景。
+
+## Purpose: derivation-and-evidence
+
+检查 claim -> reason -> evidence -> warrant 链条。
+
+### Claim
+
+- 核心 claim 是性能、成本、可扩展性、可靠性、可用性，还是机制理解。
+- claim 是否明确写出，而不是让 reviewer 猜。
+
+### Reason
+
+- 为什么认为 claim 成立。
+- 关键 reasons 是否独立，是否偷换概念。
+- 让 solution work 的关键 technique 和 assumption 是否被明确写出。
+
+### Evidence
+
+- 实验假设是否清楚，是否接近真实环境。
+- baseline 是否足够强，比较是否公平。
+- 是否覆盖不同配置、规模、工作负载。
+- 指标是否对应 problem。
+- 结果是否稳定，而非只展示 best case。
+- 是否有 ablation 证明收益来自核心技术。
+- 是否有 sensitivity 说明何时成立、何时失效。
+
+### Warrant
+
+- evidence 到 claim 的推理是否完整。
+- 是否把观察到的结果写成机制解释。
+- 是否把部分 benchmark 成立写成普遍成立。
+- 是否排除替代解释：调参、实现差异、配置差异、benchmark 偏置。
+
+审阅单个非 intro/abstract section 时，默认只跑此 purpose。
+
+## Purpose: novelty
+
+检查：
+
+- 核心差异在哪里：设计思路、实现方式、场景约束、资源模型，还是只是调参。
+- 与最相关已有工作相比，新挑战是否真实。
+- end-to-end 收益是否由核心差异带来。
+- 已有方法合理调整后是否可能达到类似效果。
+- 是否漏掉必须比较或必须引用的 competing method。
+
+## Purpose: simplicity
+
+检查：
+
+- 方法复杂度是否由 problem 本身驱动。
+- 是否有可删除组件、阶段、参数或特殊 case。
+- 是否存在“目标很小，机制很重”的不匹配。
+- 如果能简化，给出具体假设：去掉 X 后还应保留哪些收益。
+
+## Purpose: writing-kaashoek-style
+
+写作规则：
+
+- 先结论，再理由，再证据。
+- 句子短，一句一个意思。
+- 每段第一句就是 point。
+- 一段只讲一件事。
+- 数据和名词优先于形容词。
+- 早定义术语，不 use-before-define。
+- 删除 “we believe”, “it is important to note that”, “significantly” 这类软话，除非后面立刻给数字。
+
+若改写段落，输出 `before / after`；after 必须更短、更直接。
+
+## Purpose: typos-and-references
+
+检查：
+
+- 拼写、时态、单复数、标点。
+- 图表编号、section 编号、交叉引用。
+- 引用格式一致性。
+- 应引而未引的关键工作。
+- venue、年份、作者、系统名是否明显错误。