feat: gate writer sections on a % teach: block (SP025)

Rewrite references/pedagogy.md around recite-vs-teach: reader model, coverage density (sections_in is cite permission, not a to-do list), intuition-before-formula three-beat, and paper-jump filling. Every notes/sections/sec-*.tex must now answer gap / takeaway / jump / omit above the first \section. lint.py checks presence only (it cannot judge honesty); files opening with "% generated by" are exempt. - scripts/lint.py: SP025 + is_writer_section / teach_gaps helpers - tests/no-teach-block/: fixture with takeaway only, wired into test.sh - examples/*: all 14 writer sections get real teach blocks - SKILL.md, references/{agents,antipatterns,checklist}.md, DESIGN.md, assets/notes-template.tex: route writers and consistency agent through pedagogy.md
2026-09-17 10:06:54 +08:00
parent 49842c5153
commit 5170111823
26 changed files with 373 additions and 16 deletions
@@ -1,2 +1,7 @@
+% teach:
+% gap: 见过 $1/\sqrt{d_k}$，但不知道它是装饰性常数还是一次必须看见的改写
+% takeaway: 这一节要判断的是「这步改写值不值得画出来」
+% jump: none
+% omit: 摘录之外的全文结构
 \section{这篇论文在问什么}
 注意力里的 $1/\sqrt{d_k}$ 是装饰，还是一次必须看见的改写？
@@ -1,3 +1,8 @@
+% teach:
+% gap: 知道要除 $\sqrt{d_k}$，但看不见方差是从哪一步冒出来的
+% takeaway: 缩放来自点积方差随 $d_k$ 增长，是改写不是新算子
+% jump: fixture 直接给出结论，没展开方差那一步
+% omit: 其他归一化方案的对比
 \section{主张与贡献}
 \splabel{C1}
 点积方差随 $d_k$ 涨。除掉 $\sqrt{d_k}$ 是改写，不是新算子。
@@ -1,2 +1,7 @@
+% teach:
+% gap: 不知道什么时候该出 superderive 图、什么时候 align 就够
+% takeaway: $\le 4$ 步且没有消项或代入要看见时，留在 align
+% jump: none
+% omit: superderive 的完整语法（见子仓库 SKILL.md）
 \section{总结与延伸}
 四步以内、没有消项或代入要画出来时，仍然用 \texttt{align}。
@@ -1,3 +1,8 @@
+% teach:
+% gap: 知道模型要输出预测，但没想过损失算不算前向路径上的一站
+% takeaway: 这份摘录只问一件事——前向到哪里为止
+% jump: none
+% omit: 摘录之外的全文结构与实验
 \section{这篇论文在问什么}
 要把输入变成预测，最简单的机制是什么？损失要不要走在前向主路上？
 这是摘录 fixture，不假装读完全文。
@@ -1,3 +1,8 @@
+% teach:
+% gap: 还没有一句能离开 PDF 复述的核心主张
+% takeaway: 一次前向是 $x\to f_\theta\to\hat y$；损失在预测之后单独比较
+% jump: none
+% omit: 重复摘要的贡献条目
 \section{主张与贡献}
 \splabel{C1}
 一次前向是 $x \to f_\theta \to \hat y$。损失 $L(\hat y,y)$ 在预测之后单独计算，不是主路上的一站。
@@ -1,2 +1,7 @@
+% teach:
+% gap: 不知道 $f_\theta$、$\hat y$ 在本讲义里各指什么
+% takeaway: 预测器就是 $\hat y=f_\theta(x)$，其余符号查附录，不在正文重列
+% jump: none
+% omit: 论文式的记号巡游
 \section{预备：定义、假设、符号}
 预测器定义为 $\hat y = f_\theta(x)$。符号见附录。
@@ -1,3 +1,8 @@
+% teach:
+% gap: 会算内积，但不知道维数一涨为什么会把后面的非线性弄坏
+% takeaway: 除 $\sqrt{d}$ 是把方差按回 1 的改写，不是新算子
+% jump: 摘录直接写下 $1/\sqrt{d}$，没说维数涨会让点积方差跟着涨
+% omit: 数据集、超参、硬件
 \section{一次前向与损失}
 内积的方差会随维数 $d$ 涨。为了不让后续非线性饱和，要把点积除掉 $\sqrt{d}$。

@@ -1,2 +1,7 @@
+% teach:
+% gap: 学完这一条机制，不知道同样的流程怎么套到一篇完整论文
+% takeaway: 先用 ledger 钉住 claim，再按路由决定出不出图
+% jump: none
+% omit: 摘录没覆盖的实验与消融
 \section{总结与延伸}
 摘录只保留一条机制：一次前向加侧路损失。更长的论文用 ledger 把 claim 钉住，再按路由出图。
@@ -1,2 +1,7 @@
+% teach:
+% gap: 知道有前向和损失两件事，但不知道它们在图上谁接谁
+% takeaway: 这一节问的是数据流拓扑，不是张量轴长
+% jump: none
+% omit: 摘录之外的全文结构
 \section{这篇论文在问什么}
 预测怎么从输入算出来，损失该不该站在前向主路上？
@@ -1,3 +1,8 @@
+% teach:
+% gap: 容易把损失画成前向链条上的下一个方块
+% takeaway: 损失是侧路，不是主路上的一站
+% jump: fixture 的框图没说清 $L$ 是挂在 $\hat y$ 之后还是在链条之内
+% omit: 重复摘要的贡献条目
 \section{主张与贡献}
 \splabel{C1}
 一次前向是 $x\to f_\theta\to\hat y$。损失在预测之后单独比较。
@@ -1,2 +1,7 @@
+% teach:
+% gap: 不知道这类图为什么交给 superfig 而不是 supertensor
+% takeaway: 主张是「谁吃谁」时走 superfig
+% jump: none
+% omit: 轴长与形状细节（那是 supertensor 的活）
 \section{总结与延伸}
 这张图走 superfig，因为要画的是谁吃谁，不是轴长。
@@ -1,2 +1,7 @@
+% teach:
+% gap: 会写 $QK^\top$，但没想过收缩沿哪条边、$K^\top$ 要不要真的换面
+% takeaway: 这一节问的是形状对齐，不是模块拓扑
+% jump: none
+% omit: 摘录之外的全文结构
 \section{这篇论文在问什么}
 每头的 $Q$ 和 $K$ 沿哪一条边收缩，$K^\top$ 要不要真的换面？
@@ -1,3 +1,8 @@
+% teach:
+% gap: 把 $K^\top$ 当成记号上的装饰，不当成一次真实的换面
+% takeaway: 打分沿 $d_h$ 收缩，收缩边必须等长
+% jump: fixture 只写 $QK^\top$，没说明转置是物理换面而非书写约定
+% omit: 多头拼接与输出投影
 \section{主张与贡献}
 \splabel{C1}
 打分是 $(T\times d_h)(d_h\times T)\to(T\times T)$。$K^\top$ 必须物理换面，收缩边等长。
@@ -1,2 +1,7 @@
+% teach:
+% gap: 不知道形状类的图该交给哪个子仓库
+% takeaway: 主张是轴长与收缩边时走 supertensor
+% jump: none
+% omit: 模块拓扑（那是 superfig 的活）
 \section{总结与延伸}
 形状对齐的公式图只交给 supertensor。