@netpilot/skills 0.8.0 → 0.9.0

package/skills/improve-codebase-architecture/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # Improve Codebase Architecture
 
-发现 architectural friction，并提出把 shallow module 深化为 deep module 的机会。目标是提高 testability、locality、leverage 和 agent navigability。
+发现 architectural friction（架构摩擦），并提出把 shallow module 深化为 deep module 的机会。目标是提高 testability、locality、leverage 和 agent navigability。
 
 先调用 `$codebase-design` 获取 Module、Interface、Implementation、Depth、Seam、Adapter、Leverage、Locality、deletion test 与 design-it-twice 的准确含义。领域名称来自 `CONTEXT.md`，已有约束来自 ADR。
 
@@ -33,7 +33,7 @@ disable-model-invocation: true
 
 先读领域 glossary 和相关 ADR。
 
-使用只读代码探索，按真实理解摩擦有机寻找：
+启动一个只读子代理探索代码库，按真实理解摩擦有机寻找；宿主不支持子代理时由当前 agent 执行相同的只读探索：
 
 - 理解一个概念是否需要在许多小 Module 之间跳转；
 - Module 是否 shallow：Interface 几乎和 Implementation 一样复杂；
@@ -45,7 +45,7 @@ disable-model-invocation: true
 
 对每个候选项执行 deletion test：删除该 Module 会让复杂性集中到一个清楚位置，还是只把代码搬到别处？只有前者才是可信 deepening signal。
 
-## 生成 HTML report
+## 生成 HTML 报告
 
 把单文件报告写入操作系统临时目录：
 
@@ -68,6 +68,8 @@ disable-model-invocation: true
 - Recommendation strength：Strong、Worth exploring 或 Speculative；
 - 与 ADR 冲突时的明确 warning。
 
+**ADR 冲突**：只有真实摩擦足以支持重新审视该 ADR 时才展示候选，并明确标记，例如“与 ADR-0007 冲突，但值得重新讨论，因为……”。不要列出 ADR 禁止的所有理论重构。
+
 结尾只给一个 Top recommendation。
 
 使用 `CONTEXT.md` 中的领域名称和 `$codebase-design` 中的架构词汇。不要用泛化的“更干净”“更好维护”代替可解释收益。
@@ -83,6 +85,6 @@ disable-model-invocation: true
    - 新概念确实稳定时加入 `CONTEXT.md`；
    - fuzzy term 被澄清时立即更新；
    - hard-to-reverse decision 形成时建议 ADR。
-3. 用户以长期有效、会影响未来扫描的理由拒绝候选项时，询问是否记录 ADR；临时性理由不沉淀。
+3. 用户以长期有效、会影响未来扫描的理由拒绝候选项时，询问是否记录 ADR；跳过临时性理由（例如“现在不值得做”）和自明的理由。
 4. 需要比较多个 Interface 设计时调用 `$codebase-design`，使用 design-it-twice。
 5. 返回 candidate decision、推荐 Interface 方向、测试 Seam 和下一步；实际重构交给 `$to-spec` 或 `$implement`。

package/skills/prototype/SKILL.md

@@ -5,13 +5,13 @@ description: 当关键设计问题不能只靠讨论确定，需要用可丢弃
 
 # Prototype
 
-Prototype 是**用可丢弃代码回答一个问题**。问题决定它的形状。
+Prototype（原型）是**用可丢弃代码回答一个问题**。问题决定它的形状。
 
 ## 选择分支
 
 从用户提示、相邻代码或一次澄清中确认问题：
 
-- **“这套 logic / state model 是否合理？”** → 读取 [logic.md](references/logic.md)，构建一个可分享的单文件 HTML：同时提供 free-play buttons 与 tabbed guided walkthroughs，让非开发者也能推动纸面上难以判断的状态。
+- **“这套 logic / state model 是否合理？”** → 读取 [logic.md](references/logic.md)，构建一个可分享的单文件 HTML：同时提供 free-play buttons（自由操作按钮）与 tabbed guided walkthroughs（分标签页的引导演练），让非开发者也能推动纸面上难以判断的状态。
 - **“它应该长什么样？”** → 读取 [ui.md](references/ui.md)，在一个 route 上生成数个结构上明显不同的 UI variants，通过 URL search param 和浮动底栏切换。
 
 两个分支产物完全不同，选错会浪费整个实验。问题确实有歧义且用户暂时不可达时，根据相邻代码选择：backend Module 默认 logic，page/component 默认 UI，并在 prototype 顶部明确写出假设。

package/skills/prototype/references/logic.md

@@ -1,8 +1,8 @@
 # Logic Prototype
 
-一个自包含的 HTML 文件——一份 **shareable demo**——让任何人通过点击按钮推动 state model。问题涉及 **business logic、state transitions 或 data shape** 时使用：这些模型在纸面上看起来合理，只有真正经过具体情形时才会显出不对劲。
+一个自包含的 HTML 文件——一份 **shareable demo（可分享演示）**——让任何人通过点击按钮推动 state model。问题涉及 **business logic、state transitions 或 data shape** 时使用：这些模型在纸面上看起来合理，只有真正经过具体情形时才会显出不对劲。
 
-因为它只有一个文件、无需安装，所以可以直接交给非开发者，例如 designer、PM 或 domain expert，让他们亲自感受模型。因此它必须使用他们的语言，而不是代码作者的语言。
+因为它只有一个文件、无需安装，所以可以直接交给非开发者，例如设计师、产品经理或领域专家，让他们亲自感受模型。因此它必须使用他们的语言，而不是代码作者的语言。
 
 ## 何时适合这种形态
 
@@ -42,12 +42,12 @@
 
 1. **标题和一句话说明**：说明这个 demo 能探索什么，也就是步骤 1 的问题。
 2. **当前状态**：把完整相关 state 渲染为可读 panel，使用有 label 的字段而不是 raw JSON；每次点击后重新渲染，让变化可见。若能帮助非开发者跟上，再指出刚刚改变了什么。
-3. **Free-play buttons**：每个 action 一个 button，并且始终可用，让任何人按任意顺序探索模型。每次点击都 dispatch 对应 action，再重新渲染 state。
-4. **Guided walkthroughs**：提供一组 **scenarios**，每个 scenario 一个 tab。每个 tab 先用简短的日常语言说明它建立的情形和需要观察的重点，再列出该 scenario 中应按顺序点击的 **buttons**。每一步都是真实 button：点击会执行该 action 并进入下一步。启动 walkthrough 时重置到已知 initial state，使同一 scenario 每次都以相同方式运行。
+3. **Free-play buttons**（自由操作按钮）：每个 action 一个 button，并且始终可用，让任何人按任意顺序探索模型。每次点击都 dispatch 对应 action，再重新渲染 state。
+4. **Guided walkthroughs**（引导演练）：提供一组 **scenarios（场景）**，每个 scenario 一个 tab。每个 tab 先用简短的日常语言说明它建立的情形和需要观察的重点，再列出该 scenario 中应按顺序点击的 **buttons**。每一步都是真实 button：点击会执行该 action 并进入下一步。启动 walkthrough 时重置到已知 initial state，使同一 scenario 每次都以相同方式运行。
 
 选择能展示棘手情况的 scenarios：happy path、tricky edge case，以及一次本应 illegal 的尝试；它们正是纸面上难以推理的部分。
 
-外观可以漂亮，但要克制：清楚的 typography、宽松的 spacing、一个 accent colour。不要 animations 或 gimmicks，不要让任何东西与 state 和 buttons 争夺注意力。
+外观可以漂亮，但要克制：清楚的排版、宽松的间距、一种强调色。不要动画或噱头，不要让任何东西与 state 和 buttons 争夺注意力。
 
 ### 4. 交给对方操作
 

package/skills/prototype/references/ui.md

@@ -1,19 +1,19 @@
 # UI Prototype
 
-在一个 route 上生成 **数个结构上显著不同的 UI variants**，并通过浮动底栏切换。用户在 browser 中逐个比较，选定一个方案或组合各方案的优点，然后丢弃其余方案。
+在一个 route 上生成 **数个结构上显著不同的 UI variants**，并通过浮动底栏切换。用户在浏览器中逐个比较，选定一个方案或组合各方案的优点，然后丢弃其余方案。
 
 如果问题是 logic/state 而不是外观，说明选错了分支，改用 [logic.md](logic.md)。
 
 ## 何时适合这种形态
 
-- “这个 page 应该长什么样？”
+- “这个页面应该长什么样？”
 - “实现 dashboard 前，我想先看几个方案。”
 - “尝试 settings screen 的另一种 layout。”
-- 任何本来会让用户花一天在脑中比较三份模糊 mockup 的情形。
+- 任何本来会让用户花一天在脑中比较三份模糊 mockup（界面草图） 的情形。
 
 ## 两种形态——强烈优先 A
 
-当 UI prototype **紧贴应用其余部分**——真实 header、真实 sidebar、真实 data、真实 density——时，会更容易判断。孤立的 throwaway route 是一个 vacuum：每个 variant 单独看起来都不错。只要存在合理的已有页面可以承载 variants，就默认使用 A；只有 prototype 确实没有附近的归宿时才使用 B。
+当 UI prototype **紧贴应用其余部分**——真实页头、真实侧栏、真实数据、真实信息密度——时，会更容易判断。孤立的 throwaway route 是一个 vacuum：每个 variant 单独看起来都不错。只要存在合理的已有页面可以承载 variants，就默认使用 A；只有 prototype 确实没有附近的归宿时才使用 B。
 
 ### A：调整已有页面
 
@@ -51,7 +51,7 @@ Route 已经存在。通过 `?variant=` URL search param 在 **同一个 route**
 - 项目既有 component library / styling system，例如 TailwindCSS、shadcn、MUI 或 plain CSS；
 - 清楚的 exported component name，例如 `VariantA`、`VariantB`、`VariantC`。
 
-Variants 必须 **结构不同**：layout、information hierarchy 或 primary affordance 不同，而不只是 colours。三个只有轻微差别的 card grid 不是 UI prototype，只是 wallpaper。两个 draft 太相似时，明确要求其中一个“不要使用 card grid”并重新设计。
+Variants 必须 **结构不同**：布局、信息层级或主要操作方式不同，而不只是颜色。三个只有轻微差别的 card grid 不是 UI prototype，只是 wallpaper。两个 draft 太相似时，明确要求其中一个“不要使用 card grid”并重新设计。
 
 ### 3. 连接切换逻辑
 
@@ -80,7 +80,7 @@ return (
 
 ### 4. 浮动 switcher
 
-在屏幕底部中央固定一个小 bar，包含三部分：
+在屏幕底部中央固定一个小型栏，包含三部分：
 
 - **左箭头**：切换到前一个 variant，并首尾循环；
 - **Variant label**：显示当前 variant key；如果 variant export 了名称，也一起显示，例如 `B — Sidebar layout`；
@@ -90,7 +90,7 @@ return (
 
 - 点击箭头时用项目 framework 的 router 更新 URL search param，例如 Next 的 `router.replace` 或 React Router 的 `navigate`，使 variant 可分享并在 reload 后保持稳定；
 - `←` 与 `→` 键也可切换；focus 位于 `<input>`、`<textarea>` 或 `[contenteditable]` 时不得截获方向键；
-- switcher 必须在视觉上明显独立于被评估页面，例如高对比 pill 加轻微 shadow，使人清楚它不属于设计本身；
+- switcher 必须在视觉上明显独立于被评估页面，例如高对比胶囊形样式加轻微阴影，使人清楚它不属于设计本身；
 - 在 production builds 中隐藏：使用 `process.env.NODE_ENV !== "production"` 或等价检查，避免一次意外 merge 把底栏交付给用户。
 
 Switcher 只实现一次，放在项目既有 shared UI 位置，让两种形态复用。
@@ -110,7 +110,7 @@ Variant 胜出后，先捕获答案——哪个 variant 以及为什么——再
 
 ## 反模式
 
-- **Variants 只改变 colour 或 copy。** 那只是 tweak，不是 prototype；真正的 variants 对结构持不同意见。
+- **Variants 只改变颜色或文案。** 那只是 tweak，不是 prototype；真正的 variants 对结构持不同意见。
 - **Variants 共享过多代码。** 共用 `<Header>` 没问题，共用 `<Layout>` 会破坏目的；每个 variant 都必须能丢掉现有 layout。
 - **把 variants 接到真实 mutations。** 只读 prototype 没问题；需要 mutation 时指向 stub。问题是“它应该长什么样”，不是“backend 是否工作”。
 - **把 prototype 直接提升为 production。** Variant code 是在 prototype 约束下写的，没有测试，错误处理也最少。获得 `$implement` 授权后，仍须按生产标准重新实现、补齐 error handling 和 tests。

package/skills/research/SKILL.md

@@ -5,11 +5,13 @@ description: 当任务需要依据高可信一手资料调查问题、核验文
 
 # Research
 
-启动一个 **background agent** 执行阅读工作，使调用者可以同时推进其他不依赖研究结论的任务。
+启动一个 **background agent（后台子代理）** 执行阅读工作，使调用者可以同时推进其他不依赖研究结论的任务。
+
+宿主没有可用子代理，或当前任务禁止委派时，由当前 agent 执行同样的研究并保存相同证据；明确说明改为串行，不虚构派发。并行只能改变执行方式，不能降低下列来源与引用要求。
 
 后台 agent 的职责只有三项：
 
-1. 依据 **primary sources** 调查问题：官方文档、源代码、规范、论文或 first-party API，而不是二手总结。每项事实都追溯到拥有该事实的一手来源。
+1. 依据 **primary sources（一手来源）** 调查问题：官方文档、源代码、规范、论文或 first-party API，而不是二手总结。每项事实都追溯到拥有该事实的一手来源。
 2. 把结论写入一份 Markdown 文件；每项可验证 claim 或事实都在出现位置直接引用拥有该事实的一手来源，而不是只给整篇文档附一组链接。
 3. 遵循仓库现有研究文档位置与命名约定；没有约定时选择合理位置，并明确返回绝对或仓库相对路径。
 

package/skills/resolving-merge-conflicts/SKILL.md

@@ -5,7 +5,7 @@ description: 当 Git 已处于 merge 或 rebase 中且存在冲突，需要依
 
 # Resolving Merge Conflicts
 
-逐 hunk 解决正在进行的 merge 或 rebase。目标是保存双方原始意图，并使项目重新通过检查；不是选择“ours 全赢”或“theirs 全赢”。
+逐 hunk（差异块）解决正在进行的 merge 或 rebase。目标是保存双方原始意图，并使项目重新通过检查；不是选择“ours 全赢”或“theirs 全赢”。
 
 ## 动作门禁
 

package/skills/tdd/SKILL.md

@@ -11,7 +11,7 @@ TDD 是 **red → green** 循环。本 skill 说明什么测试值得保留、
 
 ## 好测试是什么
 
-测试通过 public Interface 验证 behavior，而不是 Implementation details。代码内部可以完全重写；只要外部 behavior 不变，测试就不应变化。
+测试通过公开 Interface 验证 behavior，而不是 Implementation 内部细节。代码内部可以完全重写；只要外部 behavior 不变，测试就不应变化。
 
 好测试读起来像 specification，例如：
 
@@ -21,19 +21,21 @@ TDD 是 **red → green** 循环。本 skill 说明什么测试值得保留、
 
 ## Seam：测试放在哪里
 
-**Seam** 是测试观察 behavior 的 public Interface。测试位于 Seam，不伸进 internals。
+**Seam** 是测试观察 behavior 的公开 Interface。测试位于 Seam，不伸进内部实现。
 
-只在预先确认的 Seams 上测试。写测试前列出 public Interface 与本次要测试的 Seams，并取得用户确认，或确认它们已在批准的 spec/plan 中明确；不要在每个 cycle 重复询问已批准的同一 Seam。
+只在预先确认的 Seams 上测试。写测试前列出公开 Interface 与本次要测试的 Seams，并取得用户确认，或确认它们已在批准的 spec/plan 中明确；不要在每个 cycle 重复询问已批准的同一 Seam。
 
 核心问题：
 
-> Public Interface 是什么？哪些 Seams 值得测试？
+> 公开 Interface 是什么？哪些 Seams 值得测试？
+
+当 Interface 的形状本身仍未确定——Module 应有多深、Seam 放在哪里、Interface 暴露什么——读取 `$codebase-design`（Claude 使用 Skill 工具调用 `codebase-design`）的共享参考。它统一 Module、Interface、Depth、Seam、Adapter、Leverage 与 Locality 的含义；读完返回当前 TDD 循环，不另开设计会话。
 
 ## 反模式
 
-- **Implementation-coupled**：mock 内部 collaborators、测试 private methods，或通过 side channel 验证，例如绕过 Interface 直接查询数据库。判断信号是：behavior 没变，内部重构却让测试失败。
-- **Tautological**：断言用与 Implementation 相同的方式重新计算 expected value，例如 `expect(add(a, b)).toBe(a + b)`。它按构造就无法反驳代码。Expected value 必须来自独立事实：known-good literal、手工演算例子或 spec。
-- **Horizontal slicing**：先写完所有测试，再写全部实现。批量测试验证的是想象中的 behavior，过早锁定测试结构，也无法利用上一轮实现带来的信息。改用 **vertical slices**：一个 test → 一个 implementation → 重复；每个 test 都是响应上一轮事实的 **tracer bullet**。
+- **Implementation-coupled（与实现耦合）**：mock 内部协作者、测试私有方法，或通过旁路验证，例如绕过 Interface 直接查询数据库。判断信号是：behavior 没变，内部重构却让测试失败。
+- **Tautological（同义反复）**：断言用与 Implementation 相同的方式重新计算 expected value，例如 `expect(add(a, b)).toBe(a + b)`。它按构造就无法反驳代码。Expected value 必须来自独立事实：known-good literal、手工演算例子或 spec。
+- **Horizontal slicing（水平切片）**：先写完所有测试，再写全部实现。批量测试验证的是想象中的 behavior，过早锁定测试结构，也无法利用上一轮实现带来的信息。改用 **vertical slices（垂直切片）**：一个 test → 一个 implementation → 重复；每个 test 都是响应上一轮事实的 **tracer bullet（曳光弹）**。
 
 ## 循环规则
 

package/skills/teach/SKILL.md

@@ -30,9 +30,9 @@ disable-model-invocation: true
 
 深层学习需要三样东西：
 
-- **Knowledge**：来自高质量、高可信资料的知识；
-- **Skills**：通过与你设计的、高度相关且可交互的课程练习获得的技能；
-- **Wisdom**：在学习环境之外与其他学习者和实践者互动后形成的判断力。
+- **Knowledge（知识）**：来自高质量、高可信资料的知识；
+- **Skills（技能）**：通过与你设计的、高度相关且可交互的课程练习获得的技能；
+- **Wisdom（实践判断力）**：在学习环境之外与其他学习者和实践者互动后形成的判断力。
 
 在 `RESOURCES.md` 尚未拥有足够可靠资料前，优先补齐资料。不要把参数化记忆当作事实来源。不同主题的重心不同：理论主题可能更依赖 Knowledge；身体、表演或操作性主题可能更依赖 Skills。
 
@@ -40,14 +40,14 @@ disable-model-invocation: true
 
 区分两种学习强度：
 
-- **Fluency strength**：当下能够顺畅提取或复述；
-- **Storage strength**：经过时间后仍能提取、应用和迁移。
+- **Fluency strength（流畅强度）**：当下能够顺畅提取或复述；
+- **Storage strength（存储强度）**：经过时间后仍能提取、应用和迁移。
 
-流畅会制造已经掌握的错觉，长期保持才是目标。用 desirable difficulty 建立 Storage strength：
+流畅会制造已经掌握的错觉，长期保持才是目标。用 desirable difficulty（有益难度） 建立 Storage strength：
 
-- retrieval practice：不看答案，从记忆中提取；
-- spacing：把练习分散到不同时间；
-- interleaving：在技能练习中交错相关主题，而不是连续重复同一题型。
+- retrieval practice（提取练习）：不看答案，从记忆中提取；
+- spacing（间隔练习）：把练习分散到不同时间；
+- interleaving（交错练习）：在技能练习中交错相关主题，而不是连续重复同一题型。
 
 ## 每次教学会话
 
@@ -56,7 +56,7 @@ disable-model-invocation: true
 3. 用短诊断、回忆题或小任务估计用户当前基础和 Zone of Proximal Development。自述可以作为线索，但不能替代掌握证据。
 4. 从高可信资料获得本课所需 Knowledge；资料不足、事实可能变化或用户要求核验时，使用 `$research` 完成有停止条件的调查，再把筛选后的来源写入 `RESOURCES.md`。
 5. 只设计下一节最小课程：一个目标、必要知识、一次主动练习、紧反馈和一个高可信主要来源。课程必须直接服务 mission，并位于用户的 Zone of Proximal Development。
-6. 用户完成练习后检查证据。只有用户能正确回忆、应用或迁移时，才更新学习记录或术语表；material covered 不等于 material learned。
+6. 用户完成练习后检查证据。只有用户能正确回忆、应用或迁移时，才更新学习记录或术语表；讲过不等于学会。
 7. 总结本次小胜利、仍不稳固之处、适合的复习时机和下一节候选目标。
 
 `$teach` 可以调用 `$grilling` 或 `$research`；被调用 skill 返回访谈结果或证据后，控制权回到当前教学会话，不启动第二个 `$teach`。
@@ -97,11 +97,11 @@ Mission 会随着 Skills 和 Knowledge 增长而变化。变化时先与用户
 
 Lesson 应围绕用户要获得的一项 skill 设计，只教授获得该 skill 必需的 Knowledge。先给必要知识，再让用户进入互动反馈循环。
 
-Knowledge 必须优先来自 `RESOURCES.md` 中的可信资料。课程中的事实性主张应就近链接外部来源；推断和经验判断明确标注。获取 Knowledge 时，无关难度会占用理解所需的 working memory，应尽量降低。
+Knowledge 必须优先来自 `RESOURCES.md` 中的可信资料。课程中的事实性主张应就近链接外部来源；推断和经验判断明确标注。获取 Knowledge 时，无关难度会占用理解所需的工作记忆，应尽量降低。
 
 ## 技能
 
-Knowledge 关乎获得，Skills 关乎耐久与迁移。技能练习可以有意增加难度，因为 effortful retrieval 会提高 Storage strength。
+Knowledge 关乎获得，Skills 关乎耐久与迁移。技能练习可以有意增加难度，因为 effortful retrieval（费力提取） 会提高 Storage strength。
 
 可用形式包括：
 
@@ -127,7 +127,7 @@ Wisdom 来自在学习环境之外检验 Skills。遇到需要实践判断的问
 - 流程的算法与流程图；
 - 动作、姿势和练习序列；
 - 训练动作与计划；
-- 任何有专门 nomenclature 的主题 glossary。
+- 任何具有专门术语的主题 glossary。
 
 Glossary 尤其重要。一旦建立，后续 lessons、references 和 learning records 都应使用其中的 canonical language。
 

package/skills/to-questionnaire/SKILL.md

@@ -6,52 +6,52 @@ disable-model-invocation: true
 
 # To Questionnaire
 
-把用户无法独自回答的事情变成一份 **questionnaire**：一份交给某一个人异步填写，或在会议中共同填写的 Markdown 文档。Recipient 掌握用户缺少的知识；questionnaire 把这些知识提取出来。
+把用户无法独自回答的事情变成一份 **questionnaire（问卷）**：一份交给某一个人异步填写，或在会议中共同填写的 Markdown 文档。接收者掌握用户缺少的知识；问卷把这些知识提取出来。
 
-**Grill the send, not the subject.** 只访谈用户能够回答的 _send_：发给谁，以及需要拿回什么。文档中的问题再瞄准 recipient 已知与用户所需之间的 **gap**。
+**Grill the send, not the subject（盘问发送目的，不盘问待解主题）。** 只访谈用户能够回答的 _send_：发给谁，以及需要拿回什么。文档中的问题再瞄准接收者已知与用户所需之间的 **gap（信息缺口）**。
 
-1. **发给谁？** 在一次 exchange 中询问 recipient 的角色、专业知识，以及与用户的关系。这决定 questionnaire 的语气和需要携带多少 context。完成条件：已经知道 recipient 是谁，以及对方掌握什么用户不知道的知识。
+1. **发给谁？** 在一次交流中询问接收者的角色、专业知识，以及与用户的关系。这决定问卷的语气和需要携带多少背景。完成条件：已经知道接收者是谁，以及对方掌握什么用户不知道的知识。
 
-2. **需要拿回什么？** 在一次 exchange 中询问用户无法独自解决、必须由这个人提供的具体 decisions 或 facts。完成条件：已经得到一份具体清单，说明用户在收到回答后必须能够做什么或决定什么。
+2. **需要拿回什么？** 在一次交流中询问用户无法独自解决、必须由这个人提供的具体决定或事实。完成条件：已经得到一份具体清单，说明用户在收到回答后必须能够做什么或决定什么。
 
-3. **编写 questionnaire。** 针对步骤 1–2 确定的 gap 起草问题，严格采用下方 Document Structure。写入当前目录的 `to-questionnaire-<slug>.md`，slug 来自主题，并报告最终路径。目标路径已存在时，选择唯一的新 suffix 或 slug；不得覆盖已有文件。完成条件：文件已经存在，并且步骤 2 中用户点名的每一项都由一个问题覆盖。
+3. **编写 questionnaire。** 针对步骤 1–2 确定的 gap 起草问题，严格采用下方文档结构。写入当前目录的 `to-questionnaire-<slug>.md`，slug 来自主题，并报告最终路径。目标路径已存在时，选择唯一的新后缀或 slug；不得覆盖已有文件。完成条件：文件已经存在，并且步骤 2 中用户点名的每一项都由一个问题覆盖。
 
-## Document Structure
+## 文档结构
 
-把文档框定为 **discovery questionnaire**：用户缺少 context，recipient 掌握它。按 most-important-first 排列问题——async 意味着可能只有一次回答机会。问题多于少量时，再按主题用 `##` headings 分组。使用下面的模板。
+把文档框定为 **discovery questionnaire（探索问卷）**：用户缺少背景，接收者掌握它。按 **most-important-first（最重要的问题优先）**排列问题——异步填写意味着可能只有一次回答机会。问题多于少量时，再按主题用 `##` 标题分组。使用下面的模板。
 
 <questionnaire-template>
 
-# <Questionnaire title>
+# <问卷标题>
 
-**Purpose:** 为什么需要这份 questionnaire，以及哪个 decision 取决于它。
+**目的：** 为什么需要这份问卷，以及哪个决定取决于它。
 
-**From:** <the user> — **To:** <the recipient> — **How your answers will be used:** <answers 会进入哪里>
+**发起人：** <用户> — **接收者：** <接收者> — **回答用途：** <回答会用于哪里>
 
-## Context
+## 背景
 
-用一个 paragraph 帮助没有参与用户思考过程的 recipient 定位。提供足以高质量回答的 context，但不要写成一页背景资料。
+用一个段落帮助没有参与用户思考过程的接收者了解背景。提供足以高质量回答的信息，但不要写成一页背景资料。
 
-## How to answer
+## 如何回答
 
-写明 deadline 与大致 effort。Partial answers 和 “I don't know” 都有价值；对不确定的内容显式标记，而不是跳过。
+写明截止时间与大致投入。部分回答和“我不知道”都有价值；对不确定的内容显式标记，而不是跳过。
 
-## <Theme heading>
+## <主题标题>
 
-每个 theme 一个 `##` section，下面按 most-important-first 排列问题。每个问题只包含一个 idea，不能 compound；紧接一个 answer stub。只有问题可能被误解或招致敷衍回答时，才添加一行 _Why this matters_。
+每个主题一个 `##` 章节，下面按 most-important-first 排列问题。每个问题只问一件事，不把多个问题合在一起；紧接一个作答占位。只有问题可能被误解或招致敷衍回答时，才添加一行“为什么重要”。
 
 <question-example>
 
 ### 系统在首次发布时预计要承受多大负载？
 
-_Why this matters: 这决定现在就为 burst traffic 预留容量，还是推迟该投入。_
+_为什么重要：这决定现在就为突发流量预留容量，还是推迟该投入。_
 
 >
 
 </question-example>
 
-## Anything else?
+## 还有其他信息吗？
 
-用一个 closing catch-all 收尾：还有什么我们没有问、但应该知道的事情？
+用一个兜底问题收尾：还有什么我们没有问、但应该知道的事情？
 
 </questionnaire-template>

package/skills/to-spec/SKILL.md

@@ -19,7 +19,7 @@ disable-model-invocation: true
 1. 若尚未完成，探索仓库当前状态。全文使用项目 glossary 的 canonical terms，并遵守相关 ADR。
 2. 草拟测试 feature 的 Seams：
    - 优先复用现有 Seam；
-   - 必须增加时，尽可能放在最高层；
+   - 无论复用还是新增，都尽可能使用最高层的 Seam；
    - Seam 越少越好，理想情况只有一个。
 
    向用户校准这些 Seams 是否符合预期。这是规格发布前的定向确认，不重新开始需求访谈。
@@ -27,23 +27,25 @@ disable-model-invocation: true
 
 ## Spec 结构
 
-### Problem Statement
+### 问题陈述（Problem Statement）
 
 从用户视角描述其面对的问题。
 
-### Solution
+### 解决方案（Solution）
 
 从用户视角描述解决方案。
 
-### User Stories
+### 用户故事（User Stories）
 
 使用足够详尽的编号列表覆盖所有用户可观察行为；每条都能独立检查，合在一起覆盖 feature 的全部方面：
 
 ```text
-1. As a <actor>, I want a <feature>, so that <benefit>.
+1. 作为<角色>，我希望<功能>，以便<收益>。
 ```
 
-### Implementation Decisions
+例如：作为手机银行客户，我希望查看各账户余额，以便作出更有依据的消费决策。
+
+### 实施决定（Implementation Decisions）
 
 记录已经形成的实施决定，包括：
 
@@ -58,7 +60,7 @@ disable-model-invocation: true
 
 不要写具体文件路径或工作代码，它们很快会过时。唯一例外：prototype 产生的 state machine、reducer、schema 或 type shape 比文字更精确时，可以只嵌入承载 decision 的最小片段，并注明来自 prototype。
 
-### Testing Decisions
+### 测试决定（Testing Decisions）
 
 至少说明：
 
@@ -66,15 +68,15 @@ disable-model-invocation: true
 - 哪些 Modules / Seams 要测试；
 - 代码库中可复用的同类测试先例。
 
-### Acceptance Criteria
+### 验收标准（Acceptance Criteria）
 
 用可观察、可验证的条件定义完成。适合时使用 Given / When / Then；不要把“修改某文件”当作用户行为的验收条件。
 
-### Out of Scope
+### 范围外事项（Out of Scope）
 
 明确与当前 spec 相邻但不包含的事项。
 
-### Further Notes
+### 补充说明（Further Notes）
 
 只放无法归入以上章节、但实施者确实需要的补充信息；没有内容时省略。
 

package/skills/to-tickets/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # To Tickets
 
-把 plan、spec 或当前对话拆成一组 **tracer-bullet vertical slices**。每个 ticket 都声明阻塞它的 **blocking edges**。
+把 plan、spec 或当前对话拆成一组 **tracer-bullet vertical slices（曳光弹式垂直切片）**。每个 ticket 都声明阻塞它的 **blocking edges（阻塞关系）**。
 
 ## 动作授权
 
@@ -37,7 +37,7 @@ disable-model-invocation: true
 - 能在一个新鲜上下文窗口中完成；
 - 声明真正阻塞它的 tickets；没有 blockers 的 ticket 可立即开始。
 
-**Wide refactor 是垂直切片的例外。** 识别信号不是“改动文件很多”，而是一次不可避免的机械变化——例如 **rename a column** 或 **retype a shared symbol**——会同时打破大量调用点，使普通垂直切片无法先 green。此时使用 **expand–migrate–contract**：
+**Wide refactor（大范围重构）是垂直切片的例外。** 识别信号不是“改动文件很多”，而是一次不可避免的机械变化——例如 **rename a column** 或 **retype a shared symbol**——会同时打破大量调用点，使普通垂直切片无法先 green。此时使用 **expand–migrate–contract**：
 
 1. **Expand**：让新旧形式并存，不破坏现有调用者；
 2. **Migrate**：按 package、目录或其他 blast-radius 边界拆成批次，每批一个 ticket，均被 expand 阻塞，并保持每批 CI green；

package/skills/triage/SKILL.md

@@ -28,18 +28,18 @@ disable-model-invocation: true
 
 执行前用一句话列出拟进行的状态变化和写入，无需再次确认。
 
-若只是“triage 这个 item”但最终状态仍需维护者判断，先给 recommendation 并等待。bare number 无法唯一解析、label mapping 不明或状态冲突时，只读检查并询问。
+若只是“triage 这个 item”但最终状态仍需维护者判断，先给建议并等待。裸编号无法唯一解析、label mapping 不明或状态冲突时，只读检查并询问。
 
 永不自动 push、创建 PR、merge、deploy 或发布。若 `.out-of-scope/` 更新需要 commit，只能在明确本地 branch 上提交；不自动 push。
 
 ## 分类与状态
 
-两个 category：
+两个 category（类别）：
 
 - **bug**：已有行为损坏；
 - **enhancement**：新增功能或改进。
 
-五个 state：
+五个 state（状态）：
 
 - **needs-triage**：等待维护者评估；
 - **needs-info**：等待 reporter 补充；
@@ -62,7 +62,7 @@ state labels 冲突时停止写入，先请求维护者决定。
 
 ## 模式一：显示需要关注的内容
 
-按最旧优先查询三个 bucket：
+按最旧优先查询三个分组：
 
 1. unlabeled；
 2. needs-triage；
@@ -70,7 +70,7 @@ state labels 冲突时停止写入，先请求维护者决定。
 
 若 tracker 配置把外部 PR 纳入 triage，发现列表只包含外部作者 PR，并标记 `[PR]` 或 `[issue]`。显式指定的 PR 不受该发现过滤限制。
 
-输出每个 bucket 的数量与每项一行摘要，让维护者选择。
+输出每个分组的数量与每项一行摘要，让维护者选择。
 
 ## 模式二：Triage 一个 item
 
@@ -82,8 +82,8 @@ state labels 冲突时停止写入，先请求维护者决定。
 
 执行两项代码库检查：
 
-- **Redundancy**：按领域概念搜索现有实现，而不只搜索 reporter 原话，并说明查过哪里。已实现则进入 wontfix，但不写 `.out-of-scope/`。
-- **Prior rejection**：读取 `.out-of-scope/*.md`，按概念相似性寻找以前的拒绝。
+- **Redundancy（重复需求）**：按领域概念搜索现有实现，而不只搜索 reporter 原话，并说明查过哪里。已实现则进入 wontfix，但不写 `.out-of-scope/`。
+- **Prior rejection（已有拒绝决定）**：读取 `.out-of-scope/*.md`，按概念相似性寻找以前的拒绝。
 
 ### 给出建议
 
@@ -167,5 +167,5 @@ state labels 冲突时停止写入，先请求维护者决定。
 1. 读取已确认内容和未答问题；
 2. 检查 reporter 后续回复；
 3. 标出哪些问题已解决；
-4. 展示更新后的 picture；
+4. 展示更新后的全貌；
 5. 只询问仍未解决的问题。

package/skills/wait-what/SKILL.md

@@ -4,4 +4,4 @@ description: 当用户表示上一条消息没有听懂、没有讲清楚，或
 disable-model-invocation: true
 ---
 
-等等——上一条没有讲清楚。重新讲一遍：补一点上下文；使用当前沟通语言的短句和单义技术词，英语时采用 ASD-STE100 Simplified Technical English；优先使用 `CONTEXT.md` 的 canonical terms，不存在时使用已经确认的项目词汇，不杜撰文档内容。
+等等——上一条没有讲清楚。重新讲一遍：补一点上下文；使用当前沟通语言的短句和单义技术词，英语时采用 ASD-STE100 Simplified Technical English（简化技术英语）；优先使用项目的统一领域语言，多 context 仓库先沿 `CONTEXT-MAP.md` 找到对应的 `CONTEXT.md`，单 context 仓库直接读取 `CONTEXT.md`，不存在时使用已经确认的项目词汇，不杜撰文档内容。

package/skills/wayfinder/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # Wayfinder
 
-Wayfinding 的目标是找到通往 **Destination** 的路，不是冲向 Destination。命名 Destination 是建图的第一项动作，因为它会塑造每一张 ticket。Destination 可能是交给后续流程迭代的明确 spec、规划前尚待锁定的 decision，或在当前 effort 原地完成的 migration。Map 不限定领域：工程、课程内容或其他超过单会话且仍在 fog of war 中的工作都可以使用。
+Wayfinding 的目标是找到通往 **Destination（目的地）** 的路，不是冲向 Destination。命名 Destination 是建图的第一项动作，因为它会塑造每一张 ticket。Destination 可能是交给后续流程迭代的明确 spec、规划前尚待锁定的 decision，或在当前 effort 原地完成的 migration。Map 不限定领域：工程、课程内容或其他超过单会话且仍在 fog of war 中的工作都可以使用。
 
 地图由 decision tickets 组成：每票解决一个问题，产物是 decision，而不是 build slice。Destination 是 spec 时，路线清楚后默认交给 `$to-spec`；Destination 本身是 decision 或 Notes 明确允许原地 migration 时，按该 Destination 的完成条件结束，不机械转成 spec。
 
@@ -44,9 +44,9 @@ Wayfinding 的目标是找到通往 **Destination** 的路，不是冲向 Destin
 
 Map 是一个标记为 `wayfinder:map` 的 tracker item，也是 canonical artifact。远程 tracker 使用 parent/child issue；本地 fallback 使用一份 map 文件和每票一个文件。
 
-Map 是索引，不重复保存 ticket 的完整答案。每个 decision 只在其 ticket 的 resolution 中存在；map 只写一句 gist 并链接。
+Map 是索引，不重复保存 ticket 的完整答案。每个 decision 只在其 ticket 的 resolution 中存在；map 只写一句摘要并链接。
 
-Map body 是每个 session 只加载一次的低分辨率视图。Open tickets 不列在 body 中，而是通过 child-ticket query 获取。
+Map body 是每个 session 只加载一次的低分辨率概览。Open tickets 不列在 body 中，而是通过 child-ticket query 获取。
 
 ```markdown
 ## Destination
@@ -56,7 +56,7 @@ Map body 是每个 session 只加载一次的低分辨率视图。Open tickets
 领域、每个 session 应调用的 skills、常驻约束和权限。
 
 ## Decisions so far
-- [已关闭 ticket 标题](link) — 一行 decision gist
+- [已关闭 ticket 标题](link) — 一行决定摘要
 
 ## Not yet specified
 仍在 scope 内，但尚无法精确表述为问题的 fog。
@@ -130,26 +130,26 @@ Out of scope 是经过确认的 scope boundary，不是尚未看清的 fog，永
 
 只有 destination 被重新定义时，才将相关内容作为新 effort 重新考虑。
 
-## 调用模式一：Chart the map
+## 调用模式一：绘制地图（Chart the map）
 
 用户以大型模糊想法调用：
 
-1. **Name the destination**
+1. **命名目的地（Name the destination）**
    调用 `$grilling` 和 `$domain-modeling`，明确 map 最终要找到什么。它们返回 destination、scope 和统一术语。
 
-2. **Breadth-first map the frontier**
+2. **广度优先绘制 frontier**
    再次访谈，但横向扫描整个空间，寻找当前可精确表达的 decisions 与仍在 fog 中的区域。不要过早深入单一分支。
 
 3. **检查是否真的需要 map**
    如果没有 fog，且全部工作可在一个 session 中解释清楚，停止建图，告诉用户应进入 `$to-spec` 或 `$implement`。
 
-4. **Create the map**
+4. **创建地图**
    填写 Destination、Notes、空的 Decisions so far、Not yet specified 和 Out of scope。
 
-5. **Create then wire tickets**
+5. **先创建票据，再连接依赖**
    先创建所有当前可定义的 child tickets，拿到真实标识符后，第二 pass 再建立 blocking。不能在创建前猜 id。
 
-6. **Fire research tickets**
+6. **启动研究票据**
    research tickets 可以并行：
    - 为每票创建隔离 worktree/本地 branch；
    - 调用 `$research` 写带引用的 Markdown artifact；
@@ -159,14 +159,14 @@ Out of scope 是经过确认的 scope boundary，不是尚未看清的 fog，永
    - 关闭 research ticket并更新 map。
    不得自动 push branch。
 
-7. **Stop**
+7. **停止**
    Charting session 不手工解决 grilling、prototype 或 task ticket。
 
-## 调用模式二：Work through the map
+## 调用模式二：逐票推进地图（Work through the map）
 
 用户提供 map URL、编号或本地路径。ticket 参数可选。
 
-1. 加载 map 的低分辨率视图，不一次读取所有 ticket body。
+1. 加载 map 的低分辨率概览，不一次读取所有 ticket body。
 2. 用户指定 ticket 时使用它；否则选择第一个 frontier ticket。
 3. 在工作前 claim。
 4. 按 type 解决，并调用 map `Notes` 中点名的 skills；未指定且不确定时默认使用 `$grilling` + `$domain-modeling`：
@@ -174,11 +174,11 @@ Out of scope 是经过确认的 scope boundary，不是尚未看清的 fog，永
    - prototype → `$prototype`；
    - grilling → `$grilling` + `$domain-modeling`；
    - task → 完成解除 decision blocker 所需的最小动作。
-5. 需要时再 zoom：按需读取相关 open/closed ticket 全文。
+5. 需要时再展开细节：按需读取相关 open/closed ticket 全文。
 6. 记录 resolution：
    - 写 resolution comment；
    - 关闭 ticket；
-   - 在 Decisions so far 追加标题链接与一行 gist。
+   - 在 Decisions so far 追加标题链接与一行摘要。
 7. 更新地图：
    - create then wire 新 ticket；
    - 把已变得可精确表达的 fog 转为 ticket，并从 Not yet specified 删除；