aep-reflect

反思

闭合反馈回路。将真实世界的观察转化为对产品上下文的可执行更改——故事图、架构，甚至机会假设。

适用场景：

/aep-envision → /aep-map → /aep-scaffold → [ /aep-design → /aep-launch → /aep-build → /aep-wrap ] → /aep-reflect
                                                                          ▲ you are here

会话： 主会话，与用户交互 输入： 发布后的观察（用户测试、错误日志、成本数据、产品直觉） 输出： 分类后的反馈 + 更新后的 product-context.yaml；如果产品意图发生变化，还需更新 product/index.yaml（拆分模式）

---

开始之前

模式语义（split、v1 与 new-project）以 references/file-resolution.md 为准——请在此运行探测。Reflect 从 product/index.yaml（split）或 product-context.yaml（v1）读取产品定义，了解预期目标；并从 product-context.yaml 读取运行状态（cost、stories、changelog），了解实际情况。Reflect 将运行状态更改写入 product-context.yaml；产品意图更改写入 product/index.yaml（split）或 product-context.yaml（v1）。如果这两个文件都不存在，就没有可供反思的内容——请先运行 /aep-envision，然后运行 /aep-map。

---

步骤 1：收集反馈

从所有来源收集观察结果：

• 用户测试： 哪些地方有效？哪些地方让人困惑？缺少什么？
• 错误日志 / 监控： 运行时故障、性能问题、意外行为
• 成本数据： 检查 product-context.yaml 的 cost 部分。如果存在 Agent 执行跟踪记录，请检查每个故事的成本。哪些故事类型成本高？重试主要集中在哪里？
• 产品直觉： 看到产品实际运行后，用户的直觉是什么？哪些地方感觉合适，哪些地方感觉不对？
• Dogfood 报告： 阅读 .dev-workflow/dogfood-*.md。使用 dogfood_report 适配器（references/telemetry-ingestion.md → Dogfood-report 适配器）规范化每条 ## 发现，转为步骤 2 分类的同类观察记录——这是 /aep-watch 无头模式下接收的相同来源。
• 经验教训： 阅读 lessons-learned/*.md（工作区 Agent 在构建期间记录的观察）；总结反复出现的错误、有效的解决方案和缺失的文档。
• 层级提炼： 阅读 lessons-learned/distillations/*.yaml——这是某个层级完成后由 /aep-wrap Reflect and Advance 撰写的仅供提案使用的综合内容。使用 distillation 适配器（references/telemetry-ingestion.md → Distillation 适配器）规范化每个条目：refinements → refinement（含 target_layer），skill_amendments → process（提议，不会自动应用），weak_areas → discovery/refinement。

自动摄取（可选）： 可根据 references/telemetry-ingestion.md 直接拉取错误日志、分析数据和监控数据，并将其规范化为步骤 2 分类的同类观察格式。在 topology.routing.telemetry_sources 下配置端点。摄取的记录会在分类前与人工输入合并，且人工仍需审核每项分类。

后置条件： 已审核上述每个来源，并将其发现规范化为步骤 2 的观察记录（或明确标记该来源在本轮为空）。

---

步骤 2：对每条观察进行分类

每条反馈都必须归入以下五个类别之一。向用户展示每项分类，并允许用户覆盖——他们比任何框架都更了解自己的产品。本节是标准分类器；/aep-watch 会在无头模式下应用该分类器。

Bug

已指定的行为无法正常工作。

• 操作： 直接在 product-context.yaml 的 stories 部分添加一个新故事，并在当前层级将其设为 priority: high 和 status: pending；转交给 /aep-dispatch。

校准

需要改进的现有工作行为，或需要在不同层级间调整的现有故事。

• 操作： 在下一层的 stories 部分中添加一个新故事，并设置 status: pending（包含层级分配和依赖项）。或者，如果经过学习发现某个后续层级的现有故事需要提前处理，则将其提升到较早的层级。

• 子类型 — 校准： “能够正确运行”与“感觉合适”之间存在差距。代码按规范运行，规范也正确，但结果不符合人的预期。请确认：代码是否按规范运行（是 → 不是 Bug）？规范是否正确（是 → 不是新发现）？结果是否感觉合适（否 → 校准）？偏差属于哪个维度（视觉设计 / UX 流程 / API 表面 / 数据模型 / 范围方向 / 文案语气 / 性能质量）？

根据维度的权重进行路由——轻重划分以 /aep-map 中的 references/alignment-layers.md 为准：

• 重型维度：在下一个 .5 对齐层中创建故事，并设置 calibration_type: <dimension>；分派前运行 /aep-calibrate <dimension>。
• 轻型维度：直接路由到 /aep-calibrate <dimension>——它可以在下一个整数层中创建故事，或直接更新产品上下文。无需 .5 层。

新发现

出现新需求或某项假设失效。

• 操作： 重新审视产品上下文。若是产品假设，则通过 /aep-envision 更新 product 部分（将受影响的假设标记为已修订）。若是架构问题，则通过 /aep-map 更新 architecture 部分。

机会转变

根本性地改变了当前选择——原本的机会假设有误或已经发生变化。

• 操作： 返回 /aep-envision 的阶段 0。迹象：你要解决的问题并非用户实际遇到的问题，或市场变化使这一机会不再成立。

流程

关于工作流本身而非产品的观察（权限阻滞、信号过时、缺少工具、Agent 配置缺口）。

• 操作： 在 lessons-learned/process/<observation>.md 中记录这一模式（发生了什么——描述、频率、影响；已知时注明根本原因；拟议的缓解措施）。在 product-context.yaml 的 topology.routing 中添加一条 process_learnings 记录（pattern、mitigation、discovered_at）。
• 技能修订： 如果这一模式需要修改技能文件，则将其记录为 changelog 中的一项拟议修订——包含 type: process-improvement、summary 和 proposed_changes（skill、change、rationale）。技能文件由人工审核并应用；分类器只提出修订建议，不编辑技能文件。
• 上游路由： 若要系统性地收集多次下游运行中的流程和技术栈观察，请使用 /aep-workflow-feedback（标准化格式 + 下游→AEP 路由）。

后置条件： 每条观察都必须带有且仅带有一个经用户确认的类别，并记录其路由操作——向 stories 添加故事、将 product/architecture 更新列入待办，或写入 process_learnings/修订记录。

---

第 2.5 步：重新划分地图

对所有反馈完成分类后，检查当前的层级分配。发布线只是铅笔标记——会根据你学到的内容调整。

对于尚未构建的每一层：根据已分类的反馈检查故事优先级；当新的认知表明某些故事需要更早交付时，将其提升到较早的层；将不再那么关键的故事降级；将已分类的改进项中的新故事添加到合适的层；更新 product-context.yaml 中 stories 部分的 layer 分配。

关键规则： 重新划分不需要返回 /aep-envision——只有当主干（用户活动）或产品定位发生变化时，才需要转到那里；层级分配变动时则不需要。完整框架请参阅 docs/decisions/release-line-adjustments.md。

后置条件： stories 中的 layer 分配反映已分类的反馈（如果没有内容调整，则保持不变）。

---

第 2.75 步：评估结果契约

如果已完成的层在 product.layers[] 中定义了 outcome_contract：

1. 向用户说明假设：“假设是：[hypothesis]。成功指标是：[type] [target]。”
2. 请求评估——结果契约不是自动化测试；可能需要用户测试、分析审查或定性评估。
3. **应用决策规则：**满足 keep_if 条件 → 记录为通过，进入下一层；触发 otherwise → 记录为失败，建议重新划分（提升后续层中的故事，并在需要时调整主干）。
4. 在 changelog 中记录结果——type: outcome_evaluation，summary 需注明通过/失败、指标、实际值和目标值。

自动评估（可选，需主动启用）： 当指标绑定遥测数据时，可以跳过暂停。topology.routing.auto_outcome_eval 的模式请参阅 references/telemetry-ingestion.md：quantitative 会运行 coverage_check 门禁（§1.5）；如果指标绑定了数据源，则会获取实际值并机械地应用 keep_if/otherwise；指标未绑定或获取失败时，则回退到人工暂停。定性指标仍会暂停——除非 topology.routing.full_auto: true，此时 Agent 会自行判断。默认设置（auto_outcome_eval: none、full_auto: false）会原样保留人在环中的暂停。

如果已完成的层没有结果契约，则跳过此步骤。

后置条件： 结果以通过或失败的状态记录在 changelog 中；或者，由于 product.layers[] 没有 outcome_contract，因此跳过了此步骤。

---

第 3 步：成本审查

结合 .dev-workflow/ 中的任何执行跟踪，审查 product-context.yaml 的 cost 部分：

• 哪些类型的故事一贯成本高昂？ 它们是否能通过更精准的上下文组装、更简单的拆分方式或不同的 Agent 角色获益？
• 重试集中在哪些地方？ 失败模式可能表明规格不明确或模块边界划分不当。
• Agent 拓扑是否高效？ 是否需要调整路由策略？

后置条件： 记录成本观察结果和任何拓扑调整建议，以供第 4 步使用（记入反思 changelog 条目的 cost_observations 和/或对 topology 进行编辑）——或者明确记录“本周期无”。

---

第 4 步：更新产品上下文

根据分类后的反馈，更新相应文件：运营变更（新故事、架构修订、拓扑、成本、变更日志）→ product-context.yaml；产品意图变更（机会变化、角色变更、目标、mvp_boundary、layers、activities）→ product/index.yaml（拆分模式）或 product-context.yaml（v1 模式）。

1. 按产品上下文架构追加一条 changelog 记录——包含 date、type: reflection、summary，以及一个 feedback 映射，其中包含 bugs（description、story_id）、refinements（description、story_id、target_layer）、discoveries（description、affected_section）和 opportunity_shifts（description），以及 cost_observations。

2. 更新 stories 部分，添加新故事（错误修复的 priority: high，改进则归入下一层）。

3. 如果假设发生变化，更新 product 部分（为变更添加版本号）。

4. 如果需要调整路由，更新 topology 部分。

5. 验证 YAML（完整检查清单和常见修复方法请参阅 references/yaml-guardrails.md）：

   npx js-yaml product-context.yaml > /dev/null && echo "YAML OK"
   

   提交前修复所有错误。

6. 按 /aep-git-ref 中的“Control-Plane Commits”进行提交（根据 /aep-git-ref 中的“Resolving $BASE”解析 $BASE）：

   git pull --ff-only origin "$BASE"
   git add product-context.yaml product/
   git commit -m "chore: reflect — classify feedback and update product context"
   git push origin "$BASE"
   

后置条件：npx js-yaml 输出了 YAML OK，且 git push 的退出码为 0。

---

第 5 步：决定下一步行动

根据复盘结果，推荐下一步：

反馈类型	下一步行动
仅有错误	将修复故事添加到 YAML → /aep-dispatch → /aep-design → /aep-build
改进	将下一层的故事添加到 YAML → /aep-dispatch → /aep-design → /aep-build
发现（产品）	使用 /aep-envision 更新假设
发现（架构）	使用 /aep-map 更新系统地图
机会变化	/aep-envision Phase 0（重新验证）
校准（重度）	创建 .5 对齐故事 → /aep-calibrate <dimension> → /aep-dispatch
校准（轻度）	/aep-calibrate <dimension>（内联）→ 故事可能会更新 → /aep-dispatch
一切正常	进入下一层或发布到生产环境

**后置条件：**向用户推荐表格中的下一步行动。