docs: known-issues / perf backlog — KI-1 DDP weak scaling at small global batch

Surfaced by v2 (world=4, global_batch=32): ~3593 tok/s, no speedup vs v1
single-GPU. Root cause + proposed fixes recorded; also consolidates deferred
T7 items (bf16, activation recompute) and the large-vocab modeling note.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/known-issues.md

@@ -0,0 +1,38 @@
+# xtrain — Known Issues & Perf Backlog
+
+已知问题（性能 / 正确性 / 建模）与延后项的活文档：记录现象、复现、根因、拟修复、优先级、状态。
+发现即记，修复即标 `FIXED`（附 commit）。
+
+---
+
+## Open
+
+### KI-1 · DDP 弱扩展性（small global batch）— `P1` · 由 v2 暴露
+- **现象**：4 卡 DDP 仅 ~3593 tok/s，几乎不快于 v1 单卡 ~3310 tok/s（≈1.08×，远低于近线性；T8 在 tiny 规模为 3.0×@4）。
+- **复现**：v2 训练 `dim384/12L, world=4, global_batch=32（每卡 8）, seq 256`。
+- **根因**：每个 step 对**全部参数梯度**做一次 NCCL all-reduce 是固定开销；`global_batch` 太小 → 每卡 compute 太少 → 通信/同步开销占比过高，吃掉扩展性。
+- **拟修复**：
+  1. 显著加大 `global_batch`（每卡 batch ↑：摊薄 all-reduce、喂饱 GPU）—— v3 先用此缓解；
+  2. 梯度 all-reduce **分桶 + 与 backward 重叠**（bucketed / overlapped all-reduce）；
+  3. 减少 per-step 同步点（与 KI-2/KI 性能项协同）。
+- **参考**：[docs/07-distributed.md](07-distributed.md)、[docs/06-performance.md](06-performance.md)。
+
+---
+
+## Deferred（来自 T7，放大后重启）
+
+### KI-2 · bf16 混合精度（fp32 master）— `deferred`
+- T7 延后理由：tiny 规模延迟瓶颈、bf16 改变数值会威胁 fp32 正确性闸门。
+- **重启条件**：模型放大（v2+ `dim≥384`）后 GEMM 渐成 compute-bound，tensor-core 收益显现。需 fp32 master weights + 单独 looser-tol 测试 + 收敛对比。
+
+### KI-3 · 激活重计算（gradient checkpointing）— `deferred`
+- T7 延后理由：单序列、显存不紧。
+- **重启条件**：更大模型 / 更长 seq / 更大 batch 后显存成约束。
+
+---
+
+## Modeling notes
+
+### KI-4 · 大词表 embedding 占比过高
+- gpt2 `vocab=50257` 在 dim 小时让 embed+lm_head 主导参数：v1 25.7M/34M、v2 38.6M/66.9M；core transformer 才是学习主体。
+- 后续可考虑更贴合 TinyStories 的小 vocab（会牺牲 xserv gpt2-tokenizer 复用）；或在更大 dim 下让 core 自然成为主体（继续 scaling 即可缓解占比）。