# [LEARN-20260501-001] doc-review 4-lens 在 AI 类模块上有盲区，需补 AI quality / 频控成本 / 可观测性 / i18n 深度 lens

## 触发场景

为新模块 `flow-diagram`（自然语言 → Mermaid 流程图，AI 生成类功能）跑 `doc-review`。第一轮 4-lens（实现走查 / 外部 API / 失败模式 / 字段 diff）+ Phase 0 项目侦察发现 6 🔴 + 9 🟡，全部修完。

按 doc-review skill 收敛规则应停审。但用户主动发起"用其他角度再扫一遍"，结果**用 4-lens 之外的 5 个 lens 又发现 1 🔴 + 5 🟡**，其中 🔴 是真阻塞性问题：

| 新发现 | 4-lens 为什么漏 |
|---|---|
| 🔴 system prompt 单语，en-US 用户输出语言混搭 | 4-lens 没有 i18n 深度 lens（只关注 UI 文案翻译，没问 LLM prompt 是否切语言） |
| 🟡 LLM 频控 / 防滥用缺失 | 4-lens 没有"成本 / 防 abuse" lens |
| 🟡 prompt 无 eval 黄金样本 | 4-lens 没有"AI 输出质量评估" lens |
| 🟡 metrics / 告警 / latency 观测缺失 | 4-lens 没有"可观测性" lens |
| 🟡 部门预设配色 key 没双语映射 | 同 i18n 深度盲区 |
| 🟢 a11y / 键盘导航 / 屏幕阅读器 | 4-lens 是工程实现侧 lens，没有用户多样性 lens |

## 根本原因

### 1. 4-lens 是为非 AI 模块设计的
`doc-review` skill 与其奠基 learning（`2026-04-30-doc-review-multi-lens.md`）都是从 `ops-center/m365-dormant`（传统 CRUD + 外部 API 同步）的踩坑提炼。当时没遇到 AI 类功能，4-lens 自然没考虑：
- prompt eval / 黄金样本回归
- LLM 调用频控 / token 成本
- system prompt 的 i18n 切换
- AI 输出质量的客观度量

把这套 lens 套用到 AI 类模块，会**系统性漏掉 AI 特有审查面**。

### 2. 4-lens 全是"工程实现侧"
4 个 lens（实现走查 / 外部 API / 失败模式 / 字段 diff）问的都是"代码怎么写、会不会挂、字段对不对"，**没有视角问**：
- 上线后怎么知道功能正常运行？（运维 / 可观测性）
- 怎么知道功能真的解决了用户问题？（产品 metric）
- 不同用户群体（盲人 / 老人 / 多语言）能用吗？（包容性）

这些维度对任何模块都重要，不只 AI 类。

### 3. 严重性判定边界模糊
🔴/🟡/🟢 在 skill 里只给了**例子**，没给**判定矩阵**。本次审 flow-diagram 把"权限点 seed 缺失"判 🔴，但严格说它只是 403，不是"数据丢失"。判定凭直觉，跨次审查会漂移。

## 正确做法

### 改进 1：给 doc-review 加条件触发的"AI 模块 lens"

模块如果依赖 LLM / 外部 AI 服务（命中关键词：LLM / OpenAI / Anthropic / langchain / prompt / ai-assistant / llm-service），必须额外跑：

| 检查点 | Prompt |
|---|---|
| Prompt eval | 是否有"输入 → 期望输出"的黄金样本 ≥ 5 组？改 prompt 后能跑回归吗？ |
| 频控 / 成本 | 是否定义 per-user / per-org / per-period rate limit？token 成本预估？ |
| i18n 深度 | system prompt 是否随 user locale 切换？预设词典（角色名 / 类别名）有双语映射？ |
| 输出质量度量 | 不只是"语法合法"。结构正确率、关键节点完整率、决策分支覆盖率怎么测？ |

### 改进 2：补"可观测性 lens"（与 4-lens 平级，全模块通用）

> "上线后怎么知道功能正常？挂了怎么定位？需要哪些 metric / log / 告警？"

逼出：调用量、失败率、p95 latency、关键业务漏斗（生成 → 保存比例）、PII 与隐私边界（什么能 log 什么不能）。

### 改进 3：Phase 0 项目侦察清单脚本化

现状：4-lens 文档列了"权限码格式 / schema 命名 / 状态库..."等检查项，**实际跑时是临场拼 grep**。

改成可执行 shell 脚本：每个检查项一行 grep，输出标准化结果，贴在审查报告开头。
- 漏项可见
- 命令统一，结果可对比
- 新项目接入只改 grep 模式

### 改进 4：严重性判定矩阵（二维替代单维）

| 暴露时机 \ 影响范围 | 单字段 | 单模块 | 跨模块 / 全系统 |
|---|---|---|---|
| 立即崩 / 编码即报错 | 🟡 | 🔴 | 🔴 |
| 集成测试发现 | 🟢 | 🟡 | 🔴 |
| 生产暴露（用户 / 数据 / 安全）| 🟡 | 🟡 | 🔴 |
| 长期债（性能 / 维护性） | 🟢 | 🟢 | 🟡 |

凭矩阵判，不凭直觉。

## 何时应用

任何使用 `doc-review` skill 的场景，特别是：
- AI 类功能（LLM 调用 / prompt / 输出质量都和传统 CRUD 不同）
- 长期运行的服务（必查可观测性）
- 多语言 / 多设备 / 多用户群体功能（必查 i18n 深度 + a11y）

## 关键洞察

1. **doc-review 的 4-lens 不是 universal**——它是从一次 CRUD + 外部同步类踩坑提炼，对 AI / 运维 / 包容性维度有系统盲区
2. **"4-lens 跑完 + 收敛建议停审"是局部最优**——在 lens 集合本身有漏洞时，stop 信号会让用户错失真问题
3. **meta-review（用其他视角审 review skill 自己）是有价值的**——本次新发现的 🔴 system prompt 单语，是 4-lens 永远发现不了的
4. **沉淀 lens > 多审一轮**——一次 meta-review 出几个新 lens，价值大于把现有 lens 多跑一遍

## 后续行动

1. ✅ 沉淀此 learning
2. ✅ 升级 `doc-review` SKILL.md：加 Lens E (AI quality)、Lens G (Observability)、严重性判定矩阵、Phase 0 脚本化建议
3. ⏳ 后续 AI 类模块（如 ai-assistant 自身、knowledge-base 的 RAG 部分）走 doc-review 时验证新 lens 的有效性
4. ⏳ 评估是否给 `plan-review` 也加 AI / Observability lens（plan-review 同样有此盲区）