reflect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

reflect — turn this session's problems into durable improvements

reflect — 将本次会话问题转化为持久改进措施

Every session teaches something. This skill harvests those lessons and files each one where it will actually fire next time, so the workflow compounds.

It is problem-focused, not a summary. If you want "what did I do", that is

invoice-generator

. If you want one bug's canonical record, that is

post-mortem

reflect

asks: what should change about how we work?

每次会话都能带来经验。本Skill会收集这些经验教训，并将其归档到下次能实际发挥作用的地方，从而让工作流持续优化。

它以问题为核心，而非总结内容。如果你需要“我做了什么”的总结，那是

invoice-generator

的功能。如果你需要单个Bug的标准记录，那是

post-mortem

的功能。

reflect

关注的是：我们的工作方式应该做出哪些改变？

When NOT to run

何时不应运行

Trivial or purely conversational sessions — concluding "no durable lesson" and exiting is a valid, first-class outcome. Do not manufacture findings.
As a stand-in for
```
invoice-generator
```
or
```
post-mortem
```
.

无关紧要或纯闲聊的会话——得出“无持久经验可总结”的结论并退出是合理的、可接受的结果。不要强行制造发现。
替代
```
invoice-generator
```
或
```
post-mortem
```
使用。

Scope

适用范围

Analyze the current conversation context. Do NOT parse transcript files from disk. If the session was compacted, work from what remains and say so: "analysis limited to post-compaction context".

分析当前对话上下文。请勿解析磁盘中的转录文件。如果会话内容已被压缩，请基于剩余内容进行分析，并说明：“分析受限于压缩后的上下文”。

Stage 1 — Harvest

阶段1 — 收集经验

Scan the session for four signal types:

Signal	Definition
Correction	The user corrected the approach, output, or understanding.
Friction	Repeated manual steps, wrong tool first, retries, permission churn.
Skill failure	A skill was used but guided wrong/insufficiently, OR should have triggered and did not.
Skill gap	A recurring workflow done ad-hoc that no skill covers.

These four are prompts to notice lessons, not an exhaustive partition — capture any recurring pain even if it does not fit a row cleanly.

For each finding record: what happened, evidence (a concrete moment), cost (rework / time / tokens), proposed lesson.

Cap at ~5 findings, ranked by cost. High-signal, not exhaustive. If nothing clears the bar, say so and exit.

扫描会话内容，寻找四类信号：

信号类型	定义
修正	用户纠正了方法、输出结果或认知。
摩擦	重复的手动步骤、首次使用错误工具、重试、权限频繁变更。
Skill失效	使用了某个Skill但引导错误/不足，或者本该触发却未触发。
Skill缺口	反复出现的临时工作流，没有对应的Skill覆盖。

这四类信号是发现经验教训的提示，而非穷尽分类——即使某类痛点不完全符合上述分类，只要是反复出现的问题，也要记录下来。

针对每个发现，记录：发生了什么、证据（具体场景）、成本（返工/时间/令牌消耗）、建议的经验教训。

最多记录约5个发现，按成本高低排序。聚焦高价值信号，而非穷尽所有。如果没有符合标准的发现，请说明并退出。

Stage 2 — Research & route

阶段2 — 调研与分配

Per finding, run up to three passes, gated by type so tokens are not wasted:

Pass A — Local overlap (always). Search owned skills, the auto-memory index (MEMORY.md), and the relevant project CLAUDE.md. Update beats create.
Pass B — External prior art (only for new-skill candidates). Search GitHub (
```
gh search repos
```
/
```
gh search code
```
) for existing Claude skills and SKILL.md patterns, and the web (WebSearch/WebFetch) for the pattern. Outcome: adopt (good skill exists — reference it), inform (borrow patterns), or greenfield (build it).
Pass C — Technical verification (only when the lesson is a technical claim). Verify against official docs, the actual code, and GitHub issues before persisting. Never persist a wrong fix forever.

Research guardrails: external findings are read-only input to proposals (nothing auto-applied); bounded to a couple of targeted searches per finding (inconclusive -> "no strong prior art found", proceed, never block); attribute any borrowed source by URL/repo.

Assign each finding exactly one route:

Route	Destination	When
A	Update existing skill	An owned skill should have prevented this.
B	New skill (hand to skill-creator)	Recurring workflow, no skill, no good external one to adopt.
C	Project CLAUDE.md	This project's own convention, architecture, or project-only gotcha (this repo only).
D	Auto-memory	Personal preference or a single-project fact.
E	Discard	One-off noise.
F	Global gotcha ( `~/.claude/GOTCHAS.md` )	A cross-project tooling / environment / harness trap.

F vs C vs D — one-line test. Ask "if I did this in another project, would this same thing bite me?" Yes → F — it fires everywhere via the

-imported

~/.claude/GOTCHAS.md

. No, it's this repo's own rule → C. A preference or one-project fact → D. Route F explicitly reclaims the cross-project tooling/environment lessons that used to default to D (D's store is keyed by project directory, so they never surfaced in other projects).

Ownership guardrail: Route A applies ONLY to skills you own — any plugin in this repo (

dev-workflows

ado-backlog

github-backlog

, ...) and personal skills under

~/.claude/skills

. Third-party skills (superpowers, skill-creator, Microsoft plugins) are READ-ONLY; their lessons become a Route D memory or a Route C CLAUDE.md override instead.

Route F writes global config. Route F targets the user's global Claude config —

~/.claude/GOTCHAS.md

plus one

@~/.claude/GOTCHAS.md

import line in

~/.claude/CLAUDE.md

. The user owns these, so writing is allowed, but the edit to the personal

CLAUDE.md

is announced before it happens (see Stage 4) — the same transparency Route D memory writes get.

针对每个发现，最多进行三轮调研，根据类型区分以避免浪费令牌：

第一轮 — 本地重叠检查（必做）：搜索自有Skill、自动内存索引（MEMORY.md）及相关项目的CLAUDE.md文件。优先更新而非创建新内容。
第二轮 — 外部已有方案调研（仅针对需创建新Skill的情况）：搜索GitHub（
```
gh search repos
```
/
```
gh search code
```
）中已有的Claude Skill和SKILL.md模板，以及通过WebSearch/WebFetch在网络上搜索相关模式。结果分为：采用（存在优质Skill——引用它）、参考（借鉴模板）、全新开发（自行构建）。
第三轮 — 技术验证（仅针对涉及技术主张的经验教训）：在保存前，对照官方文档、实际代码及GitHub问题进行验证。切勿永久保存错误的修复方案。

调研规则：外部发现仅作为提案的输入（不会自动应用）；每个发现仅进行几次针对性搜索（若无结果则标注“未找到明确的已有方案”，继续推进，绝不阻塞）；对任何借鉴的来源，需通过URL/仓库地址注明出处。

为每个发现分配唯一的流向：

流向	目标位置	适用场景
A	更新现有Skill	自有Skill本应避免此类问题。
B	新Skill（移交skill-creator）	存在反复出现的工作流，但无对应Skill，也无合适的外部Skill可采用。
C	项目CLAUDE.md文件	属于本项目特有的约定、架构或仅本项目存在的陷阱（仅限当前仓库）。
D	自动内存	个人偏好或单一项目的特定事实。
E	丢弃	一次性噪声。
F	全局陷阱文件（ `~/.claude/GOTCHAS.md` ）	跨项目的工具/环境/框架陷阱。

流向F、C、D的快速区分测试：问自己“如果我在另一个项目中做同样的事，是否会遇到同样的问题？”是→F——该陷阱会通过

导入的

~/.claude/GOTCHAS.md

在所有项目中生效。否，仅为本仓库规则→C。个人偏好或单一项目事实→D。流向F专门回收过去默认归入D的跨项目工具/环境经验教训（D的存储按项目目录分类，无法在其他项目中显示）。

所有权规则：流向A仅适用于你拥有的Skill——包括本仓库中的任何插件（

dev-workflows

、

ado-backlog

、

github-backlog

等）以及

~/.claude/skills

下的个人Skill。第三方Skill（superpowers、skill-creator、Microsoft插件）为只读；相关经验教训将归入流向D的内存或流向C的CLAUDE.md覆盖内容。

流向F会写入全局配置：流向F针对用户的全局Claude配置——

~/.claude/GOTCHAS.md

文件，以及

~/.claude/CLAUDE.md

中的一行

@~/.claude/GOTCHAS.md

导入语句。这些文件归用户所有，因此允许写入，但在写入个人

CLAUDE.md

前需先告知用户（见阶段4）——这与流向D的内存写入保持相同的透明度。

Stage 3 — Present & approve

阶段3 — 展示与确认

Present a numbered list. Each item: finding -> evidence -> route -> concrete proposed change (actual replacement text or diff, plus any cited source — never "improve X"). The user replies which numbers to apply (all / some / none).

以编号列表形式展示。每个条目包含：发现→证据→流向→具体的建议变更（实际替换文本或差异内容，加上引用来源——绝不能只写“改进X”）。用户回复需应用的条目编号（全部/部分/无）。

Stage 4 — Apply (approved items only)

阶段4 — 执行（仅针对已确认的条目）

Route A (owned skill): edit the skill SOURCE, never the installed cache. Then, by where the skill lives:
- A plugin in this repo (e.g.
```
dev-workflows
```
  ,
```
ado-backlog
```
  ,
```
github-backlog
```
  ): edit under
```
C:\Repo2\workflow daily work
```
  and bump the OWNING plugin version in BOTH its own
```
plugins/<plugin>/.claude-plugin/plugin.json
```
  and its entry in the repo-root
```
.claude-plugin/marketplace.json
```
  (keep the two identical).
- A personal skill under
  ~/.claude/skills
  : edit in place — there is no plugin manifest or version to bump. Either way the edit will not load until the cache is re-synced and Claude Code restarts — perform the file steps, then TELL the user a restart is required (you cannot restart the session). See the
```
claude-skills-resync-mechanism
```
  memory for the copy + installed_plugins.json procedure.
Route B (new skill): hand off to
```
skill-creator
```
/
```
writing-skills
```
— do not hand-roll a SKILL.md that duplicates their job.
Route C (CLAUDE.md): edit the relevant repo's CLAUDE.md, matching its structure.
Route D (memory): write the memory file and add a one-line MEMORY.md pointer, per the memory schema; check for an existing file to update first.
Route E: nothing.
Route F (global gotcha ->
~/.claude/GOTCHAS.md
): the destination is a standalone, cross-project file that Claude Code auto-loads in every session via an
```
@
```
import in the global
```
~/.claude/CLAUDE.md
```
. Provision it lazily and idempotently:
1. Ensure the file. If
```
~/.claude/GOTCHAS.md
```
  is missing, create it with a short header (title + one line: auto-loaded everywhere via
```
@
```
  in ~/.claude/CLAUDE.md, one gotcha = one line, grouped by area, update in place). If it exists, never clobber it.
2. Append or update -- a forward-looking WARNING, not an event log. A gotcha exists to steer future behavior, and this file loads on EVERY turn, so every word is a per-turn tax. Write the trap -> fix, not the story:
```
- **<trap, stated so future-you recognizes it>** -- <fix / rule>. (YYYY-MM-DD)
```
  Target ~1 line (2 only when the fix truly needs it). Keep the recognizable symptom and the fix; cut the incident narrative -- no "hit twice", "chased X once", blow-by-blow, or saying the same thing twice. The story, evidence, and timeline go in the Stage 5 reflections record (and a post-mortem for a full bug), NOT here. A tiny parenthetical for credibility is fine; a paragraph is not. Before adding, search for the bold
```
<trap>
```
  ; if present, UPDATE that line in place (refine + re-date) instead of duplicating. Never auto-delete; the date supports manual review. No Mermaid diagram (convention-exempt like MEMORY.md, ADR 0030). Any literal
```
@path
```
  written INTO this file must be backticked, or it would itself be re-imported.
3. Ensure the import (first time only, announced). If
```
~/.claude/CLAUDE.md
```
  has no bare
```
@~/.claude/GOTCHAS.md
```
  line, first TELL the user: "adding one
```
@import
```
  line to your global CLAUDE.md so gotchas auto-load in every project — Claude Code will ask you to approve the import on next start, please approve it." Then append the line at end of file, written plain (never inside backticks / a code fence, or it will not import). A newly filed gotcha is inert until the next session — it loads only after a restart and after the user approves that import; do NOT report the gotcha as already live. If global gotchas ever stop loading, the import was likely declined (Claude Code will not re-prompt) — re-enable it in Claude Code settings.

Note: writes into

C:\Repo2\workflow daily work

and other non-glasshull paths are blocked for the Write/Edit tools by the mobile-app write-guard hook — use PowerShell here-strings or Bash for those.

流向A（自有Skill）：编辑Skill的源代码，而非已安装的缓存文件。根据Skill的存储位置操作：
- 本仓库中的插件（例如
```
dev-workflows
```
  、
```
ado-backlog
```
  、
```
github-backlog
```
  ）：在
```
C:\Repo2\workflow daily work
```
  下编辑，并在插件自身的
```
plugins/<plugin>/.claude-plugin/plugin.json
```
  和仓库根目录的
```
.claude-plugin/marketplace.json
```
  中同时更新该插件的版本号（保持两者一致）。
- ~/.claude/skills
  下的个人Skill：直接原地编辑——无需更新插件清单或版本号。无论哪种情况，编辑内容需在缓存重新同步且Claude Code重启后才会生效——完成文件编辑步骤后，告知用户需要重启（你无法重启会话）。有关复制和installed_plugins.json的流程，请查看
```
claude-skills-resync-mechanism
```
  内存记录。
流向B（新Skill）：移交
```
skill-creator
```
/
```
writing-skills
```
处理——不要手动编写SKILL.md，避免重复他们的工作。
流向C（CLAUDE.md）：编辑对应仓库的CLAUDE.md文件，保持其原有结构。
流向D（内存）：写入内存文件，并根据内存模式添加一行MEMORY.md指针；先检查是否存在已有文件，如有则优先更新。
流向E：无需操作。
流向F（全局陷阱→
~/.claude/GOTCHAS.md
）：目标是一个独立的跨项目文件，Claude Code会通过全局
```
~/.claude/CLAUDE.md
```
中的
```
@
```
导入语句在每次会话中自动加载。需按需且幂等性地进行配置：
1. 确保文件存在：如果
```
~/.claude/GOTCHAS.md
```
  不存在，创建该文件并添加简短头部（标题 + 一行说明：通过~/.claude/CLAUDE.md中的
```
@
```
  导入，在所有会话中自动加载，每个陷阱占一行，按领域分组，原地更新）。如果文件已存在，请勿覆盖。
2. 追加或更新——前瞻性警告，而非事件日志：陷阱记录用于引导未来行为，且该文件会在每一轮会话中加载，因此每一个字都会占用会话资源。请编写**<陷阱>→<修复方案>，而非事件经过：
  - **<陷阱，需让未来的你能识别>** -- <修复方案/规则>。(YYYY-MM-DD)
  目标为约1行（仅当修复方案确实需要时才用2行）。保留可识别的症状和修复方案；删除事件叙事——不要写“遇到两次”、“曾排查X”、详细过程或重复内容。事件经过、证据和时间线应记录在阶段5的回顾记录中（若为完整Bug则记录在post-mortem中），而非此处。可添加简短的括号说明以提升可信度，但不要写成段落。添加前，搜索加粗的
  <陷阱>
  内容；如果已存在，则原地更新该行**（优化内容并更新日期），避免重复。请勿自动删除内容；日期支持手动回顾。请勿添加Mermaid图表（如同MEMORY.md、ADR 0030一样不受格式约束）。写入该文件的任何字面量
```
@path
```
  必须用反引号包裹，否则会被自动导入。
3. 确保导入语句存在（仅首次操作，需告知用户）：如果
```
~/.claude/CLAUDE.md
```
  中没有独立的
```
@~/.claude/GOTCHAS.md
```
  行，先告知用户：“将在你的全局CLAUDE.md中添加一行
```
@import
```
  语句，以便陷阱内容在所有项目中自动加载——Claude Code会在下次启动时请求你确认导入，请予以批准。”然后在文件末尾添加该行，以纯文本形式写入（不要放在反引号/代码块中，否则无法生效）。新归档的陷阱在下次会话前不会生效——需重启会话且用户批准导入后才会加载；请勿报告陷阱已生效。如果全局陷阱内容停止加载，可能是用户拒绝了导入（Claude Code不会再次提示）——需在Claude Code设置中重新启用。

注意：移动应用的写入保护钩子会阻止Write/Edit工具写入

C:\Repo2\workflow daily work

及其他非透明路径——请使用PowerShell here-strings或Bash进行操作。

Stage 5 — Record & commit offer

阶段5 — 记录与提交提议

Append a terse block to
```
docs/reflections/YYYY-MM.md
```
in the plugin repo (create
```
docs/reflections/
```
on first use). One block per session: date, project, findings (one line each — tag the route, e.g.
```
[Route F · GOTCHAS.md] <title>
```
for a global gotcha), applied vs skipped, cited sources. Short and greppable — not a narrative.
Run the commit offer (assisted, never automatic): write files first, then ask before staging/committing. Respect workspace git rules — confirm the target repo before committing when the path is a non-repo root or one of several sub-repos.

在插件仓库的
```
docs/reflections/YYYY-MM.md
```
中追加一段简洁的内容（首次使用时创建
```
docs/reflections/
```
目录）。每次会话对应一段：日期、项目、发现（每行一个——标注流向，例如全局陷阱标注
```
[Route F · GOTCHAS.md] <标题>
```
）、已应用/已跳过、引用来源。内容需简短且支持 grep 搜索——不要写成叙事性文本。
发起提交提议（辅助操作，绝不自动提交）：先写入文件，然后询问用户是否要暂存/提交。遵循工作区的Git规则——当路径为非仓库根目录或多个子仓库之一时，提交前需确认目标仓库。