# 逻辑对齐验证指南

确保优化后的 skill 不会丢失原有功能。

## 核心原则

**黄金法则**：优化只改表达，不改功能。

### 允许的优化

✅ **压缩冗余描述**
```markdown
# 优化前：这个 skill 用于处理 Excel 文件，包括读取、写入、编辑等操作
# 优化后：Excel 文件读写和编辑
```

✅ **脚本封装重复逻辑**
```markdown
# 优化前：详细列出 5 个手动步骤
# 优化后：运行 `scripts/process.py <input> <output>`
```

✅ **扁平化嵌套层级**
```markdown
# 优化前：多层嵌套标题
# 优化后：并列的二级标题
```

### 禁止的修改

❌ **删除功能入口** — 用户询问"如何旋转 PDF"时触发 → 必须保留

❌ **简化导致语义变化** — 原："仅当文件 >10MB 时压缩"，改："压缩文件" ← 改变了触发条件

❌ **移除关键约束** — 原："上传前必须验证 SHA1"，改："上传文件" ← 丢失必要步骤

## 验证流程

### 1. 功能清单对比

优化前列出所有功能点，优化后逐项核对是否保留。

### 2. 触发场景验证

列出所有应该触发该 skill 的用户输入，确保优化后的 `description` 仍能覆盖。

### 3. 工作流完整性检查

对关键工作流，验证所有步骤仍然存在（可以封装为脚本，但逻辑不能丢失）。

### 4. 边界条件保留

检查特殊情况处理是否保留（如文件大小限制、超时重试、错误处理）。

## 自动化验证

使用 `scripts/validate_logic.py` 自动检查：

```bash
python scripts/validate_logic.py \
  --original /path/to/original-skill \
  --optimized /path/to/optimized-skill
```

脚本会检查：description 覆盖度、功能关键词保留、文件引用完整性、scripts/ 调用对应性。

## 人工审核要点

自动化无法替代人工审核，重点检查：

- **语义微妙变化** — 原："仅当用户明确要求时压缩"，改："默认压缩" ← 语义反转
- **隐式依赖丢失** — 原："先验证权限，再执行"，改："执行操作" ← 丢失前置条件
- **上下文依赖变化** — 原："根据扩展名自动识别"，改："必须指定 --type" ← 增加用户负担

## 验证报告模板

```markdown
## 逻辑对齐验证报告

**验证日期**：YYYY-MM-DD

### 功能清单
- [x] 功能 A - 完全保留
- [~] 功能 B - 略有简化（不影响核心）
- [ ] 功能 C - **失败**（原因：...）

### 触发场景
- [x] 场景 1-3 - 通过

### 工作流完整性
- [x] 工作流 A-B - 步骤完整

### 风险评估
- **低风险**：XX 处
- **中风险**：XX 处（需人工复核）
- **高风险**：XX 处（建议回滚）

### 结论
✅ 验证通过 / ⚠️ 需调整 / ❌ 建议回滚
```

## 最佳实践

1. **优化前先验证** — 评审阶段就建立功能清单
2. **小步迭代** — 每次优化一个模块，立即验证
3. **保留备份** — 始终保留优化前的版本