measure-before-you-fix

修复前先测量

**约定：**参见 conventions/brain-first.md — 重新推导诊断结论前，先在 brain 中 search 是否有相同告警的既往事件。重复出现的告警通常已经有记录在案的判定结果。

任何声称涉及时间的告警都应转到此处——“X 已过时”“步骤超时”“流水线卡住了”“作业很慢”“落后 N 小时”。这类告警容易让人立即着手进行结构性修复（延长超时时间、拆分步骤、重新排序流水线）。先进行测量。测量几乎总是比修复更省，而且往往能证明修复没有必要。（路由是一项 harness 约定，并非机械保证——下方的契约才是确保其落实的规范。）

在 gbrain 界面中，这包括：gbrain doctor 的过时检查（例如同步新鲜度、周期新鲜度）、autopilot 周期告警、同步停滞看门狗（reason: 'stall_timeout'），以及基于这些机制构建的任何 cron 监控。

规则

对可疑步骤进行一次秒表测量，然后再更改任何代码。

如果你说不出所声称的缓慢环节经过测量后的耗时，就还不知道根本原因；你写出的任何修复，都只是披着 diff 外衣的猜测。

契约

此技能保证：

• 在获得被指责步骤的实测耗时之前，不会提出任何结构性修复（延长超时时间、拆分步骤、重新排序流水线、重写包装器）。
• 测量针对告警指明的具体实体，而非汇总结果（--all 会掩盖哪个成员最慢）。
• 在判定系统不健康之前，会将告警阈值与权威阈值（gbrain doctor 的 warn/fail 线）进行比较。
• 判定会明确区分“需要更多时间”和“已卡住”——两者的修复方法截然相反。
• 只读：此技能不会更改超时时间、阈值或代码。它会给出测量判定，为修复确定合适的规模；修复本身是另行进行的、如今已有测量依据的更改。

流程

1. **读取告警自身的数据。**它们往往已经与推测相矛盾。 （Locks: none 意味着并非锁竞争。记录这一点，并排除这条可能性。）

2. **直接测量可疑步骤的耗时。**隔离告警所指的最小单位，并计时运行：

   time gbrain sync --source source-a --no-embed
   

   针对具体指定的实体运行，而非汇总结果。对整个 brain 运行会掩盖哪个成员最慢；--source source-a 可以回答这个问题。使用 gbrain sources status 交叉核对状态（各来源的同步延迟）。

3. **比较实测值与预算值。**搜索包装器中的每一个超时设置，而不只是辅助函数签名中的默认值：

   grep -n "timeoutMs\|timeout:" <the wrapper or cron script>
   

   宽松的单次调用覆盖值会让辅助函数的默认值失去意义。责怪默认值之前，先检查调用点。

4. **将告警阈值与权威阈值对照。**在断定系统故障之前，先确认告警器和审计对“异常”的定义一致。gbrain doctor 的同步新鲜度检查默认使用 24h warn / 72h fail（可通过环境变量 GBRAIN_SYNC_FRESHNESS_WARN_HOURS / GBRAIN_SYNC_FRESHNESS_FAIL_HOURS 覆盖）；若 cron 监控在 12h 时就触发告警，就低于权威 warn 线。监控提前采取行动是正确的；监控在采取行动的阈值就发出告警，则会制造误报。

5. 现在才设计修复方案——依据测量得到的数据。

阈值不匹配的故障模式

cron 监控在 doctor 判定失败之前提前采取行动是合理的，可以避免进入 FAIL 状态。这是良好的设计。问题在于复用行动阈值作为告警阈值：所有处于“行动”和“警告”之间的情况，都会演变成反复告警，尽管系统本身健康。

**将这两个常量分开。**在更严格的阈值采取行动，在权威阈值发出告警：

const ACT_HOURS = Number(env.MONITOR_ACT_HOURS || 12);      // act early — fine
const ALERT_HOURS = Math.max(ACT_HOURS, DOCTOR_WARN_HOURS); // speak at the audit's line

请立即识别这一症状：告警反复出现，告警中的数据低于 doctor 自身的 warn 线，但直接查询底层资源时却显示正常。

你是在推测而非诊断的警示信号

• 你找到了根本原因，却没有测量耗时。

• 你的修复方案是重写，但你还没有实际运行过这一步。

• 你两次修改了推测，却没有在两次修改之间进行新的测量。

• 警报显示“没有恢复正在进行”——在相信之前，先确认恢复是否确实在运行（用 ps 检查工作进程；检查启动标志；用 gbrain jobs list 查看排队任务）。

• 步骤输出中出现“已是最新”。这一步不是瓶颈。

失败时

遇到任何 gbrain 错误 code、退出代码、[AGENT] 块或通知块时，请遵循Agent 操作员协议。此技能的具体注意事项：

• gbrain doctor 发出警告或失败：在判定系统不健康之前，记录具体检查项和阈值；doctor 的 24h/72h 同步新鲜度阈值可能与 cron 监控器的阈值不同。
• gbrain sources status 显示有项目被挂起或出现 lock_busy：这就是测得的原因；先修复并重新测量，而不是提高超时设置。

反模式

• 通过延长超时来解决卡顿。 如果步骤确实卡死，更大的时间预算只会让它卡得更久。先测量，再判断是“需要更多时间”还是“已卡死”——这两者的修复方法截然相反。（gbrain 的同步卡顿看门狗也会原生地区分两者：它依据进度而非经过的时间进行判断。）
• 基于未经测量的资源饥饿推测重写流水线。 拆分步骤来解决并不存在的资源饥饿，只会增加复杂度，毫无帮助。
• 相信警报对因果关系的判断。 警报能准确报告症状，却很难准确找出原因。过时时长是真实的；附带的原因只是猜测。
• 将未经测量的根本原因固化为技能或持久化记录。 把错误诊断自信地写进操作手册，比原始 bug 更糟。

已处理的已知故障模式

• 对新鲜度警报连续做出三次错误诊断。 cron 监控器反复发出警报，称两个源（source-a、source-b）已过时数小时。尚未进行任何测量，就接连断言了三个根本原因，并批准重写封装层。实际测量结果： time gbrain sync --source source-a --no-embed 在几秒内完成，并显示“已是最新”（source-b 也是如此），而 gbrain sources status 显示所有源当天早上都已同步。所有推测同时被推翻。实际原因：监控器在其操作阈值触发警报时，距离 gbrain doctor 权威警告线还差数小时。修复只需两行（ALERT_HOURS = max(ACT_HOURS, WARN_HOURS)），而非重写。经验：当系统测得健康，但警报反复出现时，先怀疑阈值，而不是系统本身。
• 同一轮检查中发现的资源争用推测附带问题： 对一个被降低优先级（通过 nice 设置）的步骤存在 CPU 争用疑虑，但同样毫无依据——即便主机持续承受并发负载，该步骤也在几秒内完成。资源争用推测和过时问题一样，都需要用秒表验证。

输出格式

输出应为测量判定（对话级；此技能不会写入任何 brain 页面）。只有得出判定后，才提出与测量数值相匹配的修复方案：

## Measurement verdict
- Alert:      <the alert text and which monitor emitted it>
- Claim:      <the temporal claim, e.g. "source-a 14h stale">
- Measured:   <exact command> → <duration> (<key output, e.g. "Already up to date">)
- Budgeted:   <timeout constant + any call-site override, file:line>
- Thresholds: monitor act-line <X>h vs doctor warn-line <Y>h → <match | MISMATCH>
- Verdict:    false page on healthy system | needs more time | wedged | genuine regression
- Fix:        <the change, justified by the measured number — or "none; adjust the alert line">

去重（边界明确）

• GStack investigate — 系统地调试代码缺陷（“为什么这个坏了”、500 错误、输出错误）。边界：investigate 找出代码行为的根本原因；此技能是在触及任何超时或阈值之前，针对时间相关的运维告警（过期／超时／新鲜度／卡死）执行的先测量关卡。如果秒表确认确实存在变慢或回归，则将测得的数值交给 investigate。
• skills/maintain/SKILL.md — 运行大脑健康检查并修复问题（doctor、提取、梦境周期）。边界：maintain 生成健康检查输出并据此采取行动；此技能规定当其中一项检查触发页面告警时，在更改预算或包装器之前该如何响应。
• smoke-test（主机端） — 重启后执行二元健康检查，并自动修复。边界：smoke-test 回答“重启后服务是否正常运行”；此技能回答“这个缓慢／过期的说法是否属实”。
• skills/cron-scheduler/SKILL.md — 安排监控和作业。边界：cron-scheduler 决定监控何时运行；此技能提供阈值必须编码的行动线与告警线规则。
• skills/conventions/test-before-bulk.md — 对变更执行先试验再批量操作。同样秉持先有证据再行动的理念，但对象不同：该约定把关批量写入；此技能把关超时／阈值／流水线的变更。