commit-with-reflection

Git Commit and Reflection Report Skill (Commit with Reflection)

A skill that automates Git commits and generates in-depth debugging reflection reports. It transforms errors, debugging experience, and solutions from the AI coding process into structured knowledge documents, saved in the GitHub repository for long-term reference and learning.

When to Use This Skill (When to Use)

Use this skill in the following situations:

The user says: "reflection commit", "smart commit", "generate debugging report"
The user says: "commit with reflection", "reflective commit"
Completed feature development that included multiple debugging iterations
Fixed a complex bug and wants to record the resolution process
Encountered and resolved architectural issues while refactoring code
Wants to turn this development experience into reusable knowledge

Related signals (for human judgment or routing reference):

An error message was detected in the session
More than 3 modification iterations were made to the same file
Git diff shows debugging-related code was added (console.log, try-catch, etc.)

Not For (Not For)

This skill does not apply to:

Simple text changes or formatting adjustments (no errors occurred)
Commits that only add comments or documentation
Initializing a project or adding dependency packages
The user explicitly asks for a "simple commit" or "quick commit"

Required Inputs:

At least one modified file (git status shows changes)
The session contains context of the development process (if there are no errors, it will ask whether to still generate a report)

Quick Reference (Quick Reference)

Core Workflow

Phase 1: Context Collection

# 获取Git状态
git status

# 获取所有变更
git diff

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

Phase 2: Generate Reflection Report

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

Phase 3: Create Git Commit

# 创建报告目录
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>"

Phase 4: Update Index

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

Report Template Structure

# 开发反思报告

**日期**: 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

Error Detection Logic

// 判断是否需要生成反思报告
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;
}

Commit Type Determination

// 根据变更内容判断提交类型
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 (Examples)

Example 1: Type Errors in Feature Development

Input:

User: "reflection commit"
Session contains: 3 TypeScript type errors, 5 iterations to fix
Modified files: 4 .tsx files, 1 .ts file

Execution Steps:

Rungit statusandgit diffcollect changes
Extract the 3 errors and their resolution process from the session history
Analyze the root cause: incomplete interface definition
Generate report: docs/reflections/2026-02/15_feature_user-auth.md
Create a commit and reference the report
Updatedocs/reflections/INDEX.md

Expected Output:

Generate a complete Chinese reflection report (10 sections)
The Git commit includes a reference to the report
The index file is automatically updated
The user receives a confirmation message: "Reflection report created and code committed"

Example 2: Simple Modification (No Errors)

Input:

User: "commit code"
No error messages in the session
Modified file: 1 README.md

Execution Steps:

No error detected
Ask user: "No error detected, do you still want to generate a reflection report?"
User selects "No"
Create a standard Git commit (no report)

Expected Output:

Standard Git commit message
No reflection report generated
Index not updated

Example 3: Complex Refactoring

Input:

User: "Generate a debugging report and commit"
Session includes: architecture adjustment, 2 integration issues, 8 iterations
Files changed: 12 files

Execution Steps:

Collect all changes and error information
Identify as refactor type (refactor)
Analyze root causes at the architecture level
Extract reusable refactoring patterns
Generate report: docs/reflections/2026-02/15_refactor_api-layer.md
Create commit and update index

Expected Output:

Reflection report containing architectural insights
Identified refactoring patterns and anti-patterns
Detailed prevention strategy checklist

References

Local Documents

references/index.md - Reference navigation
references/error-taxonomy.md - Error classification system
references/best-practices.md - Reflection report best practices
references/report-schema.md - Report structure specification

Template Files

assets/template-chinese.md - Complete Chinese report template
assets/template-feature.md - Feature development dedicated template
assets/template-bugfix.md - Bug fix dedicated template
assets/template-refactor.md - Refactoring dedicated template

Script Tools

scripts/update-index.js - Index update script
scripts/validate-report.js - Report format validation
scripts/extract-errors.js - Error extraction tool

Example Reports

examples/feature-example.md - Feature development example
examples/bugfix-example.md - Bug fix example
examples/refactor-example.md - Refactoring example

Maintenance

Data Source: Based on project commit history analysis and reflection report best practices
Last Updated: 2026-02-15
Version: v2.0 (Unified Template Integration)
Known Limitations:
- Only supports Chinese report generation
- Requires a Git repository environment
- Depends on session history completeness
- Error detection is based on heuristic rules and may produce false positives

Unified Template Integration

Overview

Starting from v2.0, commit-with-reflection uses the same unified report template as autonomous-builder, ensuring that reports generated by the two skills have a consistent format.

Template Location

Priority order:

Project local template: docs/workflows/templates/unified-template.md
Global shared template: ~/.claude/skills/shared-templates/unified-workflow-report.md

Template Features

The unified template contains 12 sections:

Overview
User Requirements and Prompts
Workflow Record
Modified Content
Errors Encountered
Root Cause Analysis
Debugging Process
Lessons Learned
Knowledge Extraction
Testing and Verification
References
Metrics

Report Type Identifier

Report settings generated by commit-with-reflection:

{REPORT_TYPE}: "reflection"
File name format: DD_reflection_[type]_[desc].md

Differences from autonomous-builder

Feature	autonomous-builder	commit-with-reflection
Report Type	workflow	reflection
Trigger Timing	After each feature is completed	Manually triggered by the user
Key Sections	Workflow records, decision points	Error analysis, lessons learned
User Prompts	Automatically recorded	Extracted from the session
Workflow Steps	Detailed records	Simplified records

Configuration

In the project's.claude-workflows.yamlconfigure in:

skills:
  commit-with-reflection:
    unified_template: true
    output_dir: "docs/workflows"
    language: "zh-CN"

Detailed Workflow

Phase 1: Context Collection

1. 执行Git命令
   - git status: 获取修改文件列表
   - git diff: 获取具体变更内容
   - git log -1: 获取最近提交信息

2. 分析会话历史
   - 提取所有错误消息(Error:, TypeError:, etc.)
   - 识别调试步骤(尝试、修复、验证)
   - 统计迭代次数(同一文件的修改次数)
   - 计算会话时长

3. 构建上下文对象
   {
     files: ['file1.ts', 'file2.tsx'],
     diff: '完整的git diff输出',
     errors: [
       {
         message: '错误消息',
         type: '错误类型',
         context: '代码上下文',
         solution: '解决方案'
       }
     ],
     iterations: 5,
     duration: 45, // 分钟
     hasDebugging: true
   }

4. 判断是否需要报告
   if (needsReflectionReport(context)) {
     继续生成报告
   } else {
     询问用户是否仍要生成
   }

Phase 2: Report Generation

1. 错误分析
   for each error in context.errors:
     - 分类: 语法/类型/逻辑/架构/集成
     - 评级: 严重/重要/次要
     - 提取代码上下文
     - 识别解决方案
     - 分析根本原因

2. 经验提炼
   - 识别核心洞察(为什么会出错)
   - 制定预防策略(如何避免)
   - 提取可复用模式
   - 识别反模式
   - 生成检查清单

3. 填充模板
   - 使用 assets/template-chinese.md
   - 根据提交类型选择专用模板
   - 填充所有10个章节
   - 确保中文格式正确

4. 生成文件名
   格式: YYYY-MM/DD_[type]_[short-desc].md
   示例: 2026-02/15_feature_user-auth.md

Phase 3: Git Commit

1. 确保目录存在
   mkdir -p docs/reflections/$(date +%Y-%m)

2. 写入报告文件
   REPORT_PATH="docs/reflections/2026-02/15_feature_desc.md"
   echo "$REPORT_CONTENT" > "$REPORT_PATH"

3. 暂存所有变更
   git add .

4. 生成提交消息
   COMMIT_MSG="feature: 实现用户认证功能

添加了JWT token验证和用户登录API端点。

遇到错误: 3
调试迭代: 5

详见反思报告: docs/reflections/2026-02/15_feature_user-auth.md

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

5. 创建提交
   git commit -m "$COMMIT_MSG"

Phase 4: Index Update

1. 扫描所有报告
   reports = scanDirectory('docs/reflections/')

2. 提取元数据
   for each report:
     - 日期
     - 类型
     - 错误数量
     - 标签
     - 文件路径

3. 生成索引结构
   index = {
     lastUpdated: '2026-02-15 14:30:00',
     totalReports: 15,
     byType: {
       feature: 8,
       bugfix: 5,
       refactor: 2
     },
     byDate: [...],
     byErrorType: {...},
     byFile: {...},
     tags: ['PDF', 'React', 'TypeScript', ...]
   }

4. 渲染INDEX.md
   使用中文模板生成索引文件

5. 提交索引更新
   git add docs/reflections/INDEX.md
   git commit --amend --no-edit

Quality Assurance

Report Quality Check

The generated report must satisfy:

Completeness: Contains all 10 required sections
Accuracy: Error messages and solutions are accurate
Depth: Root cause analysis is insightful
Practicality: Prevention strategies are specific and actionable
Readability: Chinese expression is clear and fluent
Format: Markdown format is correct, code blocks are complete

Automated Verification

# 验证报告格式
node scripts/validate-report.js docs/reflections/2026-02/15_feature_desc.md

# 检查项:
# - 是否包含所有必需章节
# - 日期格式是否正确
# - 代码块是否闭合
# - 中文编码是否为UTF-8
# - 文件名是否符合规范

Manual Review

It is recommended to regularly review reflection reports:

Review all reports from this week weekly
Identify recurring error patterns
Update prevention strategies
Improve the checklist

Troubleshooting

Issue 1: No error detected but there is indeed an error

Cause: The error message format is non-standard or truncated

Solution:

Manually trigger: explicitly say "generate a debug report"
Check whether the session history is complete
Confirm that the error message contains keywords (Error, TypeError, etc.)

Issue 2: The report is generated but the content is empty

Cause: The session history does not contain enough debugging details

Solution:

Provide more context during debugging
Describe the solutions attempted
Explain why some solutions do not work

Issue 3: Git commit fails

Cause: The working directory is not a Git repository or there is a conflict

Solution:

# 检查Git状态
git status

# 解决冲突
git add .
git commit -m "..."

# 如果需要,手动创建报告

Issue 4: Chinese garbled text

Cause: The file encoding is not UTF-8

Solution:

# 检查文件编码
file -i docs/reflections/**/*.md

# 转换为UTF-8
iconv -f GBK -t UTF-8 file.md > file_utf8.md

Extensions and Customization

Add a new error type

Edit references/error-taxonomy.md:

### 新错误类型: 性能问题

**特征**:
- 响应时间过长
- 内存占用过高
- CPU使用率异常

**常见原因**:
- 未优化的数据库查询
- 内存泄漏
- 无限循环

**预防策略**:
- 使用性能分析工具
- 设置性能监控
- 编写性能测试

Custom report template

Create a new template assets/template-custom.md:

# 自定义反思报告

## 特定章节
...

## 其他章节
...

Reference in SKILL.md:

if (context.customType) {
  template = 'assets/template-custom.md';
}

Integrate CI/CD

In .github/workflows/reflection.yml:

name: Validate Reflection Reports

on: [push]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Validate reports
        run: |
          node scripts/validate-report.js docs/reflections/**/*.md

Best Practices

Record promptly: Record key steps during debugging; do not recall them afterward
Analyze deeply: Do not be satisfied with surface causes; dig into deeper root causes
Specific Strategies: Prevention strategies must be specific and actionable, not vague generalities
Regular Review: Review reflection reports weekly to identify patterns and trends
Continuous Improvement: Update development processes and checklists based on reflection reports
Knowledge Sharing: Share valuable reflection reports with team members
Pattern Library Building: Accumulate a library of common error patterns and solutions

Plugin Intelligent Discovery and Automatic Use (ToolSearch Auto-Discovery)

Core Principles

When executing tasks, commit-with-reflectionmust proactively use ToolSearch to discover and invoke available MCP plugin tools, so as to enhance the depth and accuracy of reflection reports.

Automatic Discovery at Startup

ON SKILL ACTIVATION:

1. 使用 ToolSearch 探测可用插件:
   - ToolSearch("getDiagnostics") → 发现 IDE 诊断工具
   - ToolSearch("+serena symbol") → 发现代码符号分析工具
   - ToolSearch("+github") → 发现 GitHub 操作工具
   - ToolSearch("context7") → 发现文档查询工具

2. 将发现的工具记录到工作上下文中，后续步骤直接调用

Plugin Usage at Each Stage

Stage 1: Context Collection - Enhanced Version

原有流程:
  git status → git diff → 分析会话历史

增强流程 (使用 ToolSearch):
  1. ToolSearch("getDiagnostics")
     → 获取 IDE 诊断信息（类型错误、lint 警告等）
     → 补充到错误列表中，比纯文本分析更精确

  2. ToolSearch("+serena get_symbols_overview")
     → 分析修改文件的符号结构
     → 理解代码变更的架构影响

  3. ToolSearch("+serena find_referencing_symbols")
     → 查找被修改符号的所有引用
     → 评估变更的影响范围

Stage 2: Report Generation - Enhanced Version

原有流程:
  分析错误 → 提炼经验 → 填充模板

增强流程 (使用 ToolSearch):
  1. IF 涉及第三方库问题:
     → ToolSearch("context7")
     → 查询库文档，补充正确用法到报告中

  2. IF 需要代码结构分析:
     → ToolSearch("+serena find_symbol")
     → 获取精确的符号定义和关系图

  3. IF 需要截图记录:
     → ToolSearch("+playwright screenshot")
     → 截取应用状态作为报告附件

Stage 3: Git Commit - Enhanced Version

原有流程:
  git add → git commit

增强流程 (使用 ToolSearch):
  1. IF 需要创建 GitHub Issue 追踪:
     → ToolSearch("+github create_issue")
     → 为重要的 Bug 修复创建追踪 Issue

  2. IF 需要推送到远程:
     → ToolSearch("+github push_files")
     → 通过 MCP 直接推送，无需本地 git push

Task-Plugin Intelligent Mapping

Reflection Report Stage	ToolSearch Query	Purpose
Error Analysis	`ToolSearch("getDiagnostics")`	Obtain precise IDE diagnostic information
Code Structure Analysis	`ToolSearch("+serena symbol")`	Analyze modified code symbols and reference relationships
Library Documentation Query	`ToolSearch("context7")`	Query the correct usage of third-party libraries
GitHub Issue	`ToolSearch("+github issue")`	Create a Bug Tracking Issue
Application Screenshot	`ToolSearch("+playwright screenshot")`	Capture the application state as a report attachment
Code Execution Verification	`ToolSearch("executeCode")`	Execute code snippets to verify the fix effect

Notes

Tools returned by ToolSearchare immediately available, no need to select again
After keyword searching for already loaded tools,do notrepeatedly use select: to load
Prefer using MCP tools over Bash commands
If ToolSearch does not find relevant tools, fall back to the original method
Plugin enhancement isoptional, and the core process does not depend on plugin availability

Version History (Version History)

v1.0 (2026-02-15)

Initial Version
Support Chinese report generation
Automatic error detection
Git commit integration
Automatic index update
Support four types: feature/bugfix/refactor/docs

v2.0 (2026-02-15)

Unified Template Integration
Share report format with autonomous-builder

v3.0 (2026-02-16)

Added ToolSearch plugin intelligent discovery
Automatically use MCP plugins to enhance report quality

About this skill

When to Use This Skill (When to Use)

Not For (Not For)

Quick Reference (Quick Reference)

Core Workflow

Report Template Structure

Error Detection Logic

Commit Type Determination

Examples (Examples)

Example 1: Type Errors in Feature Development

Example 2: Simple Modification (No Errors)

Example 3: Complex Refactoring

References

Local Documents

Template Files

Script Tools

Example Reports

Maintenance

Unified Template Integration

Overview

Template Location

Template Features

Report Type Identifier

Differences from autonomous-builder

Configuration

Detailed Workflow

Phase 1: Context Collection

Phase 2: Report Generation

Phase 3: Git Commit

Phase 4: Index Update

Quality Assurance

Report Quality Check

Automated Verification

Manual Review

Troubleshooting

Issue 1: No error detected but there is indeed an error

Issue 2: The report is generated but the content is empty

Issue 3: Git commit fails

Issue 4: Chinese garbled text

Extensions and Customization

Add a new error type

Custom report template

Integrate CI/CD

Best Practices

Plugin Intelligent Discovery and Automatic Use (ToolSearch Auto-Discovery)

Core Principles

Automatic Discovery at Startup

Plugin Usage at Each Stage

Task-Plugin Intelligent Mapping

Notes

Version History (Version History)

v1.0 (2026-02-15)

v2.0 (2026-02-15)

v3.0 (2026-02-16)