systematic-debugging

执行

Bug、故障或意外行为：

1. 隔离 — 阅读错误信息、复现问题、检查差异，并沿诊断层级向上深入： L1 症状 → L2 逻辑 → L3 系统 → L4 架构 → L5 跨系统 契约 → L6 平台 → L7 规范缺口。层级是观察高度， 并非单一因果链；在停止的高度，必须先明确分类因果形态， 然后才能提出任何根因结论。只有在因果证据解释了 复发诱因，或到达 T 类边界时，才能停止。
2. 确定负责人 — 对比正常行为，追踪异常值，定位权威负责人，并将负责人重复视为一项发现。
3. 编辑前先决策 — 涉及共享逻辑、契约、回退机制、适配器、生产者／消费者接缝或事实来源边界时，修复前运行补丁形态分流和涟漪信号分流。对任何新增源代码路径或非简单源代码编辑，明确变更必要性。新增分支、回退机制、适配器、负责人或兼容路径时，运行最小性检查；负责人过载或复杂度增长时，运行编辑前复杂度检查。变更必要性选择 code-change 后、首次修复编辑前，按照 test-driven-development 为修复范围确定 TDD 路径（默认 off；行为／Bug 修复／共享逻辑／契约／持久化／权限／迁移风险时设为 strict）。
4. 验证 — 用最小复现或验证检验一个假设。只有记录了 TDD Route: strict 时，才必须先编写失败测试；若 TDD Mode: off，不要要求失败测试或 RED/GREEN 循环。三次修复失败后，停止并质疑架构。
5. 修复并收尾 — 在权威负责人处进行最小修复，按风险程度进行验证，审查架构，并完成修复和退役两条跟踪。如果症状仍然存在或发生变化，重新审视因果模型；不要假设这是独立缺陷。

完成条件：置信度 ≥ B，因果状态与复发证据或外部终止条件相符，跟踪项明确，无 H 信号，且所需的 D 证据通过。

核心不变量

找出根因，并在其权威负责人处修复此类 Bug。最小修复并非文本差异最小，而是负责人层面足以解决问题的最小修复。对每个 Bug 应用相同的因果充分性标准。追踪相关影响并说明排除理由；在保留解决方案前，解决所有会影响修复方案的未知项。实验可以先于收尾。调查深度应由证据缺口决定，而非表面规模或风险。

快速 Bug 通道

对于有证据支持、可复现、由单一负责人负责且没有补丁形态信号的本地 Bug，精简记录内容：Symptom、Reproduction、Root Cause、Change Necessity、Fix Boundary 和 Verification。只有在因果证明负责人的“快速退出证明”通过时，才可省略因果卡片。这只会减少记录内容，不会降低因果覆盖范围或证据标准。 快速 Bug 通道必须在源代码编辑前明确变更必要性。可以用一句话说明用户可见的需求、不变更／非代码选项、必须修改代码的原因、最小边界，以及明确的决策标记，例如 Decision: code-change。如果出现共享逻辑、契约、回退机制、重复负责人、消费者端补丁或跨模块行为，请退出此通道。

Aegis Visibility 指明证据／负责人／补丁形态／验证的影响。 将根因、避免的错误修复、边界、证据、复杂度和风险传递给 verification-before-completion；无需单独的回执。

修复前先诊断

对于 UI/交互缺陷，在用户可见的交界处组合使用 ui-ux-governance，以确定相关状态和恢复规则。此处负责复现和根因；提出的手动检查不等于已执行的证据。

1. 阅读完整的错误信息/堆栈，并记录输入、环境、版本和成功标准。在正确的对象上复现用户遇到的失败结果，直至最终交付；成功解析或内部检查通过可能会掩盖故障。验证修复后的行为和一个相关的相邻案例，而不是硬编码示例。只读诊断不授权修复。
2. 稳定地复现。如果复现不稳定，仅当证据显示复现具有间歇性或依赖时序时才阅读 feedback-loop-construction.md，并构建有界循环。将复现缩减为作为测试输入的关键要素，而不是缩小修复范围：仍要向上追查；在正确的交界处测试。
3. 检查近期更改，并与正常工作的示例进行比较。代码是证据；如果权威定义、术语表、代码和测试相互矛盾，应组合使用 establishing-project-context，而不是悄然重新定义术语。
4. 在组件边界添加检测，然后沿着错误值追溯其来源。仅当观测到的错误值位于其来源下游的多个调用或组件之后时，才阅读 root-cause-tracing.md。 对于任务失真，沿着 source → understanding → expression → execution → delivery 追踪，直到找到第一个有证据表明含义发生变化的位置。这能确定观测到偏差的位置，但不能证明根因；应复用足够且当前有效的证据。
5. 提出一个假设，并用单变量证据证伪。不要叠加推测性的修复。每轮结束时记录 Goal | DeeperCause | Evidence | Risk/Unknown | Decision。

规范所有者与补丁形态关卡

编辑前，除非有证据证明本地位置是规范所有者，否则只要候选项属于以下任一信号，就继续向上追查：

• 关键词、短语、正则表达式、否定词列表或示例文本例外；
• 本地保护逻辑、额外条件、try/catch、提前返回或一次性分支；
• 回退方案、适配器、兼容性分支、提示词分支或旧路径扩展；
• 消费方/调用方/就绪层/展示层补丁；
• 下游逻辑重新解析原始文本，或在存在类型化意图、规范化状态、契约或其他事实来源时重新推断操作/状态；
• 未证明生产方/所有者身份的产物/下载/导出/回读/缓存补丁。

PatchShape:
CanonicalOwner:
UpwardDrillSignal:
Decision: fix owner | continue investigation | escalate

本地测试通过不能消除分诊要求；更名后的载体并不代表新的方向。

如果修复可能重新解释或废弃现有语义、责任、契约或关系，应明确说明要保留的行为、风险最高的反例以及重要未知项。对于每个已知的明确锚点或上游/下游引用，应说明其作用和处置方式：保留、重新绑定到规范所有者、有理由地废弃，或因冲突而拒绝。未解决的关系应保留为未知；不要在下游重新推断。先绑定角色，再处理值；废弃无效责任，而不是废弃缺乏证据的载体能力。此有界提醒并非行为矩阵、关系图、引用完整性证明或穷尽式发现声明。它不会增加任何产物、TDD 风险信号或回归范围；现有 TDD 路由所有者以及已配置/默认模式仍然适用。

如果诊断超出 L3、触发补丁形态信号、用户质疑根因声明、先前的修复仍留下症状、存在复合/根因拓扑的可能、同一事件存在两个或更多有锚点的表现、不同发生情形的复现条件不一致，或者尚未排除上游生产方/配置/默认值/契约/规范，则应在声明根因之前阅读 root-cause-claim-contract.md。该文档是 Pre-Claim Gate、因果闭合/证伪证明、层级上限证明以及 Causal Topology Gate 的唯一所有者。

变更必要性

此决策由行为触发，而非由提示词触发。它适用于任何新的源代码路径。在引入该路径或进行非平凡的源代码编辑之前，先明确 Change Necessity 决策（no-change | docs/config-only | code-change | needs-clarification）；具体字段详见 advanced-debugging-governance.md。

最小性与负责人匹配

对于任何拟议的分支、回退方案、适配器、兼容路径或新负责人，运行 Minimality Check（字段见 advanced-debugging-governance.md），并给出判定：sufficient repair | local patch | needs first-principles review，同时废止无效职责：local patch 需要说明保留理由并设定废止触发条件。对于新的非普通修复界面，运行 docs/current/AEGIS_MINIMALITY_REFERENCE.md 中的 Existence Check。如果废止涉及旧代码、外部兼容性或持久状态风险，则组合使用 anti-entropy-governance；它会选择废止路径，但绝不授予 破坏性操作权限。

编辑职责过载或用途混杂的负责人之前，完成 Pre-Edit Complexity Check 和 Pre-Edit Owner-Fit Decision（模板见 advanced-debugging-governance.md）。

使用 using-aegis/references/complexity-governance.md 识别压力信号。 默认不要就地添加 new-responsibility。如果更安全的边界 会改变已批准的方案形态，请先更新计划／规格。

修复与按比例验证

在负责的负责人处修复实现预期范围结果所需的每个有证据支持的原因；不要强行把独立原因归到同一负责人，也不要捆绑“顺手”工作。在严格 TDD 下，先编写最小的失败测试。关闭 TDD 时，复现是诊断证据，不是 RED 门槛，也不是生产代码编辑的前置条件。

验证必须与风险相匹配：

• 本地单一负责人修复：原始复现加针对性回归测试；
• 共享／契约／跨模块修复：规范负责人以及受影响的使用方 和兼容性边界；
• 回退方案／负责人废止：主路径、残留引用、负向和 边界检查；
• 时序／并发修复：仅当证据指出轮询、休眠或竞态时序是原因的一部分时，才阅读 condition-based-waiting.md；
• 穿越多个受信边界的无效状态：仅在已明确根因修复，且证据表明需要第二个独立验证边界之后，才阅读 defense-in-depth.md。

在再次修复之前，若修复失败／问题持续／结果不一致或已失败三次，则阅读 advanced-debugging-governance.md；若存在不明确／有争议的停止条件／Layer Stop Card／干预，或可能存在复合根因，也应阅读。收尾触发条件：修复新增的补丁形态；多处修改／一次回归；残留模式／异常／重复代码／负责人错误／下游修复；未检查同症状修复；复发问题未解决／根因状态无依据；缺少复合拓扑特定成员／反伪装证明；仓库外权限；已发布契约破坏但未迁移；规格未定义；缺少权限／信息。这些情况会触发 H/T/D；细节不能证明因果关系。

对于配置了工作区支持的非平凡调试，使用 <aegis-workspace-helper> 对目标项目执行 init、new-work、add-evidence 和 check。 命令详情见 long-task-continuation。

失败尝试使用 <aegis-workspace-helper> add-attempt；add-evidence 仅用于终端操作。

快速修复 bug 或快速修复压力不能成为跳过流程的理由：如果触发 Ripple Signal Triage，请在编辑前记录，并验证规范负责人以及受影响的下游路径。 记录仅供参考，不构成完成授权。

闭环

始终报告：

• 修复 — 原因、负责人、最小改动、兼容性、验证。
• 退役 — 无效的职责状态、载体／能力处置、保留原因／触发条件、移除检查。

确认复现、同模式处理、权威性、复杂度和退役。为调试日志添加前缀（例如 [DEBUG-a4f2]）；关闭前确认通过一次 grep 即可移除。置信度：A = 有直接回归证据；B = 有有力证据，且未知因素范围有限；C = 证据不完整，问题尚未解决。

Trace Digest 可概述审计证据；切勿暴露思维链，也不得替代根因、规则效果和验证证据。