Files
STM32F4-Base/.dsh/skills/stale-doc-count-sweep/reference/pitfalls.md
T
wandering1 e4981aa2f6 refactor(docs): point entry-file references at their new homes
AGENTS.md stopped being the store of record for build steps, Python env,
hardware pins, doc conventions, log cost and task ownership. Those facts
already live in docs, skills and role files; the entry file now only
points at them. This commit moves every reference that used to name the
entry file to the authoritative landing point, so a reader who follows a
link arrives at the fact instead of at a sentence that no longer exists.

What changed is links and prose, not behaviour. Code, scripts and tests
only have comment and docstring lines touched; the only non-comment edit
in the whole changeset is one note string inside the generated pin table
JSON, and its generator was changed in the same step so the two stay
byte-identical.

New landing points created before the references were retargeted:
- The console single-writer log design doc, section 7.1, is now the single
  authority for log cost: about 90 B flash and 216 B stack per DBG_ line,
  and the rule that deep call chains must predefine DBG_LINE_BUF_MAX.
  It also carries the full list of the twelve translation units that have
  tightened it, plus the grep command that decides the truth if the list
  and the code ever disagree.
- The document writing standard, section 2, now holds the BOM list.
- keil-build skill gains an exit code table: 0 success, 1 build failure,
  2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief
  that was never actually written down anywhere: exit 2 does not simply
  mean environment error, argparse also exits 2 and the wrapper script
  was remapped so the two no longer collide.

Regenerated and checked byte for byte:
- The end-to-end architecture SVG in docs/images from its generator.
- tools/netlist_semantics/pinout_kb.json from gen_kb.py.
Both are idempotent; running the generators again produces no diff.

Deliberately not touched, because machines read them:
- scripts/check_bom_drift.py joins every line containing BOM and asserts
  four paths are present, so the entry file BOM line must stay one line.
- scripts/gen_task_table.py reads the TASK_TABLE anchors directly.
- scripts/rename_maps and scripts/archive keep their historical wording;
  they describe what happened, not what is true now.

Verified: doc links report the same six pre-existing findings as the base
commit and no new ones, generated-fresh passes, bom drift is clean across
101 files, and AGENTS.md itself is unchanged in this commit.
2026-11-16 19:38:27 +08:00

5.1 KiB
Raw Blame History

Pitfalls(自 SKILL.md 外置)

本文由 stale-doc-count-sweep 的 SKILL.md「Pitfalls」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。

  • 把伪命中计进真值:grep '#page=' 的首条是菜单文件头部注释里的示例行,29 里含它;真值是注册表 UI_PAGE_MAP_COUNT 的 28。任何「数出现次数」式计数,先打印全部命中逐条看,剔注释行/模板行/示例行。
  • 字形数没剔 notdef:.bitmap_index 314 条里第 1 条是 notdef,字形数是 313;照抄 314 就把占位符当成了字形。
  • 数字对但口径描述错:218 这个数两处都对,错在「含 ASCII/符号」这句口径(实测 218 个码点全为非 ASCII)。它不进任何数字 diff,只能逐句读口径句;且必须另起一笔,混进数字同步那笔会让 review 者以为只是顺手改措辞。
  • 权威脚本乱码就臆读或退回抄文档:Windows 代码页下 font-charset 的整行输出退化成 U+FFFD 替换字符时,改数源文件符号出现次数,别猜、别抄旧文档。
  • 钩子数用 grep 声明行:多算一条注释掉的候选钩子(51 变 52);反过来在配置注释里复述那个 grep 字面量会让文本计数再虚高 1。口径只认 YAML 解析后的条目数,且要与 AGENTS.md 提交门禁节「共 N 个钩子」、docs/门禁说明/README.md §2 标题、ci_local.py 实跑 passed+failed+skipped 三数同源。
  • 张数与页数互相冒充:一个 12 行分页页第 2 页要单独拍一张,于是「+2 页」可能等于「+3 张」。两个数分别报、分别换算,别互相顶替。
  • 数篇数只 grep 裸标题:^## 变更记录 漏掉 ## 6. 变更记录、## 九、变更记录、## 修订记录 三种写法 → 篇数直接少数一半,拿这个错数去"同步"全仓就是把对的改成错的(2026-10-29 实测:5 篇真台账只数出 3 篇,改到第 10 处才发现)。普查一律 grep -rn "^## " docs scripts 再看标题,或直接读 docs/文档规范.md §5.1 那行的例外清单。
  • 只扫 docs/:漏 .pre-commit-config.yaml 钩子 name: 显示名里的页数、AGENTS.md 提交门禁节的钩子数、.dsh/skills/*/SKILL.md 自带的计数与脚本路径(skill 正文也是命中面:font-regen 的 179/274 本窗最后才改)。
  • 提交完就收工:第 7 步的提交后复扫才是把漏网当前态(架构总览 §3)揪出来的那一步;漏了它,仓库里就留下一行「当前态写旧数」直到别人再扫。
  • 去已删掉变更记录的文档里「补一行流水」:2026-10-29 起全仓只剩 5 篇真台账保留变更记录表(清单 → docs/文档规范.md §5.1),外加 scripts/archive/ 归档;其余文档没有这一节。计数同步只改当前态、过程交给 git log,别再到别的文档里找或加变更记录行。真要往那 5 篇的台账里加行,历史坑照旧:它们的表按日期升序 → 新行追加为末行,插表顶会把首行「初版」挤成第二行。
  • 历史行被当陈旧值改掉:「47 → 53 页」是当天事实,改了就是伪造历史;正确动作是只改当前态那几处、历史行一个字不动(保留变更记录的 5 篇真台账要写台账也只追加、不回改)。历史行被写坏时按无反引号兜底写法整行重写,别用同样写法再改一遍。
  • 照抄用户给的数:用户说「从 40 扩到 47」也要自己数 ref/*.bin;数出来不一定是 47。
  • 把节点行当叶子数:42 是 ui_menu_tree.txt 的节点行数、33 才是叶子;不读文件头规则就数错(实测把错数写进两份文档,下一轮才自查出来)。
  • 整文件正则批处理:第一次尝试的正则没编译过、整批零落地。改法 = 逐条字面替换 + 每处 assert count == expect。
  • 反引号截断:脚本里含 ui-golden、#page= 这类反引号时,经 TS 模板字符串/内嵌 heredoc 传递会被截断,表现为「整批零落地」或「历史行写坏」。落成脚本文件再执行,或用 chr(96) / String.fromCharCode(96) 拼。
  • 只改记得的那节:上一笔只改 §2 与开篇、漏改 §1,用户当场问出「§1 说 16 叶、§2 说剩 3 项,自相矛盾」。改完必须全文通读同一文档所有小节。
  • 误报跟着改:「< 40KB」是绘制缓冲红线,与页数无关。
  • 带日期戳的测量臆改新数:「2026-10-26 实跑 …覆盖 40 页」改成 47 就是把历史测量冒充现值;只加「当时」。
  • 用截断的 grep 输出判定:cut -c 截掉的后半句常含日期戳/口径,据此分类必错。
  • 新写文本别再造编号:两道编号门禁都已退役(全库八项校验 2026-10-28、只查新增行 2026-10-29,脚本与白名单在 scripts/archive/id_gate/),撞号不再有机器报警,只剩规范与评审——所以这批文本的形态自查要自己做(docs/文档规范.md §7.1;要机器帮忙就手工跑 scripts/archive/id_gate/check_ids_new.py --worktree)。