docs: document otel trace window drilldown

.agents/skills/unidesk-otel/SKILL.md

@@ -98,6 +98,23 @@ OTel trace 内常见业务关联属性：
 
 旧 trace 不会因为后续 instrumentation 修复自动回填。若旧 trace 查不到错误 span，但新的 canary/真实 trace 能查到同类 `runner_error.*` span，应把旧 trace 结论写成“当时未采集到该事件”，不要倒推出运行面没有发生过错误。
 
+## Trace 读取窗口与乱序调查
+
+排查 HWLAB/Workbench trace 乱序、分页缺口、`--after-seq`/`--tail` 不生效、旧 trace 只返回局部事件或 read model 是否完整时，优先查 `trace_events_read` span：
+
+```bash
+bun scripts/cli.ts platform-infra observability trace \
+  --target D601 \
+  --trace-id <otelTraceId> \
+  --grep trace_events_read \
+  --limit 20 \
+  --full
+```
+
+摘要里重点看 `returnedEvents`、`sinceSeq`、`limit`、`fromSeq`、`toSeq`、`totalEvents`、`hasMore`、`fullTraceLoaded`、`rawEventCount`、`maxSeq`、`traceLastSeq`、`endSeq` 和 `commandFiltered`。这些字段用于判断“查询窗口是否正确传到后端”“后端是否只返回了局部事件”“read model 是否已经加载完整 trace”。若 `errorSpanCount=0` 但用户可见 timeline 仍乱序，先把结论写成展示/投影/renderer 调查 issue，不要把它定性为后端错误 span。
+
+旧业务 trace 在 runtime 重启或保留策略后可能只剩局部事件；OTel 只能证明读取窗口、span 和当时观测到的字段，不能自动恢复业务事件流。需要验证新 instrumentation 时，使用新 canary 或仍可完整读取的真实 trace。
+
 ## 何时先改进 OTel
 
 遇到以下情况，先修 OTel CLI 或 instrumentation，再继续业务排障：