aep-calibrate

校准

人类对齐检查点。Agent 会按规格构建，但规格是对人类意图的有损压缩。这项技能会暂停执行，让人类检查已构建的内容，并以 Agent 可使用的格式记录“正确”究竟意味着什么。

适用场景：

/aep-reflect (identified alignment gap)
  → /aep-calibrate           (Phase 1: generate dimension-specific brief)
  → human explores       (method varies by type — external tools, conversation, code review)
  → /aep-calibrate capture   (Phase 2: capture decisions into artifact)
  → /aep-dispatch            (stories dispatched with calibration context)

会话： Main，与用户交互 输入： 校准类型 + 来自 product/index.yaml（拆分模式）或 product-context.yaml（v1 模式）的产品定义 + 来自 product-context.yaml 的运行状态 输出： 校准产物（独立或内嵌）+ 更新后的 calibration.history

---

类型检测

检查此技能的调用方式，以确定校准维度：

路径 A — 显式指定： 用户输入 /aep-calibrate visual-design 或 /aep-calibrate api-surface。类型已直接给出。

路径 B — 由 /aep-reflect 路由： 反思过程将某项观察归类为具有特定维度的校准需求。维度和观察文本会作为上下文传入。

路径 C — 上下文推断： 用户输入 /aep-calibrate，但未指定类型。确定类型：

1. 检查 product-context.yaml 中的 calibration.plan（运行文件）——当前层的下一个维度是什么？
2. 检查当前 .5 层中设置了 calibration_type 的故事。
3. 如果两者都不适用，则询问用户：“你觉得哪里不对劲？（视觉设计 / UX 流程 / API 表面 / 数据模型 / 范围方向 / 文案语气 / 性能质量）”

后置条件： 已选定 7 个维度之一。

---

文件解析

ls product/index.yaml 2>/dev/null && echo "SPLIT MODE" || echo "V1 MODE"
cat product-context.yaml

模式语义以 references/file-resolution.md 为准。在拆分模式下，从 product/index.yaml 读取产品定义（quality_dimensions、layers、activities、constraints、success_criteria、failure_model）；在 v1 模式下，从 product-context.yaml 读取。始终从 product-context.yaml 读取运行状态（calibration.plan、calibration.history、stories、architecture）。各类型的写入目标见 references/calibration-types.md（Write Targets）。

---

模式检测

确定类型后，检查是否已有校准记录：

• 建立模式：calibration.history 中没有该维度的既往记录 → 完整简报，从头创建产物。
• 扩展模式：已有既往记录 → 提供增量简报，仅涵盖现有校准中没有的新增模式/决策。

---

校准类型

每个维度都是重型或轻型（划分以 /aep-map 中的 references/alignment-layers.md 为准）——这决定了 Phase 1 的交接方式：

• 重型：借助 Agent 工作流之外的工具进行外部探索，创建独立的 calibration/<type>.yaml 产物，以及（通常）.5 对齐层故事。Phase 1 到此结束并进行交接。
• 轻型：通过对话问答，直接更新产品上下文。Phase 1 随即进入 Phase 2。

各维度的简报模板、探索方法、扫描目标和写入目标见 references/calibration-types.md——选择维度或扫描当前状态时请加载此文件。对于 ux-flow / visual-design，先运行 /aep-design-lens，可用基于理论且按严重程度评分的健康检查（证据）为简报提供初始内容，calibrate 会将其转化为人类的决策。

---

Phase 1：生成简报

Step 1：读取产品上下文

cat product-context.yaml

提取：

• opportunity.bet + product.problem → 产品定位
• product.persona.description + product.persona.jtbd → 目标用户
• opportunity.why_now → 紧迫性/定位
• layer 与活动层匹配的 stories → 已构建或将要构建的内容范围
• product.constraints.required_stack + preferred_stack → 技术约束
• calibration.history → 该维度先前的校准决策（扩展模式）

步骤 2：扫描当前状态

根据此类型的扫描目标（见 references/calibration-types.md → Scan Targets），检查当前实现，例如：视觉设计检查 globals.css/components//routes/，API 表面检查 architecture.interfaces 和处理程序文件。

步骤 3：生成简报

使用 references/briefs/<type>.md 中针对该类型的模板。

• **建立模式：**生成包含所有章节的完整简报模板。
• **扩展模式：**阅读现有校准产物或产品上下文章节，然后生成一份聚焦简报，只涵盖当前层中新增的内容：“这是你当前已校准的系统。以下新增的[页面/端点/实体等]需要尚未涵盖的决策：[列表]。”

将简报写入 docs/calibration-brief.md，并将完整内容打印到终端。

后置条件：docs/calibration-brief.md 存在，且其内容已打印。

步骤 4：交接

重型校准（视觉设计、UX 流程、文案语气）：打印探索说明，然后停止——由人类在 Agent 能力范围之外进行外部探索。

Calibration brief written to: docs/calibration-brief.md

Next steps (you do these):

  1. [Type-specific exploration instructions]
  2. Explore variations, then pick a direction.
  3. Save reference files to docs/design-references/ (if applicable)
  4. When ready, come back and run:
     /aep-calibrate capture

对于视觉设计，指引人类查阅 references/vibe-design-tools.md 以获取工具指南。

**轻型校准（API 表面、数据模型、范围方向、性能质量）：**展示简报并直接进入阶段 2——简报用于引导对话，无需外部探索。

---

阶段 2：记录决策（/aep-calibrate capture）

步骤 1：交互式问答

逐个提出 references/capture/<type>.md 中的结构化问题。（重型示例：所选方向、调色板、用户旅程决策、语气。轻型示例：命名决策、实体/字段名称、范围缺口评估、延迟阈值。）

**后置条件：**已回答 references/capture/<type>.md 中的所有问题。

步骤 2：生成产物

重型校准：

• **建立模式：**根据问答答案，使用 references/schemas/<type>-schema.yaml 中的架构，从头创建 calibration/<type>.yaml，并填写所有章节。
• **扩展模式：**读取现有的 calibration/<type>.yaml，为新覆盖的模式添加条目，并更新 calibrated_at / calibrated_from_layer——扩展现有值，不要替换它们。

对于视觉设计，还需使用记录的调色板更新 globals.css：将值转换为 oklch，并将其作为 CSS 自定义属性写入 :root 和 .dark。建立模式会替换整个调色板；扩展模式只添加新的自定义属性。

**轻型校准：**更新此类型对应文件中的相关章节（见 references/calibration-types.md → Write Targets）——architecture.interfaces、architecture.domain_model、product.goals/mvp_boundary/layers，或 product.success_criteria/failure_model。

**后置条件：**所选决策已记录在现有架构字段中——对于重型校准，calibration/<type>.yaml 存在，且 direction.name/direction.description 中记录了所选方向，并已设置 calibrated_at；对于轻型校准，目标章节反映了相关决策。

步骤 3：更新校准历史

根据产品上下文架构，在 product-context.yaml 的 calibration.history 和 changelog 中各追加一条记录：

• calibration.history 条目——dimension、calibrated_at、calibrated_from_layer、mode（establishment|extension）、artifact_path（轻型校准时为 null）、sections_updated、summary。
• changelog 条目——date、type: calibration、author: human、summary、sections_changed。

步骤 4：提交

提交前验证 YAML（常见修复方法见 references/yaml-guardrails.md）：

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

提交前修复所有错误。然后提交并推送到 $BASE（根据 /aep-git-ref 中的“Resolving $BASE”解析 $BASE）：

git pull --ff-only origin "$BASE"
git add calibration/ product-context.yaml product/
git commit -m "feat: calibrate <dimension> — <brief summary>"
git push origin "$BASE"

后置条件：npx js-yaml 已打印 YAML OK，且 git push 以状态码 0 退出。