reflect

复盘：把学习写进 skill

Mine the current conversation for durable learnings, then route them into skill edits.

从当前对话挖可持久学习，再路由成 skill 编辑。

When to invoke

何时调用

Invoke when the user says “reflect” or “/reflect”. Skip when the conversation is trivial, off-topic, or already covered by an existing skill the parent followed correctly. One-offs are not learnings.

用户说 “reflect” 或 “/reflect” 时调用。对话琐碎、跑题，或已被 parent 正确遵循的已有 skill 覆盖时跳过。一次性事件不是学习。

Process

流程

1. Locate the active transcript

1. 定位活跃 transcript

The parent finds its own transcript file before fanning out. The system prompt names the active workspace’s agent-transcripts/ directory. Use that path. Do not glob across ~/.cursor/projects/*/. That crosses workspace boundaries and reads private chats from unrelated projects.

parent 扇出前找到自己的 transcript 文件。system prompt 点名当前工作区的 agent-transcripts/ 目录。用那条路径。别跨 ~/.cursor/projects/*/ glob——会跨工作区读无关私聊。

列出候选 transcript（按修改时间）：

ls -t <agent-transcripts>/*.jsonl <agent-transcripts>/*/*.jsonl <agent-transcripts>/*/subagents/*.jsonl 2>/dev/null | head -10

Three transcript layouts: legacy flat (<id>.jsonl), current nested (<id>/<id>.jsonl), and subagent (<parent>/subagents/<child>.jsonl).

三种 transcript 布局：旧扁平（<id>.jsonl）、当前嵌套（<id>/<id>.jsonl）、subagent（<parent>/subagents/<child>.jsonl）。

For each candidate, read the first JSONL line and check that message.content[0].text contains the conversation’s opening user prompt. Take the matching path. If no path resolves, write a tight digest of the session and pass that instead.

对每个候选，读第一行 JSONL，检查 message.content[0].text 是否含对话开场用户 prompt。取匹配路径。解析不到就写紧凑会话摘要代替。

2. Spawn three reviewers in parallel

2. 并行 spawn 三个审阅者

One message, three Task calls, subagent_type: generalPurpose, explicit model: on each, agent mode (readonly: false). Reviewers need MCP access for context lookups (tickets, chat threads, observability traces referenced in the transcript). Readonly strips MCPs.

一条消息、三个 Task 调用，subagent_type: generalPurpose，每个显式 model:，agent 模式（readonly: false）。审阅者需要 MCP 做上下文查找（transcript 里引用的工单、聊天线程、可观测追踪）。只读会剥掉 MCP。

Pass each template verbatim, substituting the transcript path or digest where marked. Reviewers return findings in the Task response body.

逐字传入各模板，在标记处替换 transcript 路径或摘要。审阅者在 Task 响应体返回发现。

3. Synthesize

3. 综合

One Task call, subagent_type: generalPurpose, using your configured reflect-judgment model (default claude-opus-5-5-max), agent mode (readonly: false). The synthesizer’s quality check includes spot-verifying citations, which can require MCP access. Readonly strips MCPs. Use references/synthesizer.md verbatim, with each reviewer’s full output inlined where marked. The synthesizer returns a structured Accepted / Rejected / Backlog list.

一次 Task，subagent_type: generalPurpose，用配置的 reflect-judgment 模型（默认 claude-opus-5-5-max），agent 模式（readonly: false）。综合者质检含抽查引用，可能需要 MCP。只读会剥掉 MCP。逐字用 references/synthesizer.md，在标记处内联每个审阅者完整输出。综合者返回结构化 Accepted / Rejected / Backlog 列表。

4. Structural enforcement check

4. 结构强制检查

Sanity-check the synthesizer’s Accepted list. For any item that would be enforced more reliably by a lint rule, script, metadata flag, or runtime check, move it from Accepted to Backlog. See the encode-lessons-in-structure principle skill.

对综合者 Accepted 列表做健全性检查。任何用 lint、脚本、元数据标志或运行时检查能更可靠强制的项，从 Accepted 挪到 Backlog。见 encode-lessons-in-structure。

5. Apply

5. 应用

Before applying any Accepted edit, present the synthesizer’s full Accepted/Rejected/Backlog output to the user and wait for explicit approval. The user picks which subset to apply and may redirect routings. Skill changes affect every future agent in the org. Do not auto-apply.

应用任何 Accepted 编辑前，把综合者完整 Accepted/Rejected/Backlog 输出给用户，等明确批准。用户选应用哪些子集，并可改路由。Skill 改动影响组织里每个未来 agent。别自动应用。

Backlog items file to whatever devex / backlog tracker your team uses automatically. Only the Accepted list waits for approval.

Backlog 项自动记到团队用的 devex / backlog tracker。只有 Accepted 列表等批准。

For each approved Accepted item, follow the Routing field exactly:

对每个批准的 Accepted 项，严格跟 Routing 字段：

• Trivial existing-skill edit (a one-line bullet, a tightened sentence, a stale fact corrected): parent does directly.

• Substantive existing-skill edit (a new section, a new pattern table, more than ~10 lines): hand to Cursor’s built-in create-skill skill and run its draft / test / iterate loop.

• tune description: <skill path> (the skill exists but didn’t trigger when it should have): hand to create-skill and run its description-optimization loop.

• new skill via create-skill: <kebab-name>: hand creation to create-skill. Do not invent the shape ad hoc.

• 琐碎已有 skill 编辑（一行子弹、收紧一句、纠正过时事实）：parent 直接做。

• 实质性已有 skill 编辑（新小节、新模式表、超过约 10 行）：交给 Cursor 内置 create-skill，跑其草稿/测试/迭代环。

• tune description: <skill path>（skill 存在但该触发时没触发）：交给 create-skill 跑 description 优化环。

• new skill via create-skill: <kebab-name>：交给 create-skill 创建。别临场发明形状。

If your environment ships a SKILL.md validator, run it on every touched skill before declaring done. Skip this step if it doesn’t.

环境若带 SKILL.md 校验器，宣布完成前对每个碰过的 skill 跑它。没有就跳过。

6. Summarize for the user

6. 给用户摘要

Short list, no preamble:

短列表，无开场白：

• Edits applied: <skill path>. What changed, one line each.

• New skills created: <skill path>. One line each (rare).

• Backlog filed to the devex tracker: <issue title> (<tags>). One line each.

• Dropped: one line per rejected finding + reason from the synthesizer.

• 已应用编辑：<skill path>。改了什么，各一行。

• 新建 skill：<skill path>。各一行（少见）。

• 已记入 devex tracker 的 backlog：<issue title>（<tags>）。各一行。

• 丢弃：每个被拒发现一行 + 综合者理由。