# 全局质量自检清单

DDS-to-Skill 转换完成后，必须按以下清单逐条检查。每条标记 PASS 或 FAIL，FAIL 必须附修复建议。

---

## 1. 结构完整性

| # | 检查项 | PASS 条件 |
|---|-------|----------|
| S1 | 系统级 Skill 存在 | 恰好 1 个 `developing-*-system` Skill |
| S2 | 模块级 Skills 数量 | = DDS 中识别的模块数 |
| S3 | 横切 Skills 数量 | ≥ 3 个 |
| S4 | 每个 Skill 有 SKILL.md | 所有 Skill 目录下存在 SKILL.md |
| S5 | 每个 Skill 有 reference/ | 所有 Skill 目录下存在 reference/ |
| S6 | 每个 Skill 有 verify.sh | 所有 Skill 的 scripts/ 下存在 verify.sh |
| S7 | 目录命名规范 | 全小写、连字符、动名词形式 |

---

## 2. Frontmatter 规范

| # | 检查项 | PASS 条件 |
|---|-------|----------|
| F1 | description 单行 | YAML 解析后 description 为单行字符串 |
| F2 | description 长度 | < 1024 字符 |
| F3 | description 中英文 | 同时包含中文和英文描述 |
| F4 | description 含触发场景 | 包含 "触发场景" 或 "Trigger" 关键词 |
| F5 | description 含关键词 | 包含 "关键词" 或 "Keywords" |
| F6 | name 格式 | 小写字母 + 数字 + 连字符，动名词开头 |
| F7 | argument-hint 存在 | frontmatter 中包含 argument-hint 字段 |
| F8 | allowed-tools 最小授权 | 只读 Skill 不包含 Write/Edit |

---

## 3. 内容质量

| # | 检查项 | PASS 条件 |
|---|-------|----------|
| C1 | SKILL.md 行数 | < 500 行 |
| C2 | 包含 Plan 章节 | grep 到 `## Plan` |
| C3 | 包含 Verify 章节 | grep 到 `## Verify` |
| C4 | 包含 Execute 章节 | grep 到 `## Execute` |
| C5 | 包含 Pitfalls 章节 | grep 到 `## Pitfalls` |
| C6 | 动态注入 | ≥ 2 处 `!` + 反引号命令 |
| C7 | Pitfalls 引用 reference | ≥ 2 条 Pitfall 中出现 `reference/` 路径 |
| C8 | 无空话 | 不含"检查 XX 一致性"这类无具体动作的描述 |
| C9 | 无常识内容 | 不含 Claude 已知的通用知识（如 HTTP 状态码定义） |
| C10 | 术语一致 | 同一概念在所有 Skill 中使用相同术语 |

---

## 4. Reference 质量

| # | 检查项 | PASS 条件 |
|---|-------|----------|
| R1 | 设计要素覆盖率 | 每个模块 Skill 覆盖 ≥ 3 类（API/事件/DB/状态机/权限/依赖） |
| R2 | 章节分层 | reference/ 下存在 `01-*` 等编号目录（或使用扁平+说明） |
| R3 | DDS 溯源 | 每条 reference 含 `DDS-Section:` 字段 |
| R4 | DDS 行号 | 每条 reference 含 `DDS-Lines:` 字段 |
| R5 | TBD 标注 | DDS 缺失内容标注 `[TBD]`，附最小补充清单 |
| R6 | 无脑补 | 所有设计细节可溯源到 DDS 原文 |
| R7 | 内容充分 | reference 包含足够的结构化数据（表格/列表/代码块） |

---

## 5. 跨 Skill 一致性

| # | 检查项 | PASS 条件 |
|---|-------|----------|
| X1 | 模块名一致 | 所有 Skill 中模块名拼写相同 |
| X2 | 错误码不冲突 | 相同错误码在不同 Skill 中含义相同 |
| X3 | API 路径不冲突 | 不同模块的 API 路径无重叠 |
| X4 | 事件/Topic 定义一致 | 同一 Topic 在发布方和订阅方 Skill 中定义相同 |
| X5 | 授权模型一致 | JWT Claims、角色定义在所有 Skill 中一致 |

---

## 6. 自检输出格式

```markdown
# 全局自检结果

## 结构完整性
- ✅ S1 PASS: 系统级 Skill `developing-xxx-system` 存在
- ✅ S2 PASS: 模块级 Skills 数量 = 5（匹配 DDS 中的 5 个模块）
- ❌ S3 FAIL: 横切 Skills 仅 2 个，少于要求的 3 个
  - **修复**: 从 DDS 中识别出缓存策略章节，建议增加 `managing-cache` Skill
- ✅ S4 PASS: 所有 Skill 目录下存在 SKILL.md

## Frontmatter 规范
- ✅ F1 PASS: 所有 description 为单行
- ❌ F2 FAIL: `developing-core` 的 description 超过 1024 字符（1156 字符）
  - **修复**: 精简触发场景描述，移除重复关键词

## 内容质量
- ✅ C1 PASS: 所有 SKILL.md < 500 行
- ❌ C8 FAIL: `developing-gateway` 中 Verify 包含"检查 API 一致性"
  - **修复**: 改为"对照 reference/02-api-design/apis.md 中的接口清单，grep 仓库中的 handler 注册点，确认路径和方法一致"

## 总计: XX PASS / YY FAIL
```

---

## 7. 常见 FAIL 及修复方案

| FAIL 类型 | 常见原因 | 修复方案 |
|----------|---------|---------|
| description 多行 | 使用了 `\|` 语法 | 改用 `>` 或单行字符串 |
| reference 不足 | DDS 内容被遗漏 | 重新扫描 DDS，补充缺失要素 |
| 空话 | 直接复制 DDS 原文 | 转化为可执行的审查动作 |
| 脑补 | DDS 未提及的细节 | 标注 [TBD] 并列出补充清单 |
| 横切不足 | 未充分分析 DDS | 从 DDS 中识别更多跨模块关注点 |
