/commit-with-reflection

name: commit-with-reflection
description: "Git提交与调试反思报告生成技能。用于分析开发过程中的错误、调试步骤和解决方案,生成结构化的中文反思报告,并创建包含报告引用的Git提交。显式请求词:反思提交、智能提交、生成调试报告、commit with reflection。"

Git提交与反思报告技能 (Commit with Reflection)

自动化Git提交并生成深度调试反思报告的技能。将AI编码过程中的错误、调试经验和解决方案转化为结构化的知识文档,保存在GitHub仓库中供长期参考和学习。

何时使用此技能 (When to Use)

在以下情况下使用此技能:

• 用户说:"反思提交"、"智能提交"、"生成调试报告"
• 用户说:"commit with reflection"、"reflective commit"
• 完成了包含多次调试迭代的功能开发
• 修复了复杂的bug并希望记录解决过程
• 重构代码时遇到并解决了架构问题
• 希望将本次开发经验转化为可复用的知识

**相关信号（用于人工判断或路由参考）**:

• 检测到会话中出现了错误消息
• 对同一文件进行了3次以上的修改迭代
• Git diff显示添加了调试相关代码(console.log, try-catch等)

不适用场景 (Not For)

此技能不适用于:

• 简单的文字修改或格式调整(无错误发生)
• 仅添加注释或文档的提交
• 初始化项目或添加依赖包
• 用户明确要求"简单提交"或"快速提交"

**必需输入**:

• 至少有一个修改过的文件(git status显示变更)
• 会话中包含开发过程的上下文(如果无错误,会询问是否仍要生成报告)

快速参考 (Quick Reference)

核心工作流

**阶段1: 上下文收集**

# 获取Git状态
git status

# 获取所有变更
git diff

# 分析会话历史提取:
# - 错误消息和堆栈跟踪
# - 调试步骤和迭代
# - 解决方案和修复

**阶段2: 生成反思报告**

1. 读取统一模板
   - 优先使用: project-root/docs/workflows/templates/unified-template.md
   - 回退使用: ~/.claude/skills/shared-templates/unified-workflow-report.md

2. 分析内容:
   - 错误分类(语法/类型/逻辑/架构/集成)
   - 严重程度评级(严重/重要/次要)
   - 根本原因分析
   - 预防策略制定
   - 经验提炼和模式识别

3. 填充模板
   - 报告类型设为: reflection
   - 重点填充: 错误分析、根本原因、经验总结章节

报告格式:
docs/workflows/YYYY-MM/DD_reflection_[type]_[desc].md

**阶段3: 创建Git提交**

# 创建报告目录
mkdir -p docs/workflows/$(date +%Y-%m)

# 生成并保存报告
echo "$REPORT" > docs/workflows/...

# 提交所有变更
git add .
git commit -m "type: description

遇到错误: N
调试迭代: N

详见反思报告: docs/workflows/...

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

**阶段4: 更新索引**

# 自动更新 docs/workflows/INDEX.md
# 包含:
# - 按日期/类型/错误类型分类
# - 统计信息
# - 搜索标签

报告模板结构

# 开发反思报告

**日期**: 2026-02-15 14:30:00
**提交类型**: feature | bugfix | refactor | docs
**会话时长**: 45 分钟
**修改文件数**: 5 个文件

## 1. 概述
简要描述本次修改的内容和目的

## 2. 修改内容
### 修改的文件
- `client/src/components/Feature.tsx` - 实现新功能
- `server/routers.ts` - 添加API端点

### 主要变更
- 添加了用户认证功能
- 修复了CORS跨域问题

## 3. 遇到的错误
### 错误 1: TypeScript类型错误
**严重程度**: 重要
**错误信息**: Property 'userId' does not exist on type 'User'
**上下文**: 在访问用户对象属性时
**解决方案**: 更新User接口定义,添加userId字段

## 4. 根本原因分析
### 为什么会出现这个错误?
- 直接原因: 接口定义不完整
- 深层原因: 数据库schema与TypeScript类型不同步
- 促成因素: 缺少类型检查的自动化流程

### 是什么导致编写时出现这个错误?
- 假设: 认为接口已经包含所有字段
- 知识盲区: 不了解数据库最新的schema变更
- 忽略的模式: 没有先检查现有类型定义

## 5. 调试过程
### 调查步骤
1. 检查TypeScript错误提示
2. 查看User接口定义
3. 对比数据库schema
4. 更新接口并验证

### 迭代过程
- 尝试 1: 直接添加类型断言 - 不可靠
- 尝试 2: 更新接口定义 - 成功

### 耗时统计
- 调查: 10 分钟
- 实现: 15 分钟
- 测试: 5 分钟

## 6. 经验总结
### 核心洞察
1. 类型定义应该与数据库schema保持同步
2. 类型断言只是临时方案,不能解决根本问题

### 预防策略
- 策略 1: 使用代码生成工具从schema自动生成类型
- 策略 2: 在修改schema后立即更新TypeScript类型

### 识别的最佳实践
- 实践 1: 先检查现有类型定义再编写代码
- 实践 2: 使用严格的TypeScript配置

## 7. 知识提炼
### 可复用模式
- 模式 1: Schema-first开发流程
- 模式 2: 类型安全的数据访问层

### 应避免的反模式
- 反模式 1: 使用any类型绕过类型检查
- 反模式 2: 类型断言掩盖真实问题

### 类似任务检查清单
- [ ] 检查数据库schema是否最新
- [ ] 验证TypeScript类型定义完整性
- [ ] 运行类型检查(tsc --noEmit)
- [ ] 测试所有数据访问路径

## 8. 测试与验证
### 测试用例
- 测试 1: 用户登录流程 - 通过
- 测试 2: 获取用户信息 - 通过

### 验证步骤
1. 运行TypeScript编译检查
2. 执行单元测试
3. 手动测试关键功能

## 9. 参考资料
- 相关提交: abc123, def456
- 文档: docs/api/user-authentication.md
- 外部资源: TypeScript官方文档

## 10. 指标
- 总错误数: 3
- 严重错误数: 1
- 调试迭代次数: 5
- 成功率: 80%
- 代码变动: +120 -45 行

---
**生成工具**: Claude Sonnet 4.5
**技能**: commit-with-reflection v1.0

错误检测逻辑

// 判断是否需要生成反思报告
function needsReflectionReport(context) {
  // 条件1: 发现错误消息
  const hasErrors = context.errors.length > 0;

  // 条件2: 多次迭代(>3次修改同一文件)
  const hasIterations = context.iterations > 3;

  // 条件3: 添加了调试代码
  const hasDebuggingCode = context.diff.includes('console.log') ||
                           context.diff.includes('try {') ||
                           context.diff.includes('catch (');

  // 条件4: 用户明确请求
  const userRequested = context.userMessage.includes('反思') ||
                        context.userMessage.includes('调试报告');

  return hasErrors || hasIterations || hasDebuggingCode || userRequested;
}

提交类型判断

// 根据变更内容判断提交类型
function determineCommitType(context) {
  const { files, diff, errors } = context;

  // 新增功能
  if (diff.includes('export function') || diff.includes('export const')) {
    return 'feature';
  }

  // 错误修复
  if (errors.length > 0 || diff.includes('fix:')) {
    return 'bugfix';
  }

  // 重构
  if (diff.includes('refactor:') || hasStructuralChanges(diff)) {
    return 'refactor';
  }

  // 文档
  if (files.every(f => f.endsWith('.md'))) {
    return 'docs';
  }

  return 'feature'; // 默认
}

示例 (Examples)

示例 1: 功能开发中的类型错误

**输入**:

• 用户: "反思提交"
• 会话包含: 3个TypeScript类型错误,5次迭代修复
• 修改文件: 4个.tsx文件, 1个.ts文件

**执行步骤**: 1. 运行`git status`和`git diff`收集变更 2. 从会话历史提取3个错误及其解决过程 3. 分析根本原因: 接口定义不完整 4. 生成报告: `docs/reflections/2026-02/15_feature_user-auth.md` 5. 创建提交并引用报告 6. 更新`docs/reflections/INDEX.md`

**预期输出**:

• 生成完整的中文反思报告(10个章节)
• Git提交包含报告引用
• 索引文件自动更新
• 用户收到确认消息: "已创建反思报告并提交代码"

示例 2: 简单修改(无错误)

**输入**:

• 用户: "提交代码"
• 会话无错误消息
• 修改文件: 1个README.md

**执行步骤**: 1. 检测到无错误发生 2. 询问用户: "未检测到错误,是否仍要生成反思报告?" 3. 用户选择"否" 4. 创建标准Git提交(无报告)

**预期输出**:

• 标准Git提交消息
• 不生成反思报告
• 不更新索引

示例 3: 复杂重构

**输入**:

• 用户: "生成调试报告并提交"
• 会话包含: 架构调整,2个集成问题,8次迭代
• 修改文件: 12个文件

**执行步骤**: 1. 收集所有变更和错误信息 2. 识别为重构类型(refactor) 3. 分析架构层面的根本原因 4. 提炼可复用的重构模式 5. 生成报告: `docs/reflections/2026-02/15_refactor_api-layer.md` 6. 创建提交并更新索引

**预期输出**:

• 包含架构洞察的反思报告
• 识别的重构模式和反模式
• 详细的预防策略检查清单

参考资料 (References)

本地文档

• `references/index.md` - 参考资料导航
• `references/error-taxonomy.md` - 错误分类体系
• `references/best-practices.md` - 反思报告最佳实践
• `references/report-schema.md` - 报告结构规范

模板文件

• `assets/template-chinese.md` - 中文报告完整模板
• `assets/template-feature.md` - 功能开发专用模板
• `assets/template-bugfix.md` - 错误修复专用模板
• `assets/template-refactor.md` - 重构专用模板

脚本工具

• `scripts/update-index.js` - 索引更新脚本
• `scripts/validate-report.js` - 报告格式验证
• `scripts/extract-errors.js` - 错误提取工具

示例报告

• `examples/feature-example.md` - 功能开发示例
• `examples/bugfix-example.md` - 错误修复示例
• `examples/refact