Debug Principles（渐进式调试方法论）

核心：先建浅层失败索引，再小批量归因，用失败集 diff 验证，周期性重聚类。 早期分组是暂定签名，不是根因真相。

1. 失败范围分级

2. 渐进式循环

1. 收集输入证据：优先用户指定路径；检查测试日志、panic/assert 位置、超时消息、返回码。LTP 问题先读测例源码和 helper，不要凭测例名猜测。
2. 建浅层失败索引：按可观察签名分类（panic 位置、errno、失败的 syscall、模块、超时、日志关键词、架构、调用路径）。标记为暂定签名，第一轮不做全量根因分析。
3. 选小批代表：从相同/相邻签名中选 1-3 个。优先选日志清晰、分数影响大、环境噪音小、子系统重叠强的用例。说明为什么这些代表、什么结果会合并/拆分/推翻当前分组。
4. 向不变量调试，而不是向测例调试：
   • 先从源码/可靠参考确认期望的 Linux/POSIX/LTP 行为。
   • 形成带证伪条件的根因假设。
   • 识别被违反的不变量、ABI 规则、状态所有权规则、锁/生命周期规则。
   • 提出修复该规则的最小改动——目标不是让单个用例通过。
   • 证据仍间接时，要求最小额外日志/追踪/定向重跑，不要夸大确定性。
5. 验证并记录失败集 diff：重跑代表用例 + 最小相关回归集，记录什么消失、什么保留、什么新增失败。多个不同观感的失败一起消失 → 向后合并失败族；只有单个用例通过且无法解释相邻用例 → 可能是 case hacking，回到第 4 步复查不变量。
6. 周期性重聚类：几个修复后或失败数显著下降后，重扫剩余失败并更新分组。旧分组只在解释修正时保留为历史。

3. 证据边界

• 原始日志、临时索引、暂定假设、探索性笔记：放用户私有调试目录，需要存活时保留，不进公共文档。
• 公共文档只收：稳定结论、验证结果、已接受限制、仍活跃的缺陷。
• 私有归档结构（仅当有用时）：

<user-private-debug-dir>/<YYYY-MM-DD-slug>/
  README.md            # 状态、输入日志、当前签名、主导假设、证伪条件、下一步验证、计划回写
  failure-index.md     # 批量/战役失败时可选
  logs/                # 原始或裁剪日志

4. 输出纪律

• 严格区分：症状 / 失败签名 / 假设 / 已证实根因 / 修复 / 验证。
• 假设保持暂定，直到证伪证据闭合它。
• 说明剩余风险与下一个最小验证步骤。
• 保留无关的工作区改动和无关失败，不混入结论。
• 公共文档不默认贴原始日志；提炼决定性几行，注明证据日期与验证是 agent-run / user-run / not-run。