需要排查关键操作失败、延迟和回归时…

适用于 HTTP、tRPC、IPC、队列、cron、启动流程等 runtime 边界，为重要操作建立可查询的 outcome 事件。

适用场景

解决思路

1. 先运行审计脚本：`python3 scripts/audit_queryable_outcomes.py --root . --format markdown`。
2. 从该技能目录运行随附的 `scripts/audit_queryable_outcomes.py`；如有需要，解析包含此 `SKILL.md` 的目录，并显式传入脚本路径。
3. 修改代码前只阅读一个 runtime reference：Electron、tRPC、IPC、后台桌面任务读 `references/runtime-patterns-electron.md`；Node HTTP 应用和 worker 读 `references/runtime-patterns-node.md`。
4. 在编写 middleware 或 wrappers 前，使用 `references/event-schema.md` 定义 canonical event shape。
5. 先埋点 top 3 用户关键操作；不要从仓库中每个 route 或 command 开始。
6. 清点 operation boundaries。
7. 传输边界通常最重要：HTTP handlers、tRPC procedures、IPC commands、queue consumers、cron jobs、startup flows。
8. 将低层 helper functions 视为 enrichment points，而不是 canonical operation。
9. 选择 operation record shape。
10. 阅读 `references/event-schema.md`。
11. 先锁定 required fields：operation name、type、timestamps、duration、success、stable error code、correlation ID、version metadata。
12. 在边界添加一个 wrapper。
13. 在 entry 时开始记录。
14. 在 operation 运行期间进行 enrich。
15. 在 `finally` 中 finalize 并 persist，使成功和失败路径都 emit 一个 outcome。
16. 添加能改善调试的 domain context。
17. 在可用时包含 actor、resource、trigger、rollout flags、retry count 和 version data。
18. 省略只对本地调试有意义或包含 secrets 的字段。
19. 持久化或 emit 结果：优先使用 local table、operational event store 或 queryable analytics sink。
20. 对关键 outcome，不要依赖 ephemeral console logs 或 in-memory buffers。
21. 用真实问题验证。
22. 阅读 `references/rollout-and-queries.md`。
23. 如果新的 shape 不能快速回答 failure、latency 和 regression 问题，说明 instrumentation 仍然太薄。
24. Electron desktop app：阅读 `references/runtime-patterns-electron.md`，了解 tRPC mutations、`ipcMain.handle`、startup actions 和 background jobs。
25. Node server or worker：阅读 `references/runtime-patterns-node.md`，了解 Express、Fastify、Hono-style handlers、queues 和 cron jobs。
26. 对每个重要 operation，优先使用一个 durable outcome event，而不是许多 scattered log lines。
27. 保持 `error_code` 稳定且机器可查询；将 free-form messages 视为次要。
28. 在每个 critical operation 上记录 durations 和 retry counts。
29. 尽早添加 correlation fields；缺少 `request_id`、`operation_id` 或 `session_id` 会削弱每一个下游查询。
30. 将 operational truth 与 product analytics 分离；可以 mirroring，但不能 substitution。
31. 当 secrets、tokens、raw prompts、user content 和 full URLs 不是严格需要时，进行 redact 或 hash。
32. 默认不要 emit 巨大 blobs；改为持久化 pointers 或 summarized context。
33. 使用 `scripts/audit_queryable_outcomes.py` 扫描 repo 中可能的 operation boundaries、现有 instrumentation、correlation fields 和 durable outcome signals。
34. 使用 `references/event-schema.md` 获取 required/recommended fields、naming guidance 和 redaction rules。
35. 使用 `references/runtime-patterns-electron.md` 获取 Electron、tRPC、IPC、startup flows 和 background jobs 的 boundary choices 和 wrapper patterns。
36. 使用 `references/runtime-patterns-node.md` 获取 HTTP apps、queue consumers 和 cron jobs 的 boundary choices 和 wrapper patterns。
37. 使用 `references/rollout-and-queries.md` 获取 retrofit plan、acceptance checklist 和新的 instrumentation 必须回答的 example questions。

适用边界 · 注意事项

• 不要一开始就给仓库中所有 route 或 command 埋点；应先覆盖 top 3 用户关键操作再扩展。
• 关键操作 outcome 不应只依赖临时 console logs 或内存缓冲区；若无法持久化或查询，不适合采用此方案。
• 不要用 product analytics 替代 operational truth；二者可以镜像，不能混同替代。