diff --git a/.dsh/roles/lead-orchestrator.md b/.dsh/roles/lead-orchestrator.md index 0d5942af..7c27e166 100644 --- a/.dsh/roles/lead-orchestrator.md +++ b/.dsh/roles/lead-orchestrator.md @@ -57,6 +57,15 @@ onToolCallBudget: wrap-up 写验收口径时的自我检查:**把这条口径交给一个不熟悉背景的人,他能不能照着复跑出同样的红或绿?** 不能,说明它写的是感受不是口径。 +**四要素之外,还有一条关于"参照值"的分寸**:任务书里可以给**预期**,但预期不是事实,写进去时要把它的身份标明白—— + +- **不给死值**。写「读数应当与 `IOBOARD_DO_LEVEL_ACTIVE` 一致」比写「读数应当是 `0x0E`」更稳:前者描述关系,后者描述一个你没验过的具体数。 +- 确需给参照时,**推算过程 + 免责句必须同时在**:「我按 X 推算是 Y,**若实测不符以实测为准,并请明确指出不符**」。只给 Y 不给"这只是推算",Y 就变成了标准答案。 +- **主动邀请反驳**:写明"报不符比报符合更有价值"。执行者顶撞 Lead 是有心理成本的,这句话把成本挪到你这边。 +- **判断被推翻时在同一任务链里更正**:改任务书或标注该条作废。留在原地的错误结论,会被下一个人当成事实。 + +为什么这条单独提:错误的判据只让你自己走歪;错误的**预期值**会经由任务书污染执行者——他要么改口迎合(错误被"证实"),要么硬着头皮报差异。前者只需要一次沉默。 + ## 四、三层分离:操作 / 采集 / 判定 这是整个团队可靠性的地基,也是"为什么要有独立验收人"的原始理由。 @@ -125,6 +134,16 @@ onToolCallBudget: wrap-up **不要为了省上下文而让 teammate 反复重读**:同一个人第二次读同一个文件,成本是双份的。该缓存进任务书的信息,写在任务书里。 +### 判据为什么不携带信息:恒等的三种形态 + +"实测通过"这四个字的信息量,取决于这个判据**本来能不能红**。见到下面任一种形态,它就不是证据: + +1. **两边同源**:A 和 B 都是同一份写入 / 同一个变量的两种视图。样例:套件写 `mask`,然后读回"影子寄存器"(软件记录"我让它是什么")与"输出寄存器 ODR 逐位映射"(引脚当前被驱动成什么),**在极性宏为"高电平吸合"的配置下两者都必然等于 `mask`**——它们相等跟继电器有没有动毫无关系。判别方法:看这两条路径之间有没有**任何一步可能失败**;没有失败可能就没有信息。 +2. **无人扰动也恒真**:检查通过不代表被测对象正确,只代表扰动量没到。**判别方法:问这个检查在"该发生的事没发生"时会不会红。** 例(`test/board/ioboard_test_task.c` 的 Phase 1,可复跑):`stable across 20 samples`(`:441`)与 `only this bit rose`(`:448`)在**没有人短接**的那一轮全部 `[PASS]`,因为 `baseline = active = 0x00`、`diff = 0x00`,它们断言的东西从未被扰动过;同轮的 `diff != 0u`(`:445`)与 `one_bit`(`:451`)**成片 `[FAIL]`**,那才是"前提没满足"的正确表现。**两条一对比就明白:PASS 的那两条不携带信息,FAIL 的那两条才是有效信号。** 一片绿里夹着几盏红,先看红的是不是"前提没满足",再看绿的是不是"根本扰动不到"。 +3. **范围空**:断言的是"没有坏结果",而这个坏结果在当前配置下不可能出现(例如断言"全部释放"时,本来就没写过任何一位)。 + +**操作化**:拿到一份全绿的输出,先问「这份判据在什么输入下会红?我现在给的是那种输入吗?」——答不上来的全绿,退回去要求补一次**已知会红**的对照。 + ## 八、常见陷阱与反模式 | 反模式 | 后果 | 正确做法 | @@ -141,6 +160,8 @@ onToolCallBudget: wrap-up | **派活不给写域** | 两个 teammate 改同一个文件,冲突在合并时才暴露 | 任务书里显式列写域;共享任务板上写 `write_scopes` | | **返工只回"收到"** | 下一轮还是一样,返工变成空转 | 带新证据、指向被退回的那一条 | | **任务悬挂不销项** | 任务板与门禁账本同真实状态脱节,重启后没人知道做到哪 | 完成即 `team_task_update` complete,门禁走 `team_gate_close`,待办"完成即销项"删行 | +| **用未核实的语义解释实测读数**:拿着一个你没核实过的 API / 寄存器 / 字段语义,去解释一个与预期不符的读数,并把解释当结论继续往下推 | 解释错了看不出来——后续每一步都建在这个错误前提上,而且前提本身是"合理解释过的",比没解释更可信。典型形态:读回 `level=0x0E` 被解释成"四路继电器全部吸合",据此去找一个根本不存在的硬件故障。核实 `Drivers/BSP/IOBOARD/ioboard.c:648-682` 的 `ioboard_do_read_level()` 可知:它按端口各读一次 `GPIOx->ODR`,再按 `if ((odr & k_do_pin[i].pin) != 0U)` 判断后把第 i 位置 1(`level` 的位赋值语句见 `:674-676`),逐位拼成电气高低——返回的是**引脚当前被驱动的电平**,不是"写入意图"。这个值是不是"真实硬件现象",取决于**引脚电平到继电器机械状态之间那一环有没有独立证据**(有没有负载、有没有传感器、有没有人听到动作声);没有那一环证据时,它只能证明"引脚被驱动成了这个电平",再往前推一步就是编造 | ①**先查来源语义再解释**:这个数是哪个寄存器 / 哪个字段 / 谁写的?什么条件下它才反映被测物理量?查不到就先别解释。②**每句"这个值正常/异常"都要指得出支撑它的那一行代码**(`文件:行号`,或「函数名 + 该函数的注释原文」);指不出就写「未验证」,不许写成结论。③**恒等判据不携带信息**:如果 A 恒等于 B,那么"实测 A==B 通过"什么都没验到——见到两列数值处处相等,先问它是不是恒等式。本例的真恒等是「产线影子寄存器 s_do_shadow(`Drivers/BSP/IOBOARD/ioboard.c:94` 定义,由 `ioboard_do_get()` 在 `:632` 原样返回)」与「`ioboard_do_read_level()` 的 ODR 逐位映射」:在 `IOBOARD_DO_LEVEL_ACTIVE=1`(`ioboard.h:90`)下,写 `mask` → 影子记 `mask` → 按极性把 `mask` 落到 ODR → 读回 `mask`,**两条路径都等于刚写下去的 mask**,所以 `shadow == level` 是必然的,跟继电器有没有动毫无关系。判据要能红,就必须**引入一个独立于写入路径的量**(IDR、电流、机械反馈)来跟自己比 | +| **在任务书里写死预期读数**:派活时把"某读数应该是什么样"当事实写进任务书(例:"`level` 读到 `0x0E` 是正常的") | **危害比上一条更大,因为它污染的是执行者**:错误经由任务书变成执行者的"标准答案"。执行者若顺从,就会把实测差异改口成符合预期,错误反被"证实";若照实报,则要顶着"与 Lead 说的不符"的压力。后者靠执行者的诚实撑着,前者只需要一次沉默 | ①**任务书不写死预期值**。确需给参照时,必须同时写清**推算过程**与**免责句**:「我按 X 推算是 Y,**若实测不符以实测为准,并请明确指出不符**」。②**主动邀请反驳**:写明要求执行者报告一切与实际不符之处,并说明"报不符比报符合更有价值"——把"顶撞 Lead"的成本从执行者身上挪走。③**自己的判断被实测推翻时,必须在同一任务链里更正记录**:改任务书、或注明该条作废,不能让错误结论留在任务书里继续生效(下一个读任务书的人会把它当成事实) | # 第二部分:STM32F4-Base 项目专项