@namewta/speculo 0.2.7 → 0.2.9

package/template/vendor/matt-pocock/engineering/diagnosing-bugs/SKILL.md

@@ -1,134 +0,0 @@
----
-name: diagnosing-bugs
-description: 针对疑难 bug 和性能回归的诊断循环。当用户说"诊断"/"调试这个"，或报告有东西损坏/抛出异常/失败/变慢时使用。
----
-
-# 诊断 Bug
-
-针对疑难 bug 的规程。仅在明确有理由时才跳过阶段。
-
-探索代码仓时，阅读 `CONTEXT.md`（如果存在）以获取相关模块的清晰心智模型，并检查你接触区域的 ADR。
-
-## 阶段 1 — 构建反馈回路
-
-**这就是核心技能。** 其他一切都是机械性的。如果你针对 bug 有一个**紧凑的**通过/失败信号 — 一个在_此_ bug 上会变红的信号 — 你就会找到原因；二分查找、假设检验和插桩都只是消费它。如果你没有一个这样的信号，再盯着代码看也救不了你。
-
-在此投入不成比例的精力。**要激进。要有创意。拒绝放弃。**
-
-### 构建方式 — 按大致顺序尝试
-
-1. **失败测试**，位于能触及 bug 的任意缝合点 — 单元、集成、端到端。
-2. **Curl / HTTP 脚本**，针对正在运行的开发服务器。
-3. **CLI 调用**，带固定输入，将 stdout 与已知良好快照进行 diff。
-4. **无头浏览器脚本**（Playwright / Puppeteer）— 驱动 UI，对 DOM/控制台/网络进行断言。
-5. **回放捕获的追踪数据。** 将真实网络请求 / 负载 / 事件日志保存到磁盘；在隔离环境中通过代码路径回放。
-6. **一次性测试夹具。** 启动系统的最小子集（一个服务、模拟依赖），用单个函数调用来驱动 bug 代码路径。
-7. **属性 / 模糊测试循环。** 如果 bug 是"有时输出错误"，运行 1000 次随机输入，寻找故障模式。
-8. **二分查找夹具。** 如果 bug 出现在两个已知状态之间（commit、数据集、版本），自动化"在状态 X 启动、检查、重复"以便 `git bisect run`。
-9. **差分循环。** 通过旧版本 vs 新版本（或两种配置）运行相同输入，对输出进行 diff。
-10. **HITL bash 脚本。** 最后手段。如果必须由人工点击，用 `scripts/hitl-loop.template.sh` 驱动_他们_，使循环仍然结构化。捕获的输出反馈给你。
-
-构建了正确的反馈回路，bug 就修复了 90%。
-
-### 收紧回路
-
-将回路视为产品。一旦你有了_一个_回路，**收紧**它：
-
-- 能更快吗？（缓存设置，跳过无关初始化，缩小测试范围。）
-- 信号能更清晰吗？（针对具体症状断言，而非"没崩溃"。）
-- 能更确定性吗？（固定时间、种子随机数、隔离文件系统、冻结网络。）
-
-一个 30 秒的抖动回路比没有回路好不了多少；一个 2 秒的确定性回路才是紧凑的 — 这是调试的超能力。
-
-### 非确定性 bug
-
-目标不是干净的复现，而是**更高的复现率**。循环触发 100 次，并行化，增加压力，缩小时间窗口，注入 sleep。50% 抖动的 bug 是可调试的；1% 则不行 — 持续提高复现率直到可调试。
-
-### 当确实无法构建回路时
-
-停下来，明确说明。列出你尝试过的方法。向用户请求：(a) 访问能复现的任何环境，(b) 一个捕获的产物（HAR 文件、日志转储、核心转储、带时间戳的屏幕录制），或 (c) 添加临时生产环境插桩的许可。**不要**在没有回路的情况下进入假设阶段。
-
-### 完成标准 — 一个会变红的紧凑回路
-
-阶段 1 完成的条件是回路**紧凑**且**具备变红能力**：你能说出**一条命令** — 一个脚本路径、一个测试调用、一个 curl — 你**已经至少运行过一次**（粘贴调用及其输出），并且该命令满足：
-
-- [ ] **具备变红能力** — 它驱动实际的 bug 代码路径，并断言**用户的确切症状**，因此它能在此 bug 上变红，修复后变绿。不是"运行不出错" — 它必须能够_捕获这个具体的 bug_。
-- [ ] **确定性** — 每次运行结果一致（抖动 bug：固定的、足够高的复现率，如上所述）。
-- [ ] **快速** — 秒级，而非分钟级。
-- [ ] **Agent 可运行** — 你可以无人值守地运行它；只有在通过 `scripts/hitl-loop.template.sh` 时才能有人工参与。
-
-如果你发现自己在回路存在之前阅读代码来构建理论，**停下来 — 直接跳到假设正是本技能要防止的确切失败模式。** 没有变红能力的命令，就没有阶段 2。
-
-## 阶段 2 — 复现 + 最小化
-
-运行回路。看着它变红 — bug 出现。
-
-确认：
-
-- [ ] 回路产生了**用户**描述的故障模式 — 不是恰好碰巧在附近的另一个故障。错误的 bug = 错误的修复。
-- [ ] 故障可跨多次运行复现（或对于非确定性 bug，以足够高的复现率可调试）。
-- [ ] 你已捕获确切的症状（错误消息、错误输出、缓慢的计时），以便后续阶段验证修复确实解决了它。
-
-### 最小化
-
-一旦变红，将复现场景缩小到**仍能变红的最小场景**。**逐个**削减输入、调用者、配置、数据和步骤，每次削减后重新运行回路 — 只保留对故障有负载作用的部分。
-
-为什么费这个劲：最小复现场景缩小了阶段 3 的假设空间（值得怀疑的移动部件更少），并成为阶段 5 的干净回归测试。
-
-完成条件是**每个剩余元素都有负载作用** — 移除其中任何一个都会使回路变绿。
-
-在复现**且**最小化之前不要继续。
-
-## 阶段 3 — 提出假设
-
-在测试任何假设之前生成 **3-5 个排名假设**。单一假设生成会锚定在第一个看似合理的想法上。
-
-每个假设必须是**可证伪的**：陈述它的预测。
-
-> 格式："如果 <X> 是原因，那么 <改变 Y> 会使 bug 消失 / <改变 Z> 会使它更糟。"
-
-如果你无法陈述预测，这个假设只是感觉 — 丢弃或精炼它。
-
-**在测试之前向用户展示排名列表。** 他们通常拥有能立即重新排名的领域知识（"我们刚刚部署了对第 3 项的改动"），或知道他们已经排除的假设。低成本检查点，大幅节省时间。如果用户 AFK，不要等待 — 按你的排名继续。
-
-## 阶段 4 — 插桩
-
-每个探测必须映射到阶段 3 中的一个具体预测。**每次只改变一个变量。**
-
-工具偏好：
-
-1. **调试器 / REPL 检查**，如果环境支持。一个断点胜过十行日志。
-2. **针对性日志**，在能区分假设的边界处。
-3. 永远不要"记录一切然后 grep"。
-
-**用唯一前缀标记每条调试日志**，例如 `[DEBUG-a4f2]`。最后的清理只需一次 grep。未标记的日志保留；已标记的日志删除。
-
-**性能分支。** 对于性能回归，日志通常是错误的。替代方案：建立基线测量（计时夹具、`performance.now()`、分析器、查询计划），然后二分查找。先测量，后修复。
-
-## 阶段 5 — 修复 + 回归测试
-
-在修复**之前**编写回归测试 — 但仅当存在**正确的缝合点**时才这样做。
-
-正确的缝合点是指测试能在调用点处驱动**真实的 bug 模式**。如果唯一可用的缝合点太浅（bug 需要多个调用者时却只有单调用者测试，单元测试无法复现触发 bug 的调用链），在那里的回归测试会给出虚假的信心。
-
-**如果不存在正确的缝合点，这本身就是发现。** 记录下来。代码仓架构正在阻止锁定此 bug。将此标记给下一阶段。
-
-如果存在正确的缝合点：
-
-1. 将最小复现转为该缝合点处的失败测试。
-2. 看着它失败。
-3. 应用修复。
-4. 看着它通过。
-5. 对原始（未最小化的）场景重新运行阶段 1 的反馈回路。
-
-## 阶段 6 — 清理 + 事后分析
-
-宣布完成前必须完成：
-
-- [ ] 原始复现不再复现（重新运行阶段 1 的回路）
-- [ ] 回归测试通过（或缝合点的缺失已被记录）
-- [ ] 所有 `[DEBUG-...]` 插桩已移除（grep 该前缀）
-- [ ] 一次性原型已删除（或移至明确标记的调试位置）
-- [ ] 被证明正确的假设在 commit / PR 消息中陈述 — 以便下一个调试者学习
-
-**然后问：什么本可以预防这个 bug？** 如果答案涉及架构变更（没有好的测试缝合点、纠缠的调用者、隐藏的耦合），将具体情况移交给 `/improve-codebase-architecture` 技能。在修复**之后**提出建议，而非之前 — 你现在比开始时拥有更多信息。

package/template/vendor/matt-pocock/engineering/domain-modeling/ADR-FORMAT.md

@@ -1,47 +0,0 @@
-# ADR 格式
-
-ADR 存放在 `docs/adr/` 中，使用顺序编号：`0001-slug.md`、`0002-slug.md` 等。
-
-延迟创建 `docs/adr/` 目录 — 仅在需要第一个 ADR 时才创建。
-
-## 模板
-
-```md
-# {决策的简短标题}
-
-{1-3 句话：背景是什么，我们做了什么决策，以及为什么。}
-```
-
-就这样。一个 ADR 可以就是一个段落。其价值在于记录*已经*做出了决策以及*为什么* — 而不是填满各个部分。
-
-## 可选部分
-
-仅当它们真正增加价值时才包含这些。大多数 ADR 不需要它们。
-
-- **Status** 前置元数据（`proposed | accepted | deprecated | superseded by ADR-NNNN`）— 当决策被重新审视时有用
-- **Considered Options** — 仅当被拒绝的替代方案值得记住时
-- **Consequences** — 仅当需要指出非显而易见的下游影响时
-
-## 编号
-
-扫描 `docs/adr/` 中的最高现有编号，然后加 1。
-
-## 何时提供 ADR
-
-以下三个条件必须同时为真：
-
-1. **难以逆转** — 以后改变主意的成本是实质性的
-2. **没有上下文的话令人惊讶** — 未来的读者会看着代码想"他们到底为什么这样做？"
-3. **真实权衡的结果** — 确实存在替代方案，你基于特定原因选择了一个
-
-如果决策容易逆转，跳过它 — 你反正会逆转的。如果不令人惊讶，没人会想为什么。如果没有真正的替代方案，那就没有可记录的，除了"我们做了显而易见的事"。
-
-### 什么算作
-
-- **架构形态。** "我们使用 monorepo。" "写模型采用事件溯源，读模型投影到 Postgres。"
-- **上下文间的集成模式。** "Ordering 和 Billing 通过领域事件通信，而非同步 HTTP。"
-- **带来锁定效应的技术选择。** 数据库、消息总线、认证提供商、部署目标。不是每个库 — 只是那些需要花一个季度才能替换的。
-- **边界和范围决策。** "客户数据由 Customer 上下文拥有；其他上下文仅通过 ID 引用它。"明确的"不做"和"要做"同样有价值。
-- **有意偏离显而易见路径的决策。** "我们使用手动 SQL 而不是 ORM，因为 X。"任何合理读者会假设相反的情况。这些可以阻止下一个工程师"修复"一个刻意为之的东西。
-- **代码中不可见的约束。** "由于合规要求，我们不能使用 AWS。" "由于合作伙伴 API 合同，响应时间必须低于 200ms。"
-- **拒绝的原因不明显的被拒绝替代方案。** 如果你考虑了 GraphQL 而因微妙原因选择了 REST，记录下来 — 否则 6 个月后有人会再次建议 GraphQL。

package/template/vendor/matt-pocock/engineering/domain-modeling/CONTEXT-FORMAT.md

@@ -1,60 +0,0 @@
-# CONTEXT.md 格式
-
-## 结构
-
-```md
-# {上下文名称}
-
-{对该上下文是什么以及为什么存在的一两句话描述。}
-
-## Language
-
-**Order**：
-{对该术语的一两句话描述}
-_Avoid_: Purchase, transaction
-
-**Invoice**：
-发货后发送给客户的付款请求。
-_Avoid_: Bill, payment request
-
-**Customer**：
-下订单的个人或组织。
-_Avoid_: Client, buyer, account
-```
-
-## 规则
-
-- **要有主见。** 当同一概念存在多个词时，选择最好的那个，并将其他的列在 `_Avoid_` 下。
-- **定义保持精炼。** 最多一两句话。定义它是什么，而不是它做什么。
-- **仅包含特定于该项目上下文的术语。** 通用的编程概念（超时、错误类型、工具模式）即使项目广泛使用也不属于这里。添加术语前自问：这是该上下文独有的概念，还是一个通用编程概念？只有前者才属于这里。
-- **当自然形成聚类时，用子标题分组术语。** 如果所有术语属于一个单一的凝聚领域，扁平列表也可以。
-
-## 单上下文 vs 多上下文仓库
-
-**单上下文（大多数仓库）：** 在仓库根目录下一个 `CONTEXT.md`。
-
-**多上下文：** 在仓库根目录下一个 `CONTEXT-MAP.md` 列出各个上下文、它们的位置以及它们之间的关系：
-
-```md
-# Context Map
-
-## Contexts
-
-- [Ordering](./src/ordering/CONTEXT.md) — 接收并跟踪客户订单
-- [Billing](./src/billing/CONTEXT.md) — 生成发票并处理付款
-- [Fulfillment](./src/fulfillment/CONTEXT.md) — 管理仓库拣货和发货
-
-## Relationships
-
-- **Ordering → Fulfillment**：Ordering 发出 `OrderPlaced` 事件；Fulfillment 消费它们以开始拣货
-- **Fulfillment → Billing**：Fulfillment 发出 `ShipmentDispatched` 事件；Billing 消费它们以生成发票
-- **Ordering ↔ Billing**：共享 `CustomerId` 和 `Money` 类型
-```
-
-该 skill 会根据存在情况推断适用哪种结构：
-
-- 如果存在 `CONTEXT-MAP.md`，读取它以找到各个上下文
-- 如果只存在根目录下的 `CONTEXT.md`，则为单上下文
-- 如果两者都不存在，当第一个术语被确定时延迟创建一个根目录下的 `CONTEXT.md`
-
-当存在多个上下文时，推断当前主题与哪个上下文相关。如果不清楚，询问。

package/template/vendor/matt-pocock/engineering/domain-modeling/SKILL.md

@@ -1,74 +0,0 @@
----
-name: domain-modeling
-description: 构建和精炼项目的领域模型。当用户想要确定领域术语或通用语言、记录架构决策，或当其他技能需要维护领域模型时使用。
----
-
-# 领域建模
-
-在设计过程中积极构建和精炼项目的领域模型。这是*主动*规程 — 挑战术语、发明边界场景、并在决策结晶的那一刻立即写下词汇表和决策。（仅仅_阅读_ `CONTEXT.md` 获取词汇不是本技能 — 那是任何技能都可以做到的一行习惯。本技能用于当你正在_改变_模型，而不仅仅是消费它时。）
-
-## 文件结构
-
-大多数仓库只有一个上下文：
-
-```
-/
-├── CONTEXT.md
-├── docs/
-│   └── adr/
-│       ├── 0001-event-sourced-orders.md
-│       └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-如果根目录存在 `CONTEXT-MAP.md`，则仓库有多个上下文。该映射指向每个上下文所在的位置：
-
-```
-/
-├── CONTEXT-MAP.md
-├── docs/
-│   └── adr/                          ← 系统级决策
-├── src/
-│   ├── ordering/
-│   │   ├── CONTEXT.md
-│   │   └── docs/adr/                 ← 上下文特定的决策
-│   └── billing/
-│       ├── CONTEXT.md
-│       └── docs/adr/
-```
-
-延迟创建文件 — 仅当有内容可写时才创建。如果 `CONTEXT.md` 不存在，在第一个术语确定时创建。如果 `docs/adr/` 不存在，在第一个 ADR 需要时创建。
-
-## 会话期间
-
-### 对照词汇表挑战
-
-当用户使用的术语与 `CONTEXT.md` 中的现有语言冲突时，立即指出。"你的词汇表将 'cancellation' 定义为 X，但你似乎指的是 Y — 到底是哪个？"
-
-### 精炼模糊语言
-
-当用户使用含糊或重载的术语时，提出一个精确的规范术语。"你在说 'account' — 你指的是 Customer 还是 User？它们是不同的东西。"
-
-### 讨论具体场景
-
-当讨论领域关系时，用具体场景进行压力测试。发明探索边界情况的场景，迫使用户精确界定概念之间的边界。
-
-### 与代码交叉引用
-
-当用户陈述某事如何工作时，检查代码是否一致。如果发现矛盾，指出来："你的代码取消的是整个 Order，但你刚才说部分取消是可能的 — 哪个是正确的？"
-
-### 及时更新 CONTEXT.md
-
-当术语确定时，当场更新 `CONTEXT.md`。不要批量处理 — 发生时立即捕获。使用 [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md) 中的格式。
-
-`CONTEXT.md` 应该完全不包含实现细节。不要将 `CONTEXT.md` 当作规范、草稿纸或实现决策的仓库。它只是词汇表，别无其他。
-
-### 谨慎创建 ADR
-
-仅在以下三个条件全部满足时才提供创建 ADR：
-
-1. **难以逆转** — 以后改变主意的成本是有意义的
-2. **没有上下文会令人惊讶** — 未来的读者会疑惑"他们为什么这样做？"
-3. **真实权衡的结果** — 存在真正的替代方案，你出于特定原因选择了一个
-
-如果缺少任何一个条件，跳过 ADR。使用 [ADR-FORMAT.md](./ADR-FORMAT.md) 中的格式。

package/template/vendor/matt-pocock/engineering/grill-with-docs/SKILL.md

@@ -1,7 +0,0 @@
----
-name: grill-with-docs
-description: 一场无情的访谈，用于打磨计划或设计，同时在此过程中创建文档（ADR 和词汇表）。
-disable-model-invocation: true
----
-
-运行 `/grilling` 会话，使用 `/domain-modeling` 技能。

package/template/vendor/matt-pocock/engineering/implement/SKILL.md

@@ -1,15 +0,0 @@
----
-name: implement
-description: "基于规范或工单集实现一项工作。"
-disable-model-invocation: true
----
-
-基于规范或工单实现用户描述的工作。
-
-尽可能使用 /tdd，在预先商定的缝合点处进行。
-
-定期运行类型检查，定期运行单个测试文件，最后运行一次完整的测试套件。
-
-完成后，使用 /code-review 审查工作。
-
-将你的工作提交到当前分支。

package/template/vendor/matt-pocock/engineering/prototype/LOGIC.md

@@ -1,79 +0,0 @@
-# 逻辑原型
-
-一个小型交互式终端应用，让用户手动驱动状态模型。当问题与**业务逻辑、状态转换或数据形态**相关时使用 — 这类问题在纸面上看起来合理，但只有在通过真实案例推动时才会感到不对。
-
-## 何时适合使用这种形式
-
-- "我不确定这个状态机是否处理 X 然后 Y 的边界情况。"
-- "这个数据模型是否真的能让我表示……这种情况？"
-- "我想在写代码之前感受一下 API 应该是什么样子。"
-- 任何用户想要**按下按钮观看状态变化**的场景。
-
-如果问题是"这应该长什么样" — 走错分支了。请使用 [UI.md](UI.md)。
-
-## 流程
-
-### 1. 明确问题
-
-在写代码之前，写下你在为哪个状态模型和什么问题做原型。一段话，放在原型的 README 中或文件顶部的注释中。一个回答了错误问题的逻辑原型纯属浪费 — 明确问题以便稍后检查，无论用户是现在看着还是稍后回来离线查看。
-
-### 2. 选择语言
-
-使用宿主项目使用的任何语言。如果项目没有明显的运行时（例如文档仓库），则询问。
-
-匹配项目现有的工具约定 — 不要仅仅为了原型而添加新的包管理器或运行时。
-
-### 3. 将逻辑隔离在可移植模块中
-
-将实际逻辑 — 回答问题的部分 — 放在一个小的纯接口后面，这个接口可以提取出来稍后放入真实代码库。围绕它的 TUI 是一次性的；逻辑模块不应该是。
-
-正确的形态取决于问题：
-
-- **纯 reducer** — `(state, action) => state`。适合动作为离散事件且状态是单个值的情况。
-- **状态机** — 明确的状态和转换。适合"哪些动作在当前状态下是合法的"本身就是问题的一部分。
-- **一组在纯数据类型上的小函数。** 适合没有隐式当前状态的情况 — 只是转换。
-- **具有清晰方法面的类或模块**，当逻辑确实拥有持续的内部状态时。
-
-选择最适合所问问题的形态，*而不是*最容易连接到 TUI 的形态。保持纯：无 I/O、无终端代码、无用于控制流的 `console.log`。TUI 导入它并调用它；没有任何东西向相反方向流动。
-
-这就是让原型在其生命周期之后仍然有用的关键。当问题得到回答后，经过验证的 reducer / 状态机 / 函数集可以被提取到真实模块中 — TUI 外壳则被删除。
-
-### 4. 构建最小的 TUI 来暴露状态
-
-将其构建为**轻量级 TUI** — 在每个时钟周期，清除屏幕（`console.clear()` / `print("\033[2J\033[H")` / 等价方式）并重新渲染整个帧。用户应始终看到一个稳定的视图，而非不断增长的滚动日志。
-
-每帧有两个部分，按此顺序：
-
-1. **当前状态**，美化打印且便于 diff（每行一个字段，或格式化的 JSON）。使用**粗体**表示字段名或节标题，**暗色**表示不太重要的上下文（时间戳、ID、派生值）。原生 ANSI 转义码即可 — `\x1b[1m` 粗体，`\x1b[2m` 暗色，`\x1b[0m` 重置。除非项目中已有样式库，否则无需引入。
-2. **键盘快捷键**，列在底部：`[a] add user  [d] delete user  [t] tick clock  [q] quit`。粗体显示按键，暗色显示描述，或反之 — 读起来清晰即可。
-
-行为：
-
-1. **初始化状态** — 单个内存中的对象/结构体。启动时渲染第一帧。
-2. **一次读取一个按键（或一行）**，分发给变更状态的处理函数。
-3. **在每次操作后重新渲染**完整帧 — 不要追加，替换。
-4. **循环直到退出。**
-
-整个帧应能放在一屏内。
-
-### 5. 使其通过一条命令即可运行
-
-在项目现有的任务运行器（`package.json` scripts、`Makefile`、`justfile`、`pyproject.toml`）中添加一个脚本。用户应该运行 `pnpm run <prototype-name>` 或等价命令 — 永远不需要记忆路径。
-
-如果宿主项目没有任务运行器，直接将命令放在原型的 README 顶部。
-
-### 6. 交付
-
-将运行命令交给用户。他们自己驱动；有趣的时刻是当他们说"等等，这不应该是可能的"或"嗯，我以为 X 会不一样" — 那些是*想法*中的 bug，这正是整个目的。如果他们想要添加新动作，就添加。原型会演化。
-
-### 7. 捕获答案
-
-当原型完成其使命后，问题的答案就是唯一值得保留的东西。如果用户在旁，询问他们学到了什么。如果不在，在原型的旁边留下一个 `NOTES.md`，以便答案可以在原型被删除之前填写（或由你填写，如果你观察了整个会话）。
-
-## 反模式
-
-- **不要添加测试。** 需要测试的原型不再是原型。
-- **不要连接到真实数据库。** 使用内存存储，除非问题明确与持久化相关。
-- **不要泛化。** 不要"如果我们以后想支持 X 怎么办"。原型回答一个问题。
-- **不要将逻辑和 TUI 混在一起。** 如果 reducer / 状态机引用了 `console.log`、提示或终端转义码，它就不再可移植。将 TUI 作为纯模块上的一个薄外壳。
-- **不要将 TUI 外壳发布到生产环境。** 外壳是为从终端手动驱动而优化的。其背后的逻辑模块才是值得保留的部分。

package/template/vendor/matt-pocock/engineering/prototype/SKILL.md

@@ -1,30 +0,0 @@
----
-name: prototype
-description: 构建一次性原型来回答设计问题。当用户想要快速验证状态模型或逻辑是否感觉正确，或探索 UI 应该长什么样时使用。
----
-
-# 原型
-
-原型是**回答问题的一次性代码**。问题决定形态。
-
-## 选择分支
-
-识别正在回答哪个问题 — 从用户提示、周围代码或用户在线时通过询问来判断：
-
-- **"这个逻辑 / 状态模型感觉对吗？"** → [LOGIC.md](LOGIC.md)。构建一个微型交互式终端应用，将状态机推向难以在纸面上推理的用例。
-- **"这个应该长什么样？"** → [UI.md](UI.md)。在单一路由上生成几个截然不同的 UI 变体，通过 URL 搜索参数和浮动底栏切换。
-
-两个分支产生截然不同的产物 — 选错会浪费整个原型。如果问题确实模棱两可且用户不在线，默认选择更能匹配周围代码的分支（后端模块 → 逻辑；页面或组件 → UI），并在原型顶部陈述假设。
-
-## 适用于两者的规则
-
-1. **从一开始就是一次性的，并清楚标记。** 将原型代码放在它实际将被使用的位置附近（靠近它正在原型化的模块或页面旁边），这样上下文是明确的 — 但命名时让随意读者能看出它是原型，而非生产代码。对于一次性 UI 路由，遵循项目已有的任何路由约定；不要发明新的顶层结构。
-2. **一条命令运行。** 无论项目现有任务运行器支持什么 — `pnpm <名称>`、`python <路径>`、`bun <路径>` 等。用户必须能毫不费力地启动它。
-3. **默认不持久化。** 状态驻留在内存中。持久化是原型正在_检验_的东西，而非它应该依赖的东西。如果问题明确涉及数据库，用一个标记着"PROTOTYPE — 请清除我"的临时数据库或本地文件。
-4. **跳过润色。** 没有测试，没有超出使原型_可运行_的错误处理，没有抽象。重点是快速学到东西然后删除它。
-5. **呈现状态。** 每次操作后（逻辑）或每次变体切换时（UI），打印或渲染完整的相关状态，让用户看到什么发生了变化。
-6. **完成后删除或吸收。** 当原型回答了它的问题时，要么删除它，要么将已验证的决策整合到真实代码中 — 不要让它烂在仓库里。
-
-## 完成后
-
-_答案_是原型中唯一值得保留的东西。将其捕获到某个持久的地方（commit 消息、ADR、issue，或原型旁边的 `NOTES.md`），连同它所回答的问题。如果用户在线，这只是一个快速对话；如果不，留下占位符以便他们（或你，在下一轮）能在删除原型之前填上结论。

package/template/vendor/matt-pocock/engineering/prototype/UI.md

@@ -1,112 +0,0 @@
-# UI 原型
-
-在单个路由上生成**多个截然不同的 UI 变体**，通过一个浮动底栏切换。用户在浏览器中翻看各个变体，选择一个（或从每个变体中各取一些），然后丢弃其余。
-
-如果问题关乎逻辑/状态而非外观 — 走错分支了。请使用 [LOGIC.md](LOGIC.md)。
-
-## 何时适合使用这种形式
-
-- "这个页面应该长什么样？"
-- "我想在提交之前看看这个仪表盘的几种选项。"
-- "试试设置页面的不同布局。"
-- 任何用户本来会花一天时间在脑子里犹豫三种模糊草图的场景。
-
-## 两种子形式 — 强烈偏好子形式 A
-
-当 UI 原型**和应用的其余部分放在一起**时，判断起来要容易得多 — 真实的页头、真实的侧边栏、真实的数据、真实的密度。一个单独的临时路由是在真空中：每个变体在隔离状态下看起来都没问题。只要存在合理的既有页面来承载变体，就默认使用子形式 A。只有当原型确实没有附近的归宿时才使用子形式 B。
-
-### 子形式 A — 对现有页面的调整（首选）
-
-路由已经存在。变体在**同一路由**上渲染，通过 `?variant=` URL 搜索参数来控制。现有的数据获取、参数和认证全部保留 — 只有渲染部分切换。这是默认选择；除非有特定理由不这样做。
-
-如果原型是给某个还没有页面但*自然会放在某个页面内*的东西（仪表盘的新增部分、设置页面上的新卡片、现有流程中的新步骤）— 这仍然是子形式 A。在宿主页面中挂载变体。
-
-### 子形式 B — 新建页面（最后手段）
-
-仅适用于被原型化的东西确实没有可放入的现有页面时 — 例如一个全新的顶层界面，或一个无法合理嵌入任何地方的流程。
-
-按照项目已有的路由约定创建一个**临时路由** — 不要发明新的顶层结构。命名时要明显表明它是原型（例如在路径或文件名中包含 `prototype` 一词）。使用同样的 `?variant=` 模式。
-
-在采取子形式 B 之前，做一个合理性检查：是否确实没有可嵌入的现有页面？一个空路由会隐藏设计问题，而填充了内容的路由会暴露出来。
-
-两种子形式中，浮动底栏是相同的。
-
-## 流程
-
-### 1. 明确问题并确定 N 值
-
-默认为 **3 个变体**。超过 5 个就不再是截然不同而是变成噪音 — 以此为上限。
-
-在原型的存放位置或文件顶部注释中，用一行写下计划：
-
-> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
-
-这无论用户在还是不在都能用。
-
-### 2. 生成截然不同的变体
-
-起草每个变体。对每个变体检查：
-
-- 页面的目的及其可访问的数据。
-- 项目的组件库 / 样式系统（TailwindCSS、shadcn、MUI、plain CSS 等）。
-- 清晰的导出组件名，例如 `VariantA`、`VariantB`、`VariantC`。
-
-变体必须是**结构上不同**的 — 不同的布局、不同的信息层级、不同的主要操作入口，而不仅仅是不同的颜色。三个略微调整的卡片网格不是 UI 原型，是壁纸。如果两个草稿太相似，用明确的"不要使用卡片网格"指导重新做一个。
-
-### 3. 将它们连接起来
-
-在路由上创建一个单一的切换器组件：
-
-```tsx
-// 伪代码 — 根据项目的框架进行调整
-const variant = searchParams.get('variant') ?? 'A';
-return (
-  <>
-    {variant === 'A' && <VariantA {...data} />}
-    {variant === 'B' && <VariantB {...data} />}
-    {variant === 'C' && <VariantC {...data} />}
-    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
-  </>
-);
-```
-
-对于子形式 A（现有页面）：将所有现有的数据获取保留在切换器之上；只有渲染的子树按变体变化。
-
-对于子形式 B（新页面）：`/prototype/<name>` 下的临时路由挂载相同的切换器。
-
-### 4. 构建浮动切换器
-
-屏幕底部居中的小型固定位置栏，包含三部分：
-
-- **左箭头** — 切换到上一个变体（循环）。
-- **变体标签** — 显示当前变体键，如果变体导出了名称，也显示该名称。例如 `B — Sidebar layout`。
-- **右箭头** — 向前切换（循环）。
-
-行为：
-
-- 点击箭头更新 URL 搜索参数（使用框架的路由器 — Next 上用 `router.replace`，React Router 上用 `navigate` 等），使变体可分享且在刷新后保持。
-- 键盘：`←` 和 `→` 方向键也可切换。当 `<input>`、`<textarea>` 或 `[contenteditable]` 获得焦点时不要截获方向键。
-- 视觉上与页面区分开（例如高对比度的胶囊形状、微妙的阴影），使其明显不是正在评估的设计的一部分。
-- 在生产构建中隐藏 — 通过 `process.env.NODE_ENV !== 'production'` 或等价检查来控制，这样意外合并的原型不会将切换器发布给用户。
-
-将切换器放在单个共享组件中，以便两种子形式都能复用。将其放在项目中共享 UI 的存放位置。
-
-### 5. 交付
-
-展示 URL（以及 `?variant=` 键值）。用户有空时会翻看。有趣的反馈通常是**"我想要 B 的页头加上 C 的侧边栏"** — 那才是他们真正想要的设计。
-
-### 6. 捕获答案并清理
-
-一旦有变体胜出，写下是哪一个以及为什么（commit message、ADR、issue，或者如果离线运行且用户尚未回应，则在原型的旁边写一个 `NOTES.md`）。然后：
-
-- **子形式 A** — 删除落选的变体和切换器；将胜出者融合到现有页面中。
-- **子形式 B** — 将胜出的变体提升为真正的路由，删除临时路由和切换器。
-
-不要将变体组件或切换器遗留在代码中。它们腐烂很快，会困惑下一个阅读者。
-
-## 反模式
-
-- **仅在颜色或文案上有差异的变体。** 那是微调，不是原型。真正的变体在结构上有分歧。
-- **变体之间共享太多代码。** 共享的 `<Header>` 没问题；共享的 `<Layout>` 违背了目的。每个变体应能自由地抛弃布局。
-- **将变体连接到真实的变更操作。** 只读原型是可以的。如果一个变体需要变更操作，让它指向一个桩 — 问题是"这应该长什么样"，而不是"后端是否工作"。
-- **直接将原型提升到生产环境。** 变体代码是在原型约束下编写的（无测试、最小错误处理）。在融合时要正确地重写它。

package/template/vendor/matt-pocock/engineering/research/SKILL.md

@@ -1,12 +0,0 @@
----
-name: research
-description: "针对高可信度一手来源调查问题，并将发现结果以 Markdown 文件记录到仓库中。适用于需要研究某个主题、收集文档或 API 信息、或委托阅读工作给后台 Agent 的场景。"
----
-
-启动一个**后台 Agent** 来进行研究，这样你可以在它阅读时继续工作。
-
-其工作内容：
-
-1. 针对**一手来源**调查问题 —— 官方文档、源代码、规范、第一方 API —— 而不是基于这些来源的二次编写材料。将每个声明追溯到拥有该声明的来源。
-2. 将发现结果写入单个 Markdown 文件，为每个声明标注来源。
-3. 将文件保存到仓库已有的笔记存放位置；遵循现有约定，如果没有则放到合适的位置并说明存放位置。