@namewta/speculo 0.1.3 → 0.1.4
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.
package/README.md
CHANGED
package/package.json
CHANGED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: retro
|
|
3
|
+
type: command
|
|
4
|
+
name: Speculo Retro
|
|
5
|
+
description: 复盘 Speculo commands/workflows 使用痛点，深度分析后经确认用 gh 提交改进 issue
|
|
6
|
+
keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Retro 命令
|
|
10
|
+
|
|
11
|
+
⚠️ **本命令在最后一步会通过 `gh` 向外部仓库创建 issue（外部写操作）。AI 必须先列出将要创建的 issue 清单与目标仓库并征求用户确认，确认前只输出计划，不调用 `gh`。**
|
|
12
|
+
|
|
13
|
+
## 归档路径模式
|
|
14
|
+
|
|
15
|
+
产物目录：`../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/`
|
|
16
|
+
|
|
17
|
+
报告文件：`../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/report.md`
|
|
18
|
+
|
|
19
|
+
- `<YYYY-MM-DD>` 使用当前日期。
|
|
20
|
+
- `<topic>` 从复盘范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `speculo`。
|
|
21
|
+
- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-retro-<topic>/report.md`。
|
|
22
|
+
- 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
|
|
23
|
+
|
|
24
|
+
## 调用的 skills
|
|
25
|
+
|
|
26
|
+
- `../skills/speculo-retro/SKILL.md` — 复盘 Speculo 使用痛点、深度分析并产出去重/分级/根因化的 issue-ready 提案时读取。
|
|
27
|
+
- `../skills/github-npm-ops/SKILL.md` — 需要用 `gh` 去重（`gh issue list --search`）与创建 issue（`gh issue create`）时读取，其 `references/issue-pr-triage.md` 提供检索、标签体系与命令模板。
|
|
28
|
+
|
|
29
|
+
## 执行步骤
|
|
30
|
+
|
|
31
|
+
1. 读取 `../skills/speculo-retro/SKILL.md`，按其规范采集信号（对话上下文、`../.speculo/commands/`、`../.speculo/<cat>/<change>/.status.json`、`../.speculo/.config/LESSONS.md`）并深度分析。
|
|
32
|
+
2. 用该 skill 产出规范化复盘结论：去重、分级、根因化的 issue-ready 提案清单，附丢弃/合并说明与每条处置建议。
|
|
33
|
+
3. 创建规范命令产物目录 `../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/`，把复盘结论写入 `report.md`。
|
|
34
|
+
4. **解析目标仓库**：默认框架反馈上游 `NAMEWTA/Speculo`；用户在请求中显式指定其他 `owner/repo` 时覆盖默认。无论如何，在调用 `gh` 前回显解析到的 `owner/repo`，让用户确认或改正。
|
|
35
|
+
5. **去重**：读取 `../skills/github-npm-ops/SKILL.md` 的 `references/issue-pr-triage.md`，对每条 `disposition: file-issue` 的提案用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索；命中语义重复的默认跳过并记录 `dup_of`，仅当用户明确要求才补提。
|
|
36
|
+
6. **外部写操作边界**：向用户展示将要创建的 issue 清单（标题、类型/优先级标签、正文摘要、目标 `owner/repo`）与去重结果，等待用户明确确认。没有确认时只输出计划，不调用 `gh`。
|
|
37
|
+
7. 用户确认后，按优先级倒序逐条执行 `gh issue create --repo <owner/repo> --title "<title>" --body "<body>" --label "<type>,<priority>[,<area>]"`（多行正文可用 `--body-file` 指向不保留的临时文件）。任一条失败时停止后续创建，报告已建/未建清单，不重复创建同一条。
|
|
38
|
+
8. 把每条提案的最终 issue 编号/URL 回写进 `report.md` 的「提交结果」小节；返回 `report.md` 路径、3-5 条复盘摘要和已创建 issue 链接清单。
|
|
39
|
+
|
|
40
|
+
## 产物模板（report.md）
|
|
41
|
+
|
|
42
|
+
> **服务命令：** `retro.md`
|
|
43
|
+
> **产物文件名：** `report.md`
|
|
44
|
+
|
|
45
|
+
```markdown
|
|
46
|
+
# Speculo Retro Report
|
|
47
|
+
|
|
48
|
+
## 复盘范围
|
|
49
|
+
[TODO: 本次复盘覆盖的 command / workflow 与时间/会话范围。]
|
|
50
|
+
|
|
51
|
+
## 信号来源
|
|
52
|
+
[TODO: 列出采集到的证据出处：对话节点、`.speculo/...` 产物路径、`.status.json` 字段、LESSONS。]
|
|
53
|
+
|
|
54
|
+
## 改进提案
|
|
55
|
+
[TODO: 按优先级倒序列出每条提案：标题 / 类型 / 优先级 / 根因 / 建议改动 / 验收标准 / 受影响资产 / 去重结论。]
|
|
56
|
+
|
|
57
|
+
## 丢弃与降级项
|
|
58
|
+
[TODO: 列出被合并、丢弃或降级为「仅记教训」的项及原因。]
|
|
59
|
+
|
|
60
|
+
## 目标仓库
|
|
61
|
+
[TODO: 解析到的 owner/repo 与用户确认结果。]
|
|
62
|
+
|
|
63
|
+
## 用户确认记录
|
|
64
|
+
[TODO: 记录用户对 issue 清单与目标仓库的确认原文摘要。]
|
|
65
|
+
|
|
66
|
+
## 提交结果
|
|
67
|
+
[TODO: 列出每条提案对应的 issue 编号/URL，或未提交原因（重复/失败/用户撤回）。]
|
|
68
|
+
```
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: speculo-retro
|
|
3
|
+
type: skill
|
|
4
|
+
name: Speculo Retro
|
|
5
|
+
description: 复盘 Speculo commands/workflows 使用过程中的痛点、问题与值得优化的地方，深度分析后产出去重、分级、根因化、可直接转成 GitHub issue 的规范化改进提案；当用户要求总结 Speculo 使用体验、收集框架反馈或把使用痛点整理成 issue 时使用。
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Speculo Retro
|
|
9
|
+
|
|
10
|
+
## 何时使用
|
|
11
|
+
|
|
12
|
+
当用户想复盘「用 Speculo 的 commands 或 workflows 时遇到的痛点、问题、值得优化的地方」，并希望把这些摩擦整理成规范化、可行动的框架反馈或 issue 时使用。
|
|
13
|
+
|
|
14
|
+
典型触发：
|
|
15
|
+
|
|
16
|
+
- “总结一下这次用 Speculo 踩的坑 / 卡点”
|
|
17
|
+
- “把使用痛点整理成可以提的 issue”
|
|
18
|
+
- “复盘 dev workflow 哪里别扭、哪里值得优化”
|
|
19
|
+
- “收集 Speculo 框架反馈”
|
|
20
|
+
|
|
21
|
+
本 skill 只负责**分析与规范化产出内容**：它去重、分级、根因化并起草 issue-ready 提案，把结果返回给调用方。它**不自行写文件、不调用 `gh`、不发布 issue**；落盘与提交由调用方 command / workflow 负责。
|
|
22
|
+
|
|
23
|
+
## 输入
|
|
24
|
+
|
|
25
|
+
- 当前对话上下文：本次会话用了哪些 command / workflow、卡在哪、绕了什么弯、重复了哪些动作
|
|
26
|
+
- `.speculo/commands/<run>/` 下的历史命令产物（report、snapshot、handoff）
|
|
27
|
+
- `.speculo/<cat>/<change>/` 下的 change 产物与 `.status.json`（`phase_history` 里的 `revisited`、`blocked`、长时间停滞都是摩擦信号）
|
|
28
|
+
- `.speculo/.config/LESSONS.md`（已沉淀的教训，用于去重与佐证）
|
|
29
|
+
- 可选：调用方提供的已存在 issue 列表或目标仓库上下文，用于跨提案去重
|
|
30
|
+
- 本 skill 自带分析与 issue 起草规范，已内化到 `references/`，分析时**不外读仓库 `docs/`**
|
|
31
|
+
|
|
32
|
+
## 输出
|
|
33
|
+
|
|
34
|
+
- 规范化复盘结论：每条 = 一个去重、分级、根因化的改进提案，字段对齐 GitHub issue（标题、类型/标签、证据、问题、建议改动、验收、受影响 asset）
|
|
35
|
+
- 提案清单，按优先级倒序排列
|
|
36
|
+
- 被合并或丢弃的低信号项说明（哪些重复、哪些更适合记入 `LESSONS.md` 而非提 issue）
|
|
37
|
+
- 每条标注「建议提 issue」或「仅记教训」的处置建议
|
|
38
|
+
- 全部以**返回内容**形式交给调用方写入其声明的 `.speculo/...` 路径；本 skill 不挑选持久化位置
|
|
39
|
+
|
|
40
|
+
## 执行步骤
|
|
41
|
+
|
|
42
|
+
1. **收集信号** —— 按 `references/friction-taxonomy.md` 的来源清单，扫描对话上下文、`.speculo/` 产物与 `LESSONS.md`，列出原始摩擦点。
|
|
43
|
+
2. **归类与去重** —— 按 taxonomy 把每个摩擦点归到类型（bug / friction / missing-capability / doc-gap / ergonomics），合并语义重复项。
|
|
44
|
+
3. **深度分析** —— 对每条做根因判断（是 asset 设计、持久化契约、文档还是工具问题），评估影响面与发生频率，按 `references/friction-taxonomy.md` 的优先级评分。
|
|
45
|
+
4. **过滤噪声** —— 只保留高信号、可行动项；低信号或一次性项标注为丢弃，或归入「仅记教训」。
|
|
46
|
+
5. **起草提案** —— 按 `references/issue-drafting-sop.md` 把每条规范化成 issue-ready 提案，并对照调用方提供的已存在 issue 做跨提案去重。
|
|
47
|
+
6. **返回结论** —— 把结构化提案清单、丢弃项与处置建议返回调用方；不自行写文件、不调用 `gh`。
|
|
48
|
+
|
|
49
|
+
## 渐进披露
|
|
50
|
+
|
|
51
|
+
- `references/friction-taxonomy.md`：确定信号来源、给摩擦点归类、按影响 × 频率评优先级、过滤噪声时读取。
|
|
52
|
+
- `references/issue-drafting-sop.md`：把改进提案规范化成 issue-ready 结构、对照已存在 issue 去重、生成给调用方 / `gh` 的交接字段时读取。
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Friction Taxonomy SOP
|
|
2
|
+
|
|
3
|
+
复盘 Speculo 使用摩擦时的信号来源、分类法、优先级评分与噪声过滤规范。
|
|
4
|
+
|
|
5
|
+
## 信号来源清单
|
|
6
|
+
|
|
7
|
+
按以下顺序采集原始摩擦点，每条记录**证据出处**（文件路径或对话节点），后续起草 issue 时要引用：
|
|
8
|
+
|
|
9
|
+
1. **当前对话上下文** —— 本次会话激活过的 command / workflow；用户在哪一步卡住、追问、返工；为绕开限制做了哪些手动动作；哪些指令被误解。
|
|
10
|
+
2. **命令产物** —— `.speculo/commands/<run>/` 下的 `report.md`、`snapshot.md`、`handoff.md`：里面记录的「验证失败原因」「未完成」「阻塞点」是一手摩擦。
|
|
11
|
+
3. **change 状态机** —— `.speculo/<cat>/<change>/.status.json` 的 `phase_history`：
|
|
12
|
+
- `revisited` —— phase 被迫回退，通常意味着流程设计或前置产物有缺口
|
|
13
|
+
- `blocked` —— 卡点，记录阻塞原因
|
|
14
|
+
- `skipped` —— phase 被跳过，可能是冗余或不适用
|
|
15
|
+
- `updated_at` 长期停滞 —— 流程让人不想推进
|
|
16
|
+
4. **change 产物正文** —— `prd.md`、`tdd-*.md`、`slices.md`、`diagnosis.md` 中显式写下的「待澄清」「风险」「TODO」。
|
|
17
|
+
5. **沉淀教训** —— `.speculo/.config/LESSONS.md`：已记录但尚未转成改进项的教训，用于去重与佐证频率。
|
|
18
|
+
6. **契约落差** —— 实际产物路径、frontmatter、命名是否偏离 `persistence-contract`：路径散落、缺字段、命名不合 `YYYY-MM-DD-<kebab>` 都是 bug 信号。
|
|
19
|
+
|
|
20
|
+
## 摩擦类型分类
|
|
21
|
+
|
|
22
|
+
每个摩擦点归且仅归一个**主类型**：
|
|
23
|
+
|
|
24
|
+
| 类型 | 含义 | 典型表现 |
|
|
25
|
+
|------|------|---------|
|
|
26
|
+
| `bug` | 资产行为不符合契约或文档 | 产物写错位置、`.status.json` 缺字段、命令覆盖了用户改动 |
|
|
27
|
+
| `friction` | 能用但别扭、步骤冗余、易错 | 反复手动改路径、phase 频繁 `revisited`、确认环节缺失 |
|
|
28
|
+
| `missing-capability` | 缺一个本该有的 command/workflow/skill | 用户手动拼凑某个反复出现的流程 |
|
|
29
|
+
| `doc-gap` | 文档缺失、过时或与实现不符 | 指引说一套、资产做另一套；找不到用法 |
|
|
30
|
+
| `ergonomics` | 命名、触发词、措辞、可发现性 | description 区分度差、关键词命中不到、术语不一致 |
|
|
31
|
+
|
|
32
|
+
## 优先级评分
|
|
33
|
+
|
|
34
|
+
优先级 = **影响面 × 发生频率**，落到四档（复用 `github-npm-ops` 标签体系）：
|
|
35
|
+
|
|
36
|
+
- 影响面：`broad`（影响所有使用者 / 破坏契约）｜`partial`（影响部分流程）｜`cosmetic`（轻微体验）
|
|
37
|
+
- 发生频率：`recurring`（多次出现 / 多来源佐证）｜`occasional`｜`one-off`
|
|
38
|
+
|
|
39
|
+
| 优先级 | 判定 |
|
|
40
|
+
|--------|------|
|
|
41
|
+
| `priority:critical` | 破坏契约、数据/产物丢失、覆盖用户改动 —— 无论频率 |
|
|
42
|
+
| `priority:high` | `broad` 影响且 `recurring`，或显著阻塞主流程 |
|
|
43
|
+
| `priority:medium` | `partial` 影响，或 `broad` 但仅 `occasional` |
|
|
44
|
+
| `priority:low` | `cosmetic`，或 `one-off` 且有 workaround |
|
|
45
|
+
|
|
46
|
+
## 噪声过滤规则
|
|
47
|
+
|
|
48
|
+
不是每个摩擦点都该变成 issue。按以下规则收敛：
|
|
49
|
+
|
|
50
|
+
- **合并** —— 语义重复的多条合成一条，频率累加（提升优先级佐证）。
|
|
51
|
+
- **丢弃** —— 纯属本次会话一次性、不可复现、或已被其他提案覆盖的，标注「丢弃」并写明原因。
|
|
52
|
+
- **降级为教训** —— 属于「用法/约定」而非「资产缺陷」的，建议记入 `LESSONS.md` 而非提 issue。
|
|
53
|
+
- **可行动性闸门** —— 无法描述出「改哪个 asset、怎么改、怎么验收」的，先标 `needs-design`，不要凭空提模糊 issue。
|
|
54
|
+
|
|
55
|
+
只把通过闸门、`priority:medium` 及以上、或 `recurring` 的高信号项推进到 issue 起草。
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Issue Drafting SOP
|
|
2
|
+
|
|
3
|
+
把通过过滤的改进提案规范化成 issue-ready 结构、对照已存在 issue 去重、生成交给调用方 / `gh` 的交接字段。
|
|
4
|
+
|
|
5
|
+
## 提案字段（issue-ready）
|
|
6
|
+
|
|
7
|
+
每条提案产出以下结构化字段，调用方据此写报告并据此调 `gh`：
|
|
8
|
+
|
|
9
|
+
```jsonc
|
|
10
|
+
{
|
|
11
|
+
"title": "string, 见标题规范",
|
|
12
|
+
"type": "bug | enhancement | documentation | feature-request",
|
|
13
|
+
"priority": "priority:critical | priority:high | priority:medium | priority:low",
|
|
14
|
+
"area": "string|null, 例 area:commands / area:workflows / area:skills / area:cli / area:contract",
|
|
15
|
+
"body": "string, 见正文结构",
|
|
16
|
+
"affected": ["相对路径，例 speculo/commands/archive.md"],
|
|
17
|
+
"evidence": ["证据出处，例 .speculo/dev/<change>/.status.json#phase_history"],
|
|
18
|
+
"disposition": "file-issue | record-lesson | drop",
|
|
19
|
+
"dup_of": "number|null, 疑似重复的已存在 issue 编号"
|
|
20
|
+
}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## 标题规范
|
|
24
|
+
|
|
25
|
+
- 用祈使句描述「要改成什么」，不是「哪里坏了」：`命名` 区分度差 ❌ → `enhancement: 提升 command description 在系统提示里的区分度` ✅
|
|
26
|
+
- 前缀对齐类型：`bug:` / `enhancement:` / `docs:` / `feature:`
|
|
27
|
+
- 单行、可独立读懂、不超过约 70 字，含受影响的 asset 名。
|
|
28
|
+
|
|
29
|
+
## 类型 → 标签映射
|
|
30
|
+
|
|
31
|
+
复用 `../github-npm-ops/references/issue-pr-triage.md` 的标签体系，每条至少一个**类型**标签，外加**优先级**，可选**领域**：
|
|
32
|
+
|
|
33
|
+
| 提案 type | issue 类型标签 |
|
|
34
|
+
|-----------|---------------|
|
|
35
|
+
| `bug` | `bug` |
|
|
36
|
+
| `friction` | `enhancement` |
|
|
37
|
+
| `missing-capability` | `feature-request` |
|
|
38
|
+
| `doc-gap` | `documentation` |
|
|
39
|
+
| `ergonomics` | `enhancement` |
|
|
40
|
+
|
|
41
|
+
不确定改动方向的额外加 `needs-design`。
|
|
42
|
+
|
|
43
|
+
## 正文结构
|
|
44
|
+
|
|
45
|
+
每条 issue body 用固定小节，占位符填实，禁止空话：
|
|
46
|
+
|
|
47
|
+
```markdown
|
|
48
|
+
## 问题
|
|
49
|
+
[一句话说清痛点 / 不符合预期的行为。]
|
|
50
|
+
|
|
51
|
+
## 证据
|
|
52
|
+
[引用具体出处：对话节点、`.speculo/...` 产物路径、`.status.json` 字段、文档段落。可附最小复现。]
|
|
53
|
+
|
|
54
|
+
## 根因
|
|
55
|
+
[判断是 asset 设计 / 持久化契约 / 文档 / 工具问题，指明根因而非表象。]
|
|
56
|
+
|
|
57
|
+
## 建议改动
|
|
58
|
+
[改哪个 asset、怎么改。给相对路径与具体方向，不要泛泛而谈。]
|
|
59
|
+
|
|
60
|
+
## 验收标准
|
|
61
|
+
[可验证的完成判据，例如断言、命名、契约符合点。]
|
|
62
|
+
|
|
63
|
+
## 受影响资产
|
|
64
|
+
[列出相关相对路径。]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## 去重
|
|
68
|
+
|
|
69
|
+
起草后、交给调用方提交前，对每条做去重判定：
|
|
70
|
+
|
|
71
|
+
1. 提取标题与根因的关键词。
|
|
72
|
+
2. 由调用方用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索（机制见 `../github-npm-ops/references/issue-pr-triage.md`）。
|
|
73
|
+
3. 命中语义重复：把 `disposition` 设为 `drop` 或在 `dup_of` 记录已存在编号，默认不重复提；仅当用户明确要求才补提。
|
|
74
|
+
|
|
75
|
+
## 交接契约
|
|
76
|
+
|
|
77
|
+
本 skill 只返回上面的结构化提案清单 + 丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。落盘到 `.speculo/commands/<run>/report.md` 与实际 `gh issue create` 由调用方 command 在用户确认后执行。
|