Skill: amoshc/ai-retrospective-skill (version 1.0.0)

--- name: ai-retrospective version: 1.0.0 description: > AI Collaboration Retrospective — a tool-agnostic post-session analysis framework. After each AI-assisted coding/development session, it systematically reviews the entire conversation across eight dimensions to identify improvement opportunities and generate a structured retrospective report. Core goal: make every AI session better than the last. triggers: - "复盘" - "回顾一下" - "retrospective" - "retro" - "review this session" license: MIT-0 compatibility: - Any AI coding assistant with conversation context access and file I/O - Tested with: WorkBuddy, Cursor, Claude Code, GitHub Copilot Chat, Windsurf, Cline --- # AI Collaboration Retrospective Post-session systematic review tool. Eight-dimension deep analysis drives a continuous improvement loop for AI-assisted development. ## Core Principles - **Conversation context is the data source**: The complete conversation history of the current session is already in context — no external data fetching needed - **Progressive loading**: Detailed evaluation criteria live in `references/analysis_dimensions.md` — load on demand - **Self-reflection first**: Examine the AI's own shortcomings before analyzing user-side improvements. This is NOT about criticizing the user — it's about finding efficiency gains in the "AI + Human" collaboration - **Quantify everything**: Every finding must reference specific conversation turns, wasted operations, and include counterfactual reasoning ("If X had been done, Y turns could have been saved") - **Dig deep**: Don't settle for "no findings." Complete the self-check list for each dimension before declaring it clean ## Execution Model This skill is **pure LLM instruction-driven** — no scripts, no external dependencies. It works on any AI assistant that can: 1. Access the current conversation history 2. Read reference files from this skill's directory 3. Write output files to the workspace **Capability adaptation**: The workflow below references file operations and memory updates. If your AI tool doesn't support a specific capability, skip that step and note it in the report. The analysis itself only requires conversation context access. ## Workflow (Six Steps) ### Step 1: Conversation Review — Extract Key Events + Tag Waste Points Scan the entire conversation context and extract these key events into a timeline: | Event Type | Recognition Signal | |-----------|-------------------| | Tool invocations | Command execution, file reading/writing, web searches, code generation | | File changes | Files created, modified, or deleted | | Errors & fixes | Error messages, lint failures, debugging cycles | | Repeated modifications | Same file/feature modified multiple times, user providing multiple clarifications | | Decision points | Technology choices, architecture decisions, trade-offs | | Automation/plugin usage | Any skill, agent, plugin, or extension triggered during the session | | User clarifications | User adding context because the AI misunderstood intent | | **Verification rounds** | User providing test data/feedback, AI analyzing verification results | | **AI misjudgments** | AI providing wrong conclusions, missing critical issues, or jumping to premature conclusions | **Filter rule**: System initialization events (bootstrap files, identity setup, etc.) are excluded from analysis. **Critical step — Waste point tagging**: After building the timeline, interrogate each event in reverse: 1. **Could this step have been avoided?** If something had been done earlier, would this step be unnecessary? 2. **Could this step have happened sooner?** Did the AI delay something it should have proactively done? 3. **Did this step duplicate prior work?** Was the AI hand-writing logic that could have been reused? Tag events where the answer is "yes" with `[⚠ Optimizable]` and record the reason. These tags are the core input for Step 2. Output format: Chronological event list with type labels and brief descriptions. Waste points tagged separately. ### Step 2: Eight-Dimension Deep Analysis Load `references/analysis_dimensions.md` for detailed evaluation criteria, self-check lists, and common patterns per dimension. Analyze conversation events dimension by dimension to identify improvement opportunities. **Eight dimensions overview:** 1. **AI Self-Reflection** ⭐ — AI's mistakes, delayed reactions, missed judgments in this session (highest priority, must be analyzed first) 2. **Verification Strategy** — Did the AI proactively define verification criteria and expected outcomes, or passively wait for user feedback? 3. **Automation Opportunities** — Repetitive workflows or hand-written scripts that could be encapsulated into reusable automations 4. **Existing Automation Tuning** — Were any existing automations/skills/templates used? Did they have gaps, unclear instructions, or output issues? 5. **Tool Integration Opportunities** — Operations that would benefit from dedicated tool integrations, plugins, or API connections 6. **Knowledge Persistence** — Preferences, conventions, and technical decisions from this session that should be persisted for future sessions 7. **Documentation Updates** — Project docs, coding standards, or architecture notes that need updating 8. **Workflow Efficiency** — Sequential steps that could be parallel, repeated labor, suboptimal tool choices **Analysis requirements (mandatory):** For each dimension: - Run through the dimension's self-check list (defined in `references/analysis_dimensions.md`) - For findings, output: **Specific event reference** (which turn, what operation) + **Counterfactual reasoning** (if X had been done, Y could be saved) + **Recommendation** + **Priority** - Only after all self-check items pass can a dimension be declared "no findings" and skipped ### Step 3: Generate Retrospective Report Load `assets/report_template.md` for the report template. Fill the template with results from Step 1 and Step 2 to produce a complete Markdown retrospective report. **Report save path**: `{workspace}/retrospectives/{topic}_retrospective.md` Naming rules: - `{topic}` uses 2-4 English words joined by hyphens, summarizing the session's core task (e.g., `multithread-scope-collection`, `login-flow-refactor`) - **Multiple retrospectives on same topic**: If the file already exists, append the new report at the end (separated by `---` and a new date heading) — don't create a new file If the `retrospectives/` directory doesn't exist, create it first. > **Note**: The save path above is a sensible default. Adapt to your project's conventions if they differ. ### Step 4: Display Full Analysis in Conversation **The complete analysis must be shown directly in the conversation** — don't just output a summary and point to the file. The file is an archive; the primary reading experience is in the conversation. Output content (show in full, no trimming): 1. **Session summary**: One-sentence overview 2. **Efficiency score**: Optimizable turns / total turns 3. **Event timeline**: Complete table with waste point tags 4. **All dimension findings**: Each with event reference, problem, counterfactual reasoning, recommendation (this is the core content — **never abbreviate or reduce**) 5. **Pending action list** (if any) 6. **Report archive location** Format: Use Markdown tables and headings for clear structure. Better to be thorough than to cut valuable analysis. ### Step 5: Automatic Execution — Knowledge Persistence For items identified in the "Knowledge Persistence" dimension (Dimension 6), execute persistence operations available in your AI tool: - If your tool supports persistent memory (e.g., memory APIs, memory files, `.memory` directories), write new preferences/conventions directly - If your tool supports project-level notes or config, update those - If your tool has no persistence mechanism, list the items that *should* be persisted and recommend the user save them manually Briefly state what was updated after each operation. Skip this step if no knowledge needs persisting. ### Step 6: Pending Action List For the following types of improvement suggestions, **do not auto-execute** — list them for user selection: | Action Type | Examples | |------------|---------| | Create new automation | Reusable workflow, script template, custom command | | Tune existing automation | Modify instructions, parameters, or trigger conditions | | Create/update project rules | Coding standards, review checklists, conventions | | Update project documentation | Architecture docs, API references, onboarding guides | | Create tool integration | Custom plugin, API connection, webhook | List format: Numbered list, each item includes "Action type + Specific content + Expected benefit." User can reply with numbers to select which actions to execute. If no pending actions, skip this step and state "No additional actions needed for this session." ## Edge Cases **Very short sessions**: If the conversation is only a few turns with simple content, output a brief summary and state "This session was brief — no significant improvement opportunities identified." Don't force analysis. **Compressed/summarized history**: If the conversation history appears compressed or truncated, analyze based on available context and note in the report: "Some conversation history was compressed; analysis is based on visible context." **Tool capability limitations**: If the AI tool being used lacks certain capabilities referenced in this workflow (e.g., no file writing, no memory persistence), adapt gracefully — perform the analysis steps that are possible and clearly note any skipped steps with the reason.

path: README.md
content: [中文版](README.zh-CN.md) | **English**

# AI Retrospective Skill

A tool-agnostic post-session analysis framework for AI-assisted coding. Works with any AI coding assistant that has conversation context access.

After each AI-assisted development session, trigger a systematic review across **eight dimensions** to identify improvement opportunities and generate a structured retrospective report.

**Core goal: Make every AI coding session better than the last.**

## Why This Exists

Most developers use AI assistants reactively — they code, hit problems, move on. They rarely stop to ask: *"Could this session have gone better? What patterns keep wasting our time?"*

This skill turns that reflection into a structured, repeatable process. It analyzes the conversation between you and your AI assistant, finds concrete waste points, quantifies the impact, and produces actionable recommendations.

## The Eight Dimensions

| # | Dimension | What It Examines |
|---|-----------|-----------------|
| 1 | **AI Self-Reflection** | AI's mistakes, delayed reactions, missed judgments (analyzed first — highest priority) |
| 2 | **Verification Strategy** | Whether AI proactively defined verification criteria or passively waited for feedback |
| 3 | **Automation Opportunities** | Repetitive workflows that could be encapsulated into reusable automations |
| 4 | **Existing Automation Tuning** | Gaps in automations/skills/rules that were active during the session |
| 5 | **Tool Integration Opportunities** | Operations that need dedicated tools, plugins, or API connections |
| 6 | **Knowledge Persistence** | Preferences, conventions, and decisions worth persisting for future sessions |
| 7 | **Documentation Updates** | Project docs, standards, or architecture notes needing updates |
| 8 | **Workflow Efficiency** | Sequential steps that could be parallel, repeated labor, suboptimal tool choices |

## Supported AI Tools

This skill is designed to work with any AI coding assistant. It has been tested with:

| Tool | How to Install |
|------|---------------|
| **WorkBuddy** | Copy to `.workbuddy/skills/ai-retrospective/` |
| **Cursor** | Copy SKILL.md content to `.cursor/rules/` or reference in project instructions |
| **Claude Code** | Append to `CLAUDE.md` or use as a slash command reference |
| **GitHub Copilot** | Reference in `.github/copilot-instructions.md` |
| **Windsurf** | Reference in `.windsurfrules` or Cascade workflow |
| **Cline** | Reference in `.clinerules` or custom instructions |

The skill degrades gracefully — if your tool lacks certain capabilities (e.g., no file writing, no memory persistence), the analysis steps still work; only the output/persistence steps adapt.

## Quick Start

### 1. Install

```bash
# Clone into your project (or globally)
git clone https://github.com/AmosHC/ai-retrospective-skill.git

# Or just copy the files
cp -r ai-retrospective-skill/ your-project/.ai-retrospective/
```

### 2. Trigger

At the end of any AI-assisted coding session, say one of:
- "retrospective" / "retro"
- "review this session"

### 3. Get Your Report

The skill will:
1. Scan your conversation history and build an event timeline
2. Tag waste points (avoidable steps, delayed actions, duplicated work)
3. Analyze across all eight dimensions with specific event references
4. Generate a full report in the conversation AND save to file
5. Auto-persist knowledge items (if your tool supports it)
6. List pending actions for your confirmation

## Directory Structure

```
ai-retrospective-skill/
├── SKILL.md                              # Core skill definition and workflow
├── references/
│   └── analysis_dimensions.md            # Detailed criteria for all 8 dimensions
├── assets/
│   └── report_template.md                # Markdown template for reports
├── README.md                             # English documentation
├── README.zh-CN.md                       # Chinese documentation
└── LICENSE                               # MIT License
```

## How It Works

The skill is **pure LLM instruction-driven** — no scripts, no external dependencies, no API keys. It works entirely through structured prompts that guide the AI assistant through the analysis workflow.

The key insight: your AI assistant already has the complete conversation history in context. This skill simply provides a systematic framework for the AI to analyze that history and extract actionable insights.

### Workflow Overview

```
Session ends → Trigger word → Step 1: Extract events & tag waste
→ Step 2: Eight-dimension analysis → Step 3: Generate report file
→ Step 4: Display full analysis in chat → Step 5: Auto-persist knowledge
→ Step 6: List pending actions for confirmation
```

## Adaptation Guide

### For tool-specific installation

Each AI tool has its own convention for custom instructions. The core content lives in `SKILL.md` and `references/analysis_dimensions.md`. Adapt the packaging:

- **WorkBuddy**: Use as-is — the directory structure matches the Skills format
- **Cursor**: Create a `.cursor/rules/retrospective.md` combining SKILL.md + key parts of analysis_dimensions.md
- **Claude Code**: Append a "Retrospective" section to your `CLAUDE.md` with the workflow and dimension summaries
- **Other tools**: Wherever your tool reads custom instructions, include the SKILL.md content

### Customizing dimensions

The eight dimensions are designed to be comprehensive but not exhaustive. You can:
- Add domain-specific dimensions (e.g., "Security Review" for security-critical projects)
- Adjust priority weights for dimensions most relevant to your workflow
- Add new patterns to the self-check lists based on your experience

### Customizing the report

Edit `assets/report_template.md` to match your team's conventions. The template uses placeholder variables that the AI fills during report generation.

## Contributing

Issues and PRs are welcome. Some areas where contributions would be especially valuable:

- **New dimensions**: Domain-specific analysis dimensions with self-check lists
- **Pattern libraries**: Common waste patterns for specific languages/frameworks
- **Tool adapters**: Pre-built configurations for additional AI tools
- **Translations**: Localized versions of the analysis dimensions

## License

MIT — see [LICENSE](LICENSE) for details.


path: README.zh-CN.md
content: **中文** | [English](README.md)

# AI 协作复盘 Skill

一个工具无关的 AI 辅助编程会话复盘框架。适用于任何能访问对话上下文的 AI 编程助手。

每次 AI 辅助开发结束后，触发一次系统化的 **八维度** 复盘分析，识别改进机会，生成结构化复盘报告。

**核心目标：让每一次 AI 协作都比上一次更高效。**

## 为什么需要这个

大多数开发者用 AI 的方式是被动的 —— 写代码、遇到问题、继续推进。很少有人停下来想一想：*"这次协作本可以更好吗？哪些模式一直在浪费我们的时间？"*

这个 Skill 把这种反思变成一个结构化、可重复的流程。它分析你和 AI 助手之间的对话，找到具体的浪费点，量化影响，给出可执行的改进建议。

## 八个分析维度

| # | 维度 | 分析内容 |
|---|------|---------|
| 1 | **AI 自我反思** | AI 的失误、延迟反应、遗漏判断（最高优先级，首先分析） |
| 2 | **验证策略** | AI 是否主动定义了验证标准，还是被动等待反馈 |
| 3 | **自动化机会** | 重复性工作流，可以封装成可复用的自动化 |
| 4 | **现有自动化调优** | 会话中使用的自动化/Skill/规则存在的缺口 |
| 5 | **工具集成机会** | 需要专用工具、插件或 API 连接的操作 |
| 6 | **知识沉淀** | 值得持久化的偏好、约定和决策，供未来会话使用 |
| 7 | **文档更新** | 需要更新的项目文档、规范或架构笔记 |
| 8 | **工作流效率** | 可以并行的串行步骤、重复劳动、次优工具选择 |

## 支持的 AI 工具

本 Skill 设计为工具无关，适用于任何 AI 编程助手。已测试的工具：

| 工具 | 安装方式 |
|------|---------|
| **WorkBuddy** | 复制到 `.workbuddy/skills/ai-retrospective/` |
| **Cursor** | 将 SKILL.md 内容复制到 `.cursor/rules/` 或在项目设置中引用 |
| **Claude Code** | 追加到 `CLAUDE.md` 或作为 slash command 引用 |
| **GitHub Copilot** | 在 `.github/copilot-instructions.md` 中引用 |
| **Windsurf** | 在 `.windsurfrules` 或 Cascade 工作流中引用 |
| **Cline** | 在 `.clinerules` 或自定义指令中引用 |

Skill 支持优雅降级 —— 如果你的工具缺少某些能力（比如不能写文件、不能持久化记忆），分析步骤照常工作，只有输出/持久化步骤会自适应调整。

## 快速开始

### 1. 安装

```bash
# 克隆到你的项目（或全局使用）
git clone https://github.com/AmosHC/ai-retrospective-skill.git

# 或者直接复制文件
cp -r ai-retrospective-skill/ your-project/.ai-retrospective/
```

### 2. 触发

在任何 AI 辅助编程会话结束时，说：
- "复盘" / "回顾一下"
- "retrospective" / "retro"
- "review this session"

### 3. 获取报告

Skill 会：
1. 扫描对话历史，构建事件时间线
2. 标记浪费点（可避免的步骤、延迟操作、重复工作）
3. 按八个维度进行分析，关联具体事件
4. 在对话中输出完整报告，同时保存到文件
5. 自动沉淀知识条目（如果工具支持）
6. 列出待确认的行动项

## 目录结构

```
ai-retrospective-skill/
├── SKILL.md                              # 核心 Skill 定义和工作流
├── references/
│   └── analysis_dimensions.md            # 八维度详细分析标准
├── assets/
│   └── report_template.md                # 报告 Markdown 模板
├── README.md                             # 英文文档
├── README.zh-CN.md                       # 中文文档（本文件）
└── LICENSE                               # MIT 许可证
```

## 工作原理

本 Skill 是**纯 LLM 指令驱动**的 —— 没有脚本、没有外部依赖、不需要 API Key。完全通过结构化的 prompt 引导 AI 助手完成分析工作流。

核心洞察：你的 AI 助手已经在上下文中拥有完整的对话历史。这个 Skill 只是提供了一个系统化的框架，让 AI 去分析这段历史并提取可执行的洞察。

### 工作流概览

```
会话结束 → 触发词 → 步骤1: 提取事件 & 标记浪费
→ 步骤2: 八维度分析 → 步骤3: 生成报告文件
→ 步骤4: 在对话中显示完整分析 → 步骤5: 自动沉淀知识
→ 步骤6: 列出待确认行动项
```

## 适配指南

### 按工具安装

每个 AI 工具有自己的自定义指令约定。核心内容在 `SKILL.md` 和 `references/analysis_dimensions.md` 中。根据工具调整安装方式：

- **WorkBuddy**：直接使用 —— 目录结构就是 Skills 格式
- **Cursor**：创建 `.cursor/rules/retrospective.md`，合并 SKILL.md + analysis_dimensions.md 的关键部分
- **Claude Code**：在 `CLAUDE.md` 中追加「复盘」章节，包含工作流和维度摘要
- **其他工具**：在工具读取自定义指令的位置，放入 SKILL.md 的内容

### 自定义维度

八个维度设计为全面但不穷尽。你可以：
- 添加领域特定维度（如安全敏感项目加入「安全审查」维度）
- 调整各维度的优先级权重，匹配你的工作流
- 根据经验添加新的自检模式

### 自定义报告

编辑 `assets/report_template.md` 以匹配你的团队规范。模板使用占位符变量，由 AI 在生成报告时填充。

## 贡献

欢迎提 Issue 和 PR。以下方向的贡献尤其有价值：

- **新维度**：领域特定的分析维度及自检清单
- **模式库**：特定语言/框架的常见浪费模式
- **工具适配器**：为更多 AI 工具提供预置配置
- **翻译**：分析维度的本地化版本

## 许可证

MIT — 详见 [LICENSE](LICENSE)。


path: references/analysis_dimensions.md
content: # Eight-Dimension Analysis — Evaluation Criteria, Self-Check Lists & Pattern Library

Reference manual for retrospective analysis. Loaded in Step 2 to provide self-check lists, evaluation criteria, and recommendation templates for each dimension.

**Core requirement**: Every dimension must go through its self-check list item by item. A dimension can only be skipped when ALL self-check items are answered "no."

---

## Dimension 1: AI Self-Reflection ⭐ (Highest Priority — Must Be Analyzed First)

### Self-Check List (answer each item)

- [ ] Did the AI give a wrong judgment or conclusion at any point? (e.g., "this is expected behavior" when it wasn't)
- [ ] Did the AI miss something it should have checked? (e.g., modified serialization code but didn't check input boundary cases)
- [ ] Did the AI jump to conclusions prematurely without investigating deeper? (e.g., said "no problem" based on surface symptoms)
- [ ] Did the AI only discover an issue after the user asked, when it should have found it proactively?
- [ ] Did the AI miss critical technical constraints or edge cases during planning/design?
- [ ] Did the AI fail to anticipate foreseeable side effects? (e.g., changed output format but didn't consider parser compatibility)
- [ ] Did the AI's code introduce bugs that required post-fix? Analyze root cause for each bug separately

### Analysis Method

For each "yes" answer:
1. **Locate event**: Which specific conversation turn did this happen?
2. **Quantify impact**: How many extra turns of conversation/debugging did this cause?
3. **Counterfactual reasoning**: If the AI had done X at that point, what could have been avoided?
4. **Root cause classification**:
   - Cognitive blind spot (didn't know a technical fact)
   - Insufficient analysis (only looked at surface, didn't trace root cause)
   - Check omission (changed A but didn't check related B)
   - Over-optimism (declared "no problem" too early)

### Recommendation Template

```
**AI Self-Reflection** [Priority: X]
- Event: Turn N, AI did/didn't do XXX
- Impact: Caused M extra turns / introduced bug / delayed discovery
- Counterfactual: If XXX had been done, YYY could have been saved
- Root cause: Cognitive blind spot / Insufficient analysis / Check omission / Over-optimism
- Improvement: In similar future scenarios, should ZZZ
```

---

## Dimension 2: Verification Strategy

### Self-Check List

- [ ] Did the AI define clear verification criteria before starting implementation? (e.g., "verification passes when X appears in Y")
- [ ] Did the AI proactively provide verification steps/checklists to the user? Or passively wait for "take a look"?
- [ ] After each verification round, did the AI check all core metrics? Or did it only look at some before concluding?
- [ ] When verification failed, did the AI provide clear troubleshooting direction? Or did it take multiple rounds to locate the issue?
- [ ] Could verification rounds have been fewer? If the AI had given a complete checklist upfront, could the user have verified in one pass?

### Common Problem Patterns

| Pattern | Problem | Improvement |
|---------|---------|-------------|
| Passive verification | Waiting for user to say "I ran it, take a look" | AI should proactively output verification checklist with expected results |
| Partial verification | Only checked new feature, not core objectives | Verify against requirements item by item |
| Missing edge cases | Didn't verify boundary conditions/error paths | Checklist should include happy path + boundary + error cases |
| Multi-round verification | User had to run tests repeatedly | Give complete verification plan upfront to minimize round-trips |

### Recommendation Template

```
**Verification Strategy** [Priority: X]
- Event: <specific verification scenario>
- Problem: <efficiency loss during verification>
- Counterfactual: If AI had provided verification checklist [item1, item2, ...] at turn N, M round-trips could have been saved
- Recommendation: <improved verification strategy>
```

---

## Dimension 3: Automation Opportunities

This dimension identifies repetitive workflows or hand-written scripts that could be encapsulated into reusable automations — regardless of the specific tool ecosystem.

### Self-Check List

- [ ] Was any operation executed 2+ times during the session? (e.g., hand-written analysis scripts, formatted output)
- [ ] Was there a fixed multi-step process (3+ steps) that followed the same pattern?
- [ ] Did the AI hand-write scripts that could be templatized or tool-ized? (especially one-off Python/shell scripts)
- [ ] Are there operations that would likely recur in future sessions?

### Common Signal Patterns

| Signal | Example |
|--------|---------|
| Hand-written one-off script ≥2 times | Multiple Python scripts analyzing similar data files |
| Multi-step fixed process | "Every time: first X, then Y, finally Z" |
| Domain-specific knowledge | Operations involving specific APIs, framework conventions, business rules |
| Repeated instructions | User giving same guidance across different sessions |

### What "automation" means per tool

| AI Tool | Automation Mechanism |
|---------|---------------------|
| WorkBuddy | Skills (SKILL.md + directory structure) |
| Cursor | .cursor/rules, custom instructions, notepads |
| Claude Code | CLAUDE.md, project instructions, slash commands |
| GitHub Copilot | .github/copilot-instructions.md, custom instructions |
| Windsurf | .windsurfrules, Cascade workflows |
| Cline | .clinerules, custom instructions |
| Generic | Prompt templates, checklists, runbooks stored in project |

### Recommendation Template

```
**Automation Opportunity** [Priority: X]
- Suggested name: <descriptive-name>
- Trigger scenario: <when should this be used>
- Core workflow: <main steps overview>
- Repetition count this session: N times
- Estimated benefit: <what it saves or improves>
- Implementation hint: <which automation mechanism fits your tool>
```

---

## Dimension 4: Existing Automation Tuning

This dimension evaluates any pre-existing automations, templates, rules, or custom instructions that were active during the session.

### Self-Check List

- [ ] Were any automations/skills/rules/custom instructions triggered during this session? If so, did the AI follow them completely?
- [ ] Was the automation's output corrected or supplemented by the user?
- [ ] Were there scenarios where an automation should have triggered but didn't?
- [ ] Did the automation's output conform to project conventions (paths, naming, format)?

### Common Signal Patterns

| Signal | Possible Problem |
|--------|-----------------|
| AI skipped a step from the automation | Instructions unclear or step description ambiguous |
| Output doesn't match project conventions | Automation not adapted to project-specific rules |
| User manually corrected output | Quality criteria not specific enough |
| Automation didn't trigger when it should have | Trigger conditions not accurately described |

### Recommendation Template

```
**Automation Tuning** [Priority: X]
- Target: <automation/skill/rule name>
- Problem found: <specific issue description>
- Suggested fix: <which part to modify and how>
- Expected improvement: <effect after modification>
```

---

## Dimension 5: Tool Integration Opportunities

This dimension identifies operations that would benefit from dedicated tool integrations, plugins, or API connections — beyond what the AI assistant provides out of the box.

### Self-Check List

- [ ] Did the session involve repeated calls to external APIs or services?
- [ ] Were there operations requiring specific tool capabilities the AI currently lacks?
- [ ] Were there multi-step operations that could be encapsulated into a single tool call?

### Evaluation Criteria

| Characteristic | Suitable For |
|---------------|-------------|
| Needs independent conversation context | Custom agent/sub-agent |
| Needs multi-step reasoning | Custom agent/sub-agent |
| Single function call | Tool plugin / MCP server / API integration |
| Needs external service connection | Tool plugin / MCP server / API integration |

### Tool integration mechanisms per AI tool

| AI Tool | Integration Options |
|---------|-------------------|
| WorkBuddy | MCP servers, custom Agents, Skills with scripts |
| Cursor | MCP servers, custom tools |
| Claude Code | MCP servers, custom slash commands |
| GitHub Copilot | Extensions, MCP servers (preview) |
| Windsurf | MCP servers, tool integrations |
| Generic | Shell scripts, API wrappers, CLI tools |

### Recommendation Template

```
**Tool Integration Opportunity** [Priority: X]
- Type: Agent / Plugin / MCP / API wrapper / CLI tool
- Name: <suggested-name>
- Function: <what it does>
- Current pain point: <the problem without it>
- Implementation hint: <which mechanism fits your tool>
```

---

## Dimension 6: Knowledge Persistence

### Self-Check List

- [ ] Were important technical facts established during the session? (e.g., a module's internal call chain, an API's behavioral characteristics)
- [ ] Did the user correct the AI's behavior and indicate the right approach?
- [ ] Were there significant architecture/design decisions and their rationale?
- [ ] Did the user express clear preferences or conventions?

### Knowledge Categories

| Type | Where to Persist | Examples |
|------|-----------------|---------|
| Global preferences | Tool's memory/persistent config | "I prefer concise output", "Reply in Chinese" |
| Project conventions | Project config or docs | "Callback chain for module X is..." |
| Technical decisions | Project docs or decision log | "Used approach A because..." |

### Persistence mechanisms per tool

| AI Tool | Persistence Options |
|---------|-------------------|
| WorkBuddy | `update_memory`, working memory files, MEMORY.md |
| Cursor | .cursor/rules, notepads, project instructions |
| Claude Code | CLAUDE.md, project-level memory |
| GitHub Copilot | .github/copilot-instructions.md |
| Windsurf | .windsurfrules, memories |
| Cline | .clinerules, custom instructions |
| Generic | README notes, project docs, config files |

### Recommendation Template

```
**Knowledge Persistence** [Auto-execute if possible]
- Type: Global preference / Project convention / Technical decision
- Content: <specific information to persist>
- Suggested location: <where to store, adapted to your tool>
- Reason: <why this is worth persisting>
```

---

## Dimension 7: Documentation Updates

### Self-Check List

- [ ] Did this session's changes involve architecture modifications? Do architecture docs need updating?
- [ ] Are there new coding standards/conventions that should be documented?
- [ ] Are there new tools/scripts that need usage instructions?

### Recommendation Template

```
**Documentation Update** [Priority: X]
- Target document: <file path or document name>
- Update content: <what to add/modify>
- Update reason: <why the update is needed>
```

---

## Dimension 8: Workflow Efficiency

### Self-Check List

- [ ] Were multiple independent steps executed sequentially? (Could have been parallelized)
- [ ] Was the same code/script hand-written multiple times? (Should be reused or tool-ized)
- [ ] Were suboptimal tools or methods used? (Better alternatives exist)
- [ ] Did the AI do unnecessary work? (Over-analysis, redundant verification)
- [ ] How many conversation turns were wasted? What percentage of total turns?

### Common Patterns

| Pattern | Efficiency Loss | Improvement Direction |
|---------|----------------|----------------------|
| Sequential search | Searching files one by one | Use global/project-wide search |
| Trial and error | Multiple modifications to the same spot | Analyze root cause before modifying |
| Hand-written one-off scripts | Rewriting analysis scripts for each verification | Encapsulate into reusable automation |
| Missing verification | No verification after modification | Verify immediately after changes |
| Plan gaps | Plan didn't cover critical constraints | Add technical constraint review step to planning |

### Recommendation Template

```
**Workflow Efficiency** [Priority: X]
- Scenario: <specific efficiency bottleneck>
- Waste quantified: ~N conversation turns / M repeated operations
- Counterfactual: If XXX, could have saved YYY
- Improvement: <more efficient approach>
- Applicability: This session only / General recommendation
```

---

## Priority Scoring Rules

| Priority | Criteria |
|----------|---------|
| **High** | High frequency (encountered in almost every session) OR high impact (≥3 wasted turns) |
| **Medium** | Occasional but with clear improvement path (1-2 wasted turns) |
| **Low** | Nice-to-have improvement, not essential but worth considering |

Prioritize high-priority findings in output. No limit on findings per dimension, but each finding must have a specific event reference and quantified analysis.


path: assets/report_template.md
content: # AI Collaboration Retrospective Report

**Date**: {{DATE_TIME}}
**Session type**: {{SESSION_TYPE}}
**Session length**: {{TURN_COUNT}} turns
**Efficiency score**: {{EFFICIENCY_SCORE}} (optimizable turns / total turns)
**Workspace**: {{WORKSPACE}}
**AI Tool**: {{AI_TOOL}}

---

## Session Summary

{{SUMMARY}}

## Event Timeline

{{EVENT_TIMELINE}}

<!--
Each event format:
| # | Event Type | Description | Tag |

Waste points tagged [⚠ Optimizable] with explanation.
-->

## Analysis Findings

{{FINDINGS}}

<!--
For each dimension with findings, output in this format:

### Dimension N: Dimension Name [Priority]

**Event reference**: Turn X, what specifically happened

**Problem**: Specific issue description

**Counterfactual reasoning**: If X had been done, Y could have been avoided (saving ~N turns)

**Recommendation**: What to do in similar future scenarios

> **Action tag** (Auto-executed / Pending confirmation / Recommendation only)

Dimensions with no findings are omitted entirely — don't output empty sections.
-->

## Auto-Executed Actions

{{AUTO_ACTIONS}}

<!--
List operations auto-executed during this retrospective:
- [Knowledge] Persisted XXX to <location>
If no auto-executed operations, write "None"
-->

## Pending Action List

{{PENDING_ACTIONS}}

<!--
Numbered list, each item format:
1. **[Action type]** Specific content — Expected benefit

If no pending actions, write "No additional actions needed for this session"
-->

---

*Report generated by ai-retrospective skill*


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)