# Roll 技能选择指南

快速选择正确的技能或工具。

## 核心技能

| 用户意图 | 技能 | 说明 |
|---------|------|------|
| **"不确定怎么做"** / **"有几个方案"** | `roll-design` | 探索方案、比较选项、人工决策 |
| **"帮我做一个..."** / **"实现 US-001"** / **"修 FIX-001"** | `roll-build` | 万能入口：US-XXX 故事模式、FIX-XXX 修复模式、自由文本飞行模式——一个技能全覆盖 |
| **"这个逻辑很关键"** / **"涉及支付"** | `roll-spar` | 对抗式 TDD，高风险场景激活 |
| **"修个 bug"** / **"改文案"** | `roll-fix` | 快速修复，无需完整工作流 |
| **"规划需求"** / **"拆成故事"** | `roll-design` | 仅规划，不实现，输出 BACKLOG.md |
| **"并行跑多个 Action"** | `roll-build` | 拆分 Action 后自动判断是否并行 |
| **"交付了什么 / 队列里还有什么？"** | `roll status` / `roll loop cycle` / Story 报告 | CLI-first 交付状态、cycle 轨迹和按 Story 收口的证据 |
| **"调试这个页面"** | `roll-debug` | 深度诊断，采集日志/网络/DOM |

## 支撑技能

| 场景 | 技能 | 触发时机 |
|------|------|---------|
| 代码自审 | `roll-.review` | Commit 前，或手动触发 |
| 生成变更日志 | `roll-.changelog` | 成功 Deploy 后自动触发 |
| QA 测试参考 | `roll-.qa` | 写测试时参考 |
| 意图澄清 | `roll-.echo` | 用户输入模糊或不清晰时自动激活 |
| 文档/产品一致性审计 | `roll-doc-audit` | 核对 README、指南、网站、CLI help、文档与真实实现；需要时建索引、补缺口 |

## roll-doc-audit —— 文档/产品一致性审计

`roll-doc-audit` 先核对用户可见文档表面与真实行为: README、指南、网站、CLI help、
测试和源码。需要文档盘点时,它仍运行四个 phase——扫描/索引 → 缺口分析 → 填充 →
报告——外加深度读取的 **Phase 3b**。Phase 3 填充目录级缺口;Phase 3b 构建完整
项目符号表,侦测目录级填充单独无法发现的 **6 类跨目录主题**:

| 主题 | 触发条件 | 输出 |
|------|----------|------|
| 数据流 / 调用链 | import 链跨越 ≥ 3 个源目录 | `docs/data-flows.md` |
| 状态机 | `*State` / `*Status` 枚举被 ≥ 2 个文件引用 | `docs/state-machines.md` |
| 外部集成 | 存在 `fetch` / `axios` / `*_URL` 常量 | `docs/integrations.md` |
| 部署管线 | 存在 CI 配置文件加部署 URL 模式 | `docs/deployment.md` |
| Agent 入口 | 无 `AGENTS.md` 且源码根有 ≥ 3 个子目录 | `AGENTS.md` |
| 高引用目录 | 某目录被 ≥ 5 个源文件引用 | `<dir>/README.md` |

`$roll-doc-audit --dry-run` 运行 Phase 1–2 并打印 Phase 3 / 3b 计划而不写文件;
`$roll-doc-audit --force` 即便目标已存在也重新生成草稿。完整指南见
[roll-doc-audit.md](roll-doc-audit.md)。

## 快速决策树

```
用户输入
    |
+----------------------+
| "不确定方案？"        |--> roll-design
+----------------------+
    | 否
+----------------------+
| "一句话需求？"        |--> roll-build（飞行模式）
+----------------------+
    | 否
+----------------------+
| "有 US-XXX ID？"     |--> roll-build（故事模式）
+----------------------+
    | 否
+----------------------+
| "有 FIX-XXX ID？"    |--> roll-fix
+----------------------+
    | 否
+----------------------+
| "修 bug？"           |--> roll-fix
+----------------------+
    | 否
+----------------------+
| "规划/拆分？"        |--> roll-design
+----------------------+
    | 否
+----------------------+
| "高风险逻辑？"       |--> roll-spar
+----------------------+
    | 否
  人工判断
```

## Review Score（US-SKILL-010..014, FIX-343）

skill 不自评。工作 agent 绝不给自己的故事打分；**Review Score** 是 runner 侧的
同行评审产物，由一个全新独立会话里的 Reviewer 产出（绝非 builder 的子 agent）。
`roll-build` / `roll-fix` cycle 交付后，runner 拉起全新会话的 Reviewer，写一条
结构化 Review Score 笔记进故事的卡片文件夹（US-META-008——卡片文件夹是故事唯一的家；
平铺的 `.roll/notes/` 留给项目日记与迁移前的历史档，看板趋势与故事档案双源合并读）：

```
.roll/features/<epic>/US-AUTH-001/notes/2026-05-29-roll-build-US-AUTH-001-1717000000.md
.roll/features/<epic>/FIX-072/notes/2026-05-29-roll-fix-FIX-072-1717000123.md
```

每条笔记是 YAML frontmatter + 评审理由：

```markdown
---
skill: roll-build
story: US-AUTH-001
score: 8
verdict: good
ts: 2026-05-29T03:14:15Z
---

故事干净交付,AC 全部命中。auth-cookie 测试 TCR 重试一次(setup 漏初始化)。
Peer review 有一条 nit,inline 解决。
```

`roll loop status` 在 ROLLUP 区块底部汇总趋势：

```
review-score: mean 7.8 / min 4 / redo 2 (last 14)
```

`redo` 计入 `verdict: regression` 和 `verdict: ok` 且 `score < 6` 的
低置信交付——两者都提示该轮 cycle 值得回看。mean 和 min 覆盖整个
窗口，避免一次糟糕 cycle 被平均掩盖。

The trend line shows mean, minimum, and `redo` count (regression
verdicts plus low-confidence "ok"s) for the last 14 Review Score notes.

这些笔记是 `.roll/` 的一部分，跟代码一起提交，质量轨迹在不同机器、
不同协作者之间都可复现，从项目历史里直接可见。

## 新增 skill

一个 skill 就是 `skills/<name>/` 目录下的一个 `SKILL.md`，其 YAML frontmatter
至少声明 `name` 和 `description`。注册新 skill 按以下步骤走——你永远不需要手工
维护一份能力清单：

1. 创建 `skills/<name>/SKILL.md`，写好 frontmatter（`name`、`description`、
   `license`，以及 `allowed-tools`——见下文）。
2. 重新生成能力清单：

   ```bash
   roll setup skills
   ```

   该命令重新扫描每个 `skills/*/SKILL.md`，从 frontmatter 重写 `guide/skills.md`。
   `guide/skills.md` 是**生成产物**——文件头写明
   `GENERATED by roll setup skills — do not edit by hand`。新增或删除 skill 后，
   下一次重生成会自动反映；切勿手工编辑 `guide/skills.md`。
3. 把新建的 `SKILL.md` 和重新生成的 `guide/skills.md` 一起提交。

### 漂移防护

提交到仓库的清单不会与实际 skill 悄悄漂移：

- `roll doctor skills` 重新扫描，若 `guide/skills.md` 与 `skills/*/SKILL.md` 不一致
  就失败（非零退出并打印 diff）。CI 跑这道关卡，手改或漏跑重生成都会在合并前被抓住。
- `roll doctor` 在 skills 区块里，当清单过期时打印一条不致失败的提醒，作为本地
  「记得跑 `roll setup skills`」的提示。

扫描兼容 bash 3.2（基于 awk 的解析器；不用 `declare -A`、`mapfile` 或 `${var^^}`），
因此能在 macOS 系统自带 bash 上运行。

## 声明工具范围（`allowed-tools`）

每个 `SKILL.md` 的 frontmatter 都应声明一行 `allowed-tools`，列出该 skill 被允许
使用的工具：

```yaml
---
name: roll-design
license: MIT
allowed-tools: "Read, Edit, Write, Glob, Grep, Bash(git:*), WebSearch, WebFetch, Skill"
description: ...
---
```

- **怎么写**：用逗号分隔列出该 skill 实际需要的工具（如
  `Read, Edit, Write, Glob, Grep`），能收窄就收窄 Bash——用 `Bash(git:*)` 这种 glob
  形式，而不是放开无限制的 `Bash`。
- **为何要写**：声明把每个 skill 意图使用的工具面记录下来，使工具范围逐 skill 可审计、
  可评审，且与整份清单约定一致。
- **对 Roll 是什么**：仅是**声明 + lint**。Roll 把声明呈现出来并检查其存在性；工具的
  真正**强制权（enforcement）**在内层 agent harness，不在 Roll。写 `allowed-tools`
  本身并不会沙箱化该 skill。

## 自动触发关键词

| 技能 | 触发关键词 |
|------|----------|
| `roll-design` | 讨论、比较方案、怎么选、权衡、不确定用哪个、设计、规划、拆分、写故事、需求分析 |
| `roll-build` | 帮我做、加个功能、改一下、重构、实现 US-、做这个 story、做这个需求、并行、同时开发 |
| `roll-fix` | 修个 bug、改文案、调颜色、报错了、修复 |
| `roll-spar` | 对抗式、攻防、高风险、核心逻辑、支付、权限、安全 |
| `roll-debug` | 调试、诊断、页面有问题、排查 |