contextualizar-negocio

梳理业务背景（brownfield）

目标

用业务语言并提供证据，回答系统目前做什么、遵循哪些规则，以及各项内容的名称是什么。在 brownfield 项目中，没有 PRD 或 backlog：系统的行为写在代码里，而许多规则在其他地方都没有记录。

此 skill 涵盖功能背景（第 3、4 层）。技术背景由 ARCH 使用 contextualizar-repo 生成。

**此 skill 不修改代码，也不提出新功能。**它负责收集信息、记录文档、提出问题，然后停止。

原则

1. **使用业务语言。**每项能力和规则都要以 PO 能理解的方式描述；技术证据要附在旁边，而不是代替说明。
2. **凡事都要有证据。**每项能力和规则都要注明来源（endpoint、屏幕、测试或 archivo:línea），否则标记为 NO VERIFICADO。
3. **代码的实际行为不一定符合业务期望。**如果某项规则看起来像错误或含义模糊，不要修正或自行解读；将其转化为业务问题。

输入

• ARCH 提供的 docs/contexto/ARQUITECTURA.md（或通知 CONTEXTO TÉCNICO LISTO）：指出应查看的位置。如果不存在，询问 ARCH 是否会先运行；只有在人类确认后才能在没有它的情况下继续，并告知收集过程会更慢、准确度也会更低。
• 如有现成的用户文档。
• 可选：正在运行的应用，以便浏览各个屏幕。

工作流

1. 来源

按以下顺序查看描述系统行为的内容：

1. **公共接口：**API endpoints、屏幕、命令。
2. **现有测试：**通过具体示例描述预期行为。
3. **配置：**会改变用户所见行为的选项和 flags。
4. 用户文档。
5. 代码，用于确认，并查找以上来源中没有体现的内容。

2. 能力地图（第 3 层）

按业务能力分组，而不是按文件或 endpoint 分组。每项能力记录：

• 允许用户执行什么操作，用一句业务语言描述；
• 使用者（角色）；
• 证据（endpoint、屏幕、测试或 archivo:línea）；
• 状态：启用 · 受配置选项控制 · 已弃用。

使用 assets/capacidades-template.md。

3. 隐藏的业务规则（第 3 层）

在代码中查找影响用户操作的校验、限制、转换、权限和默认值。每项规则记录：

• 用业务语言描述（“文档创建时不能超过 100,000 个字符”）；
• 证据 archivo:línea；
• 是否在其他地方有文档记录（是 / 否）；
• 如果含义模糊或看起来像错误：作为业务问题提出，不要自行解决。

4. 术语表（第 4 层）

使用 assets/glosario-template.md 创建 docs/contexto/GLOSARIO.md：

1. 汇总界面、API 和代码中出现的领域术语。
2. 每个术语都要记录：业务定义、同义词，以及不同情况下代码使用的名称；如果有标识符格式，也要一并记录。
3. **“Dónde vive”**列由 ARCH 填写：向其发送 GLOSARIO: TÉRMINOS NUEVOS: <ruta> — <cantidad de términos>。 如果本次会话中没有 ARCH，则根据证据填写，并标记为 pendiente de revisión técnica。
4. 如果同一个术语在不同地方含义不同，应记录为冲突，而不是选定一个定义。

5. 编写文档

文件	内容
docs/contexto/CAPACIDADES.md	能力地图 + 业务规则 + 业务问题
docs/contexto/GLOSARIO.md	业务 ↔ 代码术语表

如果 AGENTS.md 已指向这些文件（由 ARCH 留下），则不要修改。如果没有，则建议添加链接。

6. 自我验证

• 重新打开每份引用的证据，并确认其支持所述内容。
• 确认没有任何能力或规则被写成全新内容或提案。
• 确认词汇表中的每个术语都有业务定义。

7. 人工关卡

提交摘要和业务问题，最好交给 PO。等待明确批准后，才能将功能上下文标记为完成。

与 ARCH 协调

• 等待 CONTEXTO TÉCNICO LISTO 后再开始（除非人工另有指示）。
• 出现代码中没有对应位置的术语时，发送 GLOSARIO: TÉRMINOS NUEVOS。
• 收到 GLOSARIO COMPLETO 后，检查每个位置是否与业务定义相符；如不符，指出具体差异。
• 同一分歧最多沟通两轮；之后由人工决定。

约束

• 不修改 ARCH 的代码或技术文档。
• 不提出新功能：只记录现有功能。
• 不解决含糊的规则：只提出问题。
• 未经人工批准，不将功能上下文标记为完成。