triage

分诊

你正在使用 triage 入门流程。适用于错误、小型修复，以及只涉及单个组件、不引入新边界且不改变接口的变更。如果发现变更规模更大，请升级到 architect。

运行辅助脚本

此技能将辅助脚本打包在自身的 scripts/ 目录中（与此 SKILL.md 一同安装）。将 SKILL_DIR 设置为此技能的绝对路径——文件末尾标注为 此技能的基础目录——然后从你的项目根目录运行脚本（它们会操作项目的 .changes/ 和 CONTEXT.md 文件）：

SKILL_DIR="<absolute path to this skill's directory>"

以下所有 node "$SKILL_DIR/scripts/..." 命令都依赖此设置。切勿引用 packages/build/——该路径只存在于工具包的开发仓库中，不存在于已安装的技能中。

你的立场

采用 references/challenge-protocol.md 中的建设性挑战立场，但保持此工作流轻量。分诊不会执行正式的 AV-*、SV-* 或 RV-* 审查，不会启动审计员／验证员角色，也不会使用 review-log.mjs。只有当选择触及实质性边界时才询问用户；如果触及，通常应转入 architect。对于常见、惯用、本地、私有且可逆的选择，自动做出决定。

前置条件

在检查状态、创建清单、读取 CONTEXT.md 或扫描代码之前，先获取目标和可观察结果、受影响区域、约束与反目标，以及需求是已成形、部分成形还是尚未成形。选择或创建工作区后，根据 references/templates/change-brief.md.tmpl 编写 change-brief.md。

检查是否有活动变更：

node "$SKILL_DIR/scripts/change-status.mjs"

如果没有活动变更，则创建一个：

node "$SKILL_DIR/scripts/change-new.mjs" --title "<title>" --class small|bug [--language <lang>]

加载活动的 manifest.yaml。如果设置了 manifest.language，则使用 idioms 技能加载匹配的语言包，用于挑战和重构阶段。如果未安装匹配的语言包，请说明这一点，并采用仓库的语言约定和工具，而不要臆测语言包的指导。

阶段 1：分类

先回答以下问题，再做其他事情：

1. 是否仅限于单个组件？ 如果涉及多个组件或跨越组件边界 → 升级到 architect。
2. 是否引入了新边界或改变了现有接口？ 如果是 → 升级到 architect。
3. 是否涉及稳固边界？ 如果是：变更是在稳固契约范围内（实现变更，而非契约变更），还是会改变契约？如果会改变契约 → 升级到 architect 并采用稳固边界变更协议。
4. 修复是否明确且范围有限？ 如果不是 → 升级到 architect。

如果要升级：

"此变更超出分诊范围，原因是：[原因]。我将改为启动 architect 会话。"

使用 --class feature 创建新清单，然后继续执行 architect 流程。

阶段 2：快速了解上下文

只阅读必要内容：

• 组件的 CONTEXT.md（如果存在）
• 相关源文件（不要读取整个代码库）
• 变更涉及的任何稳固边界（确认不会改变契约）

记下 CONTEXT 中相关的 Known-soft-spots。如果修复涉及已知软肋，且存在更好的解决方案，请指出来——但在扩大范围前，必须获得明确批准。

阶段 3：挑战并确认

提出一两个有针对性的问题——不必进行完整访谈，但要足以确认修复方案正确：

• 根本原因是什么？（不只是症状）
• 这是正确的修复方案，还是针对更深层问题的权宜之计？
• 是否会影响其他调用方或使用者？
• 如果涉及惯用写法问题，语言包中是否有更简洁的做法？

阶段 4：快速规划

在此处写一份简短计划——除非变更需要，否则不必编写完整的 plan.md：

## Triage Plan: <title>

Root cause: <one sentence>
Fix: <what you're doing>
Files: <target files>

Tasks:
- [ ] <task 1>
- [ ] <task 2>
- [ ] Write test: <what it asserts> [seam: <id if applicable>, firmness: soft|firm]
- [ ] Run tests

对于错误，先编写一个能够复现该错误的失败测试，然后再修复。这可以确认根本原因并防止回归。

如果使用完整变更工作区，请保存到 .changes/active/<id>/plan.md。

阶段 5：执行 + 轻量自检

实施任务。然后快速进行一次实施者自检，不要开展正式的发现／修复／验证循环：

• 此修复是否引入了新的技术债？
• 有没有更简洁的表达方式？
• 检查 idioms 技能包中是否有相关内容，尤其是存在不安全／容易引发 panic 的代码（例如 Rust 中对 I/O 使用 .unwrap()／.expect()）、吞掉错误以及模块过大的情况。

运行测试——必须通过。

如果修复超出小范围的独立改动，请停止并转交给完整的 architect 主流程或 refactor 技能。

阶段 6：文档协调

文档审批前必须完成协调与验证。对于每个相关的 CONTEXT.md 目标：

• 更新相关的 CONTEXT.md 部分。
• 重新盖上来源戳。
• 运行验证并解决所有发现：

  node "$SKILL_DIR/scripts/context-verify.mjs" --path <context-file>
  

阶段 7：已可归档并验证归档

完成轻量自检和文档协调后，依次批准实施和文档。这会将直接分诊生命周期推进到 archive-ready：

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval implement --approve
node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval docs --approve

只有在更改达到可归档状态后，才能创建经过验证的归档：

node "$SKILL_DIR/scripts/change-archive.mjs" --id <id>

如需取消，请在 manifest.yaml 中记录具体的 archive.reason，并归档当前工作区，而不是删除它。

升级条件（摘要）

出现以下任一情况时，升级给 architect：

• 涉及多个组件
• 添加或移除接缝
• 更改接口（哪怕只是细微更改）
• 触及固定接缝的契约
• 修复需要进行实质性规模的重构
• 根本原因分析发现了更深层的架构问题

不要为了把事情留在分诊阶段而逞强。合理升级并不代表失败——而是诚实地界定范围。

参考文件

• references/challenge-protocol.md
• references/context-schema.md — 用于读取 CONTEXT.md
• references/seam-and-test-taxonomy.md
• references/firm-change-protocol.md — 涉及固定接缝时使用
• idioms 技能 — 已确定语言时使用