diagnose-and-explain

诊断并讲清楚

目标不是给出最像答案的猜测，而是建立足以推翻错误结论的证据链，找到问题发生的机制，并让不了解领域的用户真正看懂。

推理底盘与权限

• 先完整读取并使用 $first-principles-adversarial-review。把用户给出的原因和首个合理解释都视为待验证假设。
• 默认自主进行只读调查：读取代码、配置、日志、文档、接口契约、数据只读结果、历史差异、已有正常样本和同类实现。
• 不因发现疑似根因而自动修复。修改代码、配置、测试、文档或数据，添加持久化埋点，以及提交、推送、部署、发消息或更新外部系统前，必须说明拟操作及影响并获得明确确认。
• 运行可能写入状态、触发真实业务、污染数据或影响外部系统的复现与探针，不属于只读调查，必须先确认。优先使用隔离、可回滚、无副作用的验证方式。

调查工作流

0. 先约定诊断的停止条件

用户要求分析报错或找根因时，告警摘要、错误栈转述和“下一步可以查日志/代码”都只是调查入口，不是诊断结果。只要当前权限内还有可访问、低风险，并且可能改变根因判断或结论强度的代码、日志、配置、数据只读查询或正常对照，就直接继续调查，不把本可自主完成的下一步留给用户再次追问。

首轮调查持续到满足以下任一条件：已经形成经过关键反证的根因结论；可用事实源已经穷尽，只能给出有边界的候选原因；继续取证需要用户提供专属材料、开放环境访问或授权有副作用的操作；剩余查询即使得到不同结果也不会改变结论。受阻时说明已经查了什么、具体缺什么，以及缺失证据会区分哪两个候选，不用“后续还能继续分析”掩盖尚未完成的低成本只读调查。

1. 固定问题与事实源

先明确期望行为、实际现象、发生时间、影响对象和判断问题存在的信号。技术问题追踪真实入口、调用链、数据流、状态和错误路径；业务、产品、流程或数据问题追踪参与者、生产者、消费者、规则、指标口径、状态转换和反馈环。

优先检查最新、最接近运行时的事实源。注释、文档、字段名、历史记忆和用户猜测只能作为线索。无法验证时明确标记“推断，未验证”。

问题可能跨环境、地域、租户、账号或部署时，先固定一条可核验的环境身份链：用户实际访问的域名或入口 → 运行时集群、namespace、deployment 与镜像 → 配置中心及其 namespace/group/dataId → 最终数据库、缓存或消息队列实例。以运行时值为准；仓库默认配置、相同版本和相似响应只能作为线索。环境身份链尚未闭合时，不把某个环境的日志、配置或数据当成另一个环境的直接证据。

把业务对象识别为复合身份，而不是裸 ID：至少包含环境身份、事实源和业务 ID，必要时再加租户与时间范围。跨库关联项目号、任务号、订单号等可能重复的编号前，先用域名、集群、配置实例、时间、消息内容或文件路径证明两边属于同一对象；不能证明时，只能作为跨环境对照，不能支撑当前环境的根因。

2. 建立反馈闭环

能安全复现时，建立一个针对用户准确症状的清晰通过/失败信号，而不是只验证“没有崩溃”。优先选择现有测试、只读查询、日志对照、请求回放、历史前后对比或正常样本对照。

让闭环尽量稳定、快速、具体。若问题偶发，设法提高观测或复现概率；若能缩小样本、步骤、输入或参与者，则逐项删除非必要因素，找出最小成立条件。

“无法稳定复现”不是广义诊断的停止条件。对线上事故、业务异常或一次性事件，可以使用时间线、审计记录、多源交叉验证和排除法，但必须降低结论置信度并说明缺失的证据。不得为了满足复现要求制造有副作用的操作。

3. 沿组件边界取证，并检查证据是否独立

问题跨越两个及以上组件、角色或流程节点时，沿边界记录信息在哪里第一次偏离预期。按需使用下表，不为简单单因问题强行套模板：

边界	输入	输出	配置或状态	期望与实际	证据来源

不要把同一事实的多个转述误算成多份证据。来自同一请求链的应用日志、聚合告警和截图通常是一个证据渠道；注释和复述也不是独立的运行时证据。可重复实验、当前运行时或原始日志、真实配置或数据、独立正常对照等来源若彼此不依赖，才可以叠加提高置信度。证据互相矛盾时，先解释矛盾或降低结论强度，不按数量投票。

多个环境出现相似症状时，按环境分别列出入口、生产者、消费者、运行时配置、事实源和失败边界，再寻找共同原因。页面都为空、错误文案相同或接口响应一致，只能证明症状相似；只有各环境在同一已验证边界以同一机制失败，才能合并为一个根因。尤其要分别验证“上游是否仍在生产数据”和“下游是否能读取数据”，避免用修复读取配置掩盖上游已停止写入的问题。

4. 先找等价正常路径，再判断哪一层需要改