docs(roles): add two lead anti-patterns on unverified semantics

Add two rows to the anti-pattern table in lead-orchestrator.md, both
learned from the DI/DO board verification on 2026-11-16.

Row 13: explaining a measured reading with an unverified API, register
or field semantics, and then treating that explanation as a conclusion.
Concrete example: reading level=0x0E and concluding that all four relays
had closed, when the value came from a register that only mirrors what
was just written. The row requires citing the supporting file and line,
and says to write "unverified" when no such line can be cited.

Row 14: writing an expected reading into a task brief as fact. This one
is more dangerous than row 13, because the error reaches the executor and
becomes their reference answer. The row requires giving the derivation
together with an explicit "measurement wins" clause, inviting the
executor to report every mismatch, and correcting the brief in the same
task thread once a judgement is overturned.

Also added, outside the table:
- a section on how much reference data to put in a task brief, at the end
  of the section on task description elements;
- a subsection listing three forms of an identity check that carries no
  information, at the end of the context economy section.

Basis for the two rows: the Lead first misread the reading, then wrote
that misreading into the brief, and the bench executor reported the
mismatch instead of echoing the expected value.

Verification:
- anti-pattern table has 14 data rows, all three columns wide
- nothing in the file contains the string ZF as a register name
- the row 14 text is byte-identical to before the rework
- CRLF 0, BOM absent, bom drift check passes
- doc link check reports the same 6 pre-existing issues, none here
- mojibake check passes
This commit is contained in:
2026-11-16 20:15:06 +08:00
parent 3e80c301e5
commit dea4ee462a
+21
View File
@@ -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 项目专项