用途
debug-broken-ui 面向一种具体的排查困境：Web 应用运行异常，但源码看起来没问题，控制台也没有明显报错。此时重读源码无法给出答案，因为证据在运行中的应用里，而且大多不会出现在屏幕上——失败的请求、从未变化的状态存储、从未绑定的处理函数、被不可见元素遮挡的控件。
该技能从页面内部读取这些证据，核心原则是：不要从猜测开始，要从复现开始。
主要能力
技能提供了一组工具，围绕“复现—观察—定位”展开：
- reticle_look：查看页面或元素。以 interactive 模式查看页面可获取带 ref 的控件；查看元素可返回其组件与源码位置 { file, line }，以及是否被遮挡、尺寸、是否禁用、是否偏离主题等。查看 state 可读取指定 store。
- reticle_act_and_wait：执行动作并等待某个结果，例如点击某个 ref，直到某个 testid 的元素出现。
- reticle_act：以 steps 数组驱动较长流程，一次断言，避免 act → snapshot 反复往返。
- reticle_observe：观察 console 或 network，可传入 since 限定从某个时间点之后的范围。
- reticle_scroll_to：滚动到目标元素，用于虚拟列表尚未挂载的元素。
- reticle_storage：读取存储，用于排查 token 未持久化等“看起来已登录、行为却像未登录”的问题。
- reticle_session：提交反馈，例如用 kind: "gap" 报告 Reticle 未能看到所需信息。
使用方式
资料给出的起点是复现，然后是读取 act 结果。act 结果的 summary 块本身已包含一次点击的完整因果窗口：net { total, errors, headline }、consoleErrors、stateDiffs [{ path, from, to }]、storageDiffs [{ key, from, to }]、route、signals、layoutShift、longTasks，都是真实的 before→after 差异而非计数。console、network、storage、state 调用是用于深入 summary 已指向的某个方向，因此不要在 act 之后立刻把三者全部调用一遍，那会为已经掌握的证据多花三次模型往返（在需审批的客户端还要多三次人工点击）。
verdict 本身已经缩窄了范围：no / contradicted 表示某个通道看到了与界面不兼容的情况，即存在 bug；unknown 表示 Reticle 驱动了流程但无法判断，这与“它失败了”是不同的调查方向。
summary.stateUnwatched: true 表示状态通道是黑的：没有注册可订阅的 store，此时空的 stateDiffs 意味着“未被观察”而不是“没有变化”，在有人注册 store 之前无法得出基于状态的结论。
当 summary 指向某处时，应把观察范围限定在刚执行的动作之后，例如把 act 结果中的 since 传给 reticle_observe，否则读到的缓冲早于本次点击。
诊断对照
- 完全没有发出请求：处理函数未绑定，或客户端缓存返回了过期值。下一步可查看元素获取 file:line；若使用 TanStack Query 则检查缓存。
- 请求发出但返回 4xx/5xx：UI 吞掉了一次真实的后端失败。响应体在网络记录中。
- 返回 2xx 但什么都没变：应用没有读取响应，verdict 会显示 outcome_unread，通常是成功路径中的真实 bug。
- 请求正常、DOM 正常，但 store 过期：UI 与状态不同步，任何截图都看不到，reticle_look 的 state 是唯一见证者，也是这里价值最高的读取。
- 点击无反应且无错误：控件失效、被遮挡或已禁用。查看元素会返回 occluded、box (0×0)、styles.cursor、opacity。
- 肉眼可见却提示“找不到”：虚拟列表尚未挂载它，使用 reticle_scroll_to。查询未命中不等于元素不存在。
- 看起来已登录、行为却像未登录：token 从未持久化，使用 reticle_storage。
- 早于本次点击的控制台错误：属于既有故障，不是当前 bug，继续前应先指出。
定位与验证
调查应以位置而非假设收尾：通过 reticle_look 查看元素，得到所看元素的组件与源码 { file, line }。
流程较长时，用 reticle_act { steps: [...] } 驱动整个旅程并一次断言，第一个后果不符的步骤就是应查看的对象。
在声称修复之前，应把复现重跑为 verdict（使用 reticle_act_and_wait 并预先指明期望后果），而不是用眼睛看页面。通过肉眼查看确认的修复，正是产生这类工单的失败模式。并且绝不要为了让检查通过而削弱检查。
另外，若问题出在 Reticle 本身而非应用，可参考 https://docs.reticle.sh/troubleshooting.md；其他文档见 https://docs.reticle.sh/llms.txt。若 Reticle 看不到需要的信息，可用 reticle_session { action: "feedback" } 并指定 kind: "gap"。
安装
若未安装，可使用 RETICLE_INSTALL_SOURCE=npx_skill npx @reticlehq/server@latest init，然后配合 install-and-verify 技能。
适用场景与限制
适用于排查运行中 Web 应用的界面与交互故障，尤其是控制台无报错、源码看似正确的情况。资料未提供该技能的收费、价格、支持平台或效果保证等信息。