reflect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phase gate: COMMIT checkpoint. This skill MUST verify that .branch-context.md learnings are consolidated to MEMORY.md before the agent considers the task complete.

Post-task review. Do the following in order:

Mark reflect timestamp: Run
```
date +%s > "${CLAUDE_PROJECT_DIR}/ai-workspace/.last-reflect-ts"
```
to reset the auto-reflect reminder for this session.
Review session work: Check
```
git log --oneline -10
```
, recent file edits, and any corrections received this session. If a completed plan exists in
```
ai-workspace/plans/
```
(Status: complete or Outcomes & Learnings filled in), use it. Otherwise, extract learnings from the session directly — git diff, conversation corrections, and patterns discovered.

1b. Verify issue closure: Scan commit messages from this branch for

closes #N

fixes #N

resolves #N

references. For each referenced issue, run

gh issue view N --json state

and confirm it is actually closed. If an issue is still open despite a closing keyword in a commit, warn: "Issue #N referenced as closed but still open — may need a push or merge to trigger closure."

Extract and classify learnings: For each learning identified in Step 1 (from a plan's Outcomes & Learnings or directly from the session): a. Project-specific (references project files, paths, configs) → Write to ai-workspace/MEMORY.md only Example: "This project uses constructor injection via AppContext (see src/di/container.ts)"

b. Cross-project pattern (general tool behavior, coding pattern, preference) → Write to Basic Memory vault via MCP (global knowledge graph) Example: "[[DI Patterns]]: Constructor injection with interface contracts prevents test coupling"

c. Both (general pattern with project-specific instance) → Write adapted versions to both, with cross-references → Vault note links to project; project MEMORY references the pattern

2b. Comment learnings on related issues: Post relevant learnings as comments on related GitHub issues.

If a plan file exists with
Issue: #N
in frontmatter (explicit path): Comment the learnings from Outcomes & Learnings directly on issue #N. Format: "## Learnings from

<plan-name>

\n\n- learning 1\n- learning 2"

If no plan file or no Issue field (fuzzy path): Run

gh issue list --state open --json number,title,labels --limit 50

. For each learning, compare keywords against open issue titles. Present matches to the user for confirmation before commenting. Only comment after explicit approval — a bad auto-comment is worse than a missed one.

Write to MEMORY.md: Append project-specific items. Prune entries older than 30 days. Keep under 200 lines. If over, summarize and compress the oldest section.
Write to Basic Memory: Create or update notes in the vault via MCP. Use [[wiki-links]] for connections. Tag with project name for cross-referencing.
ADR check: If significant patterns emerged not yet formalized, prompt: "Should this become an ADR?"

5b. Create issues from surfaced work: If the reflect process surfaced TODOs, gotchas, follow-up work, or technical debt not yet tracked, create GitHub issues for them. Run

gh issue list --state open --json number,title --limit 50

first to avoid duplicates. Use labels appropriate to the type (bug, enhancement, chore, etc.). Report created issues in the output summary.

Finalize plan: Rename completed plan to
```
<name>.done.md
```
(triggers write protection).
Scratchpad: Review
```
ai-workspace/scratchpad.md
```
. Items marked with
```
- [ ]
```
are flagged for elevation to GitHub issues. For each
```
- [ ]
```
item:
- Create a GitHub issue with appropriate title and labels
- Convert the item to
```
- [x] → #N
```
  with the created issue number Items without checkboxes (plain
```
- 
```
  bullets) are reference material — leave them.
Phase gate verification:
- Read
```
.branch-context.md
```
  if it exists in the worktree or current directory
- Extract validated learnings from it
- Verify at least 1 line was added to MEMORY.md (diff check)
- Clean up worktree:
```
git worktree remove .worktrees/<name>
```
  (if applicable)
- If MEMORY.md was NOT updated and .branch-context.md had content, warn: "MEMORY.md not updated — consolidate learnings before declaring task complete"
- If .branch-context.md is empty or doesn't exist, warn: "No .branch-context.md found — no learnings to consolidate" but still complete (don't block)
- Gate: Agent cannot declare task complete until this step confirms MEMORY.md updated OR confirms no learnings to consolidate

Output: Summary of what was added to each memory layer, what was pruned, issues created/closed/commented, any ADR prompts.

阶段关口：COMMIT 检查点。本技能必须在Agent判定任务完成之前，验证 .branch-context.md 中的经验教训已经合并到 MEMORY.md 中。

任务后复盘，请按顺序执行以下操作：

标记复盘时间戳：运行
```
date +%s > "${CLAUDE_PROJECT_DIR}/ai-workspace/.last-reflect-ts"
```
重置本次会话的自动复盘提醒。
复盘会话工作内容：查看
```
git log --oneline -10
```
、最近的文件编辑记录，以及本次会话收到的所有修正内容。如果
```
ai-workspace/plans/
```
目录下存在已完成的计划（状态：已完成，或者已填写结果与经验教训），就使用该计划的内容。否则直接从本次会话中提取经验教训：包括git diff、对话修正内容、以及发现的规律模式。

1b. 验证issue关闭状态：扫描当前分支的提交信息，查找包含

closes #N

、

fixes #N

、

resolves #N

的引用。对每个被引用的issue，运行

gh issue view N --json state

确认它确实已关闭。如果提交信息中有关闭关键词但issue仍然处于开启状态，发出警告："Issue #N referenced as closed but still open — may need a push or merge to trigger closure."

提取并分类经验教训：针对步骤1中识别到的每条经验教训（来自计划的「结果与经验」部分，或者直接来自本次会话）： a. 项目专属（涉及项目文件、路径、配置）→ 仅写入 ai-workspace/MEMORY.md 示例："This project uses constructor injection via AppContext (see src/di/container.ts)"

b. 跨项目通用模式（通用工具行为、编码模式、偏好设置）→ 通过MCP（全局知识图谱）写入基础记忆库示例："[[DI Patterns]]: Constructor injection with interface contracts prevents test coupling"

c. 两者皆是（带有项目特定实例的通用模式）→ 分别适配后写入两个位置，同时添加交叉引用：记忆库笔记关联到项目，项目MEMORY文件引用对应模式

2b. 在相关issue下评论经验教训：将相关经验教训作为评论发布到对应的GitHub issues上。

如果计划文件的前置元数据中包含
Issue: #N
（明确关联路径）：直接将「结果与经验」中的内容评论到issue #N下。格式："## Learnings from

<plan-name>

\n\n- learning 1\n- learning 2"

如果没有计划文件或者没有Issue字段（模糊匹配路径）：运行

gh issue list --state open --json number,title,labels --limit 50

。对每条经验教训，将关键词与开启状态的issue标题进行匹配。发布评论前先将匹配结果展示给用户确认，只有获得明确批准后才评论——错误的自动评论比遗漏评论更糟糕。

写入MEMORY.md：追加项目专属的经验条目。删除超过30天的旧条目，保持文件行数不超过200行。如果超出就对最旧的部分进行总结压缩。
写入基础记忆库：通过MCP在记忆库中创建或更新笔记。使用[[wiki-links]]建立关联，打上项目名称标签便于交叉引用。
ADR检查：如果出现了尚未正式确定的重要模式，提示用户："Should this become an ADR?"

5b. 为浮出的工作创建issue：如果复盘过程中发现了尚未跟踪的待办事项、注意事项、后续工作或者技术债务，为它们创建GitHub issues。先运行

gh issue list --state open --json number,title --limit 50

避免重复创建，使用匹配类型的标签（bug、enhancement、chore等），并在输出总结中报告创建的issue。

完成计划归档：将已完成的计划重命名为
```
<name>.done.md
```
（触发写保护）。
便签本处理：查看
```
ai-workspace/scratchpad.md
```
。标记为
```
- [ ]
```
的条目需要升级为GitHub issues。对每个
```
- [ ]
```
条目：
- 创建一个标题和标签合适的GitHub issue
- 将原条目改为
```
- [x] → #N
```
  ，N为创建的issue编号没有复选框的条目（普通
```
- 
```
  列表项）是参考资料，保留不动。
阶段关口验证：
- 如果工作树或者当前目录下存在
```
.branch-context.md
```
  则读取该文件
- 从中提取经过验证的经验教训
- 验证MEMORY.md至少新增了1行内容（diff检查）
- 清理工作树：
```
git worktree remove .worktrees/<name>
```
  （如果适用）
- 如果MEMORY.md未更新且.branch-context.md有内容，发出警告："MEMORY.md not updated — consolidate learnings before declaring task complete"
- 如果.branch-context.md为空或者不存在，发出警告："No .branch-context.md found — no learnings to consolidate" 但仍然允许完成（不阻塞流程）
- 关口规则：Agent只有在本步骤确认MEMORY.md已更新，或者确认没有经验教训可合并后，才能声明任务完成

输出：各内存层新增内容概要、删除内容概要、创建/关闭/评论的issue信息、所有ADR提示。