story-define

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Historia de usuario

Skill：用户故事（Historia de usuario）

Guía para crear o actualizar historias de usuario en el repo del producto.

Alcance de una US: El
README.md
es un documento funcional. Registra el valor para el usuario, los criterios de aceptación (subsecciones Reglas de negocio con ids
BR-XX
y Escenarios con ids
SC-XX
) y el estado de avance. El detalle de implementación (DTOs, endpoints, esquemas) va en
docs/specs/technical-docs/
o en tareas
TK-XXX
, nunca en la narrativa de la historia. Los documentos técnicos no son parte de la descripción funcional; pueden referenciarse únicamente para justificar criterios de INVEST o condiciones del DoR.

La plantilla canónica está en

assets/user-story-template.md

(léela antes de escribir cualquier US).

在产品仓库中创建或更新用户故事的指南。

用户故事（US）的范围：
README.md
是一份功能性文档，记录用户价值、验收标准（包含ID为
BR-XX
的「业务规则」子章节和ID为
SC-XX
的「场景」子章节）以及进度状态。实现细节（DTO、端点、Schema）需放在
docs/specs/technical-docs/
或任务
TK-XXX
中，绝不能放在用户故事的叙述内容里。技术文档不属于功能描述的一部分；仅可在证明INVEST准则或DoR条件时引用。

标准模板位于

assets/user-story-template.md

（编写任何用户故事前请先阅读）。

Subagente requerido

所需子代理

Este skill debe ejecutarse bajo el agente/subagente
docs-specialist
(

agents/docs-specialist.md

; en el proyecto destino instalar como

.cursor/agents/docs-specialist.md

). No ejecutar el flujo normativo de la US sin ese contexto.

此Skill必须在
docs-specialist
代理/子代理（

agents/docs-specialist.md

；在目标项目中需安装为

.cursor/agents/docs-specialist.md

）下执行。若无该上下文，请勿执行用户故事的常规流程。

Cómo preguntar al usuario

如何向用户提问

Cuando este skill indique preguntar, pedir, confirmar, validar o sugerir algo al usuario, hacerlo mediante la herramienta de preguntas estructuradas que ofrezca el cliente (la que renderiza opciones tappables o un selector de respuesta) en lugar de redactar la pregunta como prosa libre. Reglas:

Opciones cortas y mutuamente excluyentes (2–4 por pregunta) cuando la respuesta admita categorías; usar entrada libre solo si no hay forma razonable de enumerar opciones (p. ej. el texto del valor de negocio).
No repreguntar lo que ya está respondido en el contexto, en
```
.agents/MEMORY.md
```
o en el
```
README.md
```
que se está editando.
Recopilación inicial (antes de redactar): una sola tanda con hasta tres preguntas por bloque; agrupar huecos de información, no ir descubriendo turno a turno.
Confirmaciones de flujo (después de redactar o en cierre Draft): una pregunta por turno cuando sea posible; si hay más de tres lagunas, encadenar tandas como en el paso 5 del flujo de creación.
Fallback: si el cliente no expone esta herramienta, formular la pregunta en prosa con opciones enumeradas (1, 2, 3…). Cada sección posterior que diga preguntar al usuario, validar con el usuario o sugerir al usuario asume este mecanismo; no se vuelve a repetir.

当此Skill指示询问、请求、确认、验证或建议用户操作时，请使用客户提供的结构化提问工具（可渲染可点击选项或响应选择器），而非自由文本提问。规则如下：

当答案可分类时，提供简短且互斥的选项（每个问题2-4个）；仅当无法合理枚举选项时（例如业务价值文本），才使用自由输入。
不要重复提问已在上下文、
```
.agents/MEMORY.md
```
或正在编辑的
```
README.md
```
中已有答案的内容。
初始收集（编写前）：单次批量提问，每组最多3个问题；将信息缺口分组，不要逐个提问。
流程确认（编写后或草稿收尾时）：尽可能每次只提一个问题；若存在超过3个缺口，按创建流程的第5步分组提问。
备选方案：若客户未提供该工具，用自由文本列出选项（1、2、3…）提问。后续所有提及「询问用户」「与用户验证」或「向用户建议」的章节均默认遵循此机制，不再重复说明。

Resolución de idioma

语言解析规则

Orden canónico para el idioma de la US, criterios Gherkin, INVEST, DoR y texto natural del skill. Detenerse en el primer paso que aplique:

.agents/MEMORY.md
(raíz del repo) → línea
```
preferred language: <ISO 639-1>
```
(p. ej.
```
es
```
,
```
en
```
). Si no existe esa línea pero hay claves legacy (
```
language:
```
,
```
idioma:
```
,
```
Project language:
```
), usarlas solo como fallback al leer MEMORY antiguo.
Idioma del turno del usuario (mensaje actual).
Preguntar al usuario qué idioma prefiere y persistir la respuesta en
```
.agents/MEMORY.md
```
con
```
preferred language: <código>
```
.

用户故事、Gherkin准则、INVEST、DoR以及Skill自然文本的规范语言优先级如下，按顺序匹配到第一个适用规则即停止：

.agents/MEMORY.md
（仓库根目录）→ 查找
```
preferred language: <ISO 639-1>
```
行（例如
```
es
```
、
```
en
```
）。若该行不存在但有旧版关键字（
```
language:
```
、
```
idioma:
```
、
```
Project language:
```
），仅在读取旧版MEMORY时作为备选使用。
用户当前对话的语言（当前消息）。
询问用户偏好的语言，并将答案保存到
```
.agents/MEMORY.md
```
中，格式为
```
preferred language: <代码>
```
。

Ubicación de archivos

文件位置

Artefacto	Ruta
Historia de usuario	`docs/specs/user-stories/US-XXX-[nombre-corto]/README.md`
Archivos de apoyo	`docs/specs/user-stories/US-XXX-[nombre-corto]/assets/`
Documentación técnica	`docs/specs/technical-docs/` (no parte de la descripción funcional; referenciable solo para justificar INVEST o DoR)
Glosario	`docs/specs/glossary.md` (opcional)

工件	路径
用户故事	`docs/specs/user-stories/US-XXX-[nombre-corto]/README.md`
辅助文件	`docs/specs/user-stories/US-XXX-[nombre-corto]/assets/`
技术文档	`docs/specs/technical-docs/` （不属于功能描述；仅可在证明INVEST或DoR时引用）
术语表	`docs/specs/glossary.md` （可选）

Convenciones del nombre de carpeta

文件夹命名规范

Formato:
```
US-XXX-[nombre-corto]
```
con
```
US-XXX
```
en mayúsculas y número de 3 dígitos.
Nombre corto: minúsculas, kebab-case, sin artículos ni palabras vacías.

Ejemplos:

US-001-seleccion-item-sdp-desde-receta

US-004-resumen-costos-receta

Archivos de apoyo en
```
assets/
```
; enlazarlos desde Referencias con rutas relativas, p. ej.
```
![Descripción](assets/nombre.png)
```
.

格式：
```
US-XXX-[nombre-corto]
```
，其中
```
US-XXX
```
为大写，数字为3位。
短名称：小写、kebab-case格式，无冠词或冗余词。

示例：

US-001-seleccion-item-sdp-desde-receta

、

US-004-resumen-costos-receta

。

辅助文件放在
```
assets/
```
中；从「参考资料」章节用相对路径链接，例如
```
![描述](assets/nombre.png)
```
。

Información requerida antes de redactar

编写前需收集的信息

Antes de crear o editar cualquier US, el agente debe tener clara la siguiente información. No inventar nada — si algún dato no es explícito, preguntar al usuario.

Dato	Cómo obtenerlo	Si no está disponible
Actor y valor de negocio	Del contexto o descripción del usuario	Preguntar al usuario
Criterios de aceptación (BR y SC)	Del contexto o descripción del usuario	Preguntar; sin al menos una `BR-XX` y un `SC-XX` INVEST no es valorable y la historia solo puede crearse en Draft
Idioma de preferencia	Ver Resolución de idioma	Preguntar y persistir en `.agents/MEMORY.md` con `preferred language: <código>`
Referencias de diseño (solo US de UI)	Figma, prototipos u otros enlaces aportados por el usuario	Sin ellas la historia no puede declararse Ready
Dependencias con otras US o sistemas	Indicadas por el usuario o inferibles del contexto	Preguntar; afectan las dimensiones I y E de INVEST
ID de la US	Proporcionado por el usuario	Inferir el siguiente libre revisando carpetas `US-` * en `docs/specs/user-stories/`
Unidades de trabajo	Proporcionadas por el usuario o inferibles del repo	Sin ellas la historia no puede declararse Ready

El único dato estrictamente obligatorio para crear la historia es tener identificado el actor y el valor de negocio. Si INVEST no es completamente valorable con la información disponible, la historia se crea con
Estado: Draft
y las lagunas documentadas en Observaciones. El estado Ready requiere todos los datos sin excepción.

创建或编辑任何用户故事前，代理必须明确以下信息。不得编造内容——若有数据不明确，需询问用户。

数据	获取方式	若不可用的处理方式
角色与业务价值	从用户上下文或描述中获取	询问用户
验收标准（BR和SC）	从用户上下文或描述中获取	询问用户；若无至少一个 `BR-XX` 和一个符合INVEST的 `SC-XX` ，则用户故事无法评估，仅能以「草稿（Draft）」状态创建
偏好语言	查看语言解析规则	询问用户并将答案保存到 `.agents/MEMORY.md` 中，格式为 `preferred language: <代码>`
设计参考（仅UI类用户故事）	用户提供的Figma、原型或其他链接	若无这些参考，用户故事无法标记为「就绪（Ready）」
与其他用户故事或系统的依赖关系	用户指明或从上下文推断	询问用户；这些依赖会影响INVEST的I和E维度
用户故事ID	用户提供	查看 `docs/specs/user-stories/` 下的 `US-*` 文件夹，推断下一个可用ID
工作单元	用户提供或从仓库中推断	若无这些信息，用户故事无法标记为「就绪（Ready）」

创建用户故事的唯一必填信息是明确角色和业务价值。若现有信息无法完全评估INVEST准则，则用户故事以「状态：草稿（Draft）」创建，并在「备注」中记录信息缺口。「就绪（Ready）」状态要求所有信息无遗漏。

Validación antes de crear

创建前的验证

Antes de crear archivos, verificar las siguientes condiciones. Si alguna falla, no crear — informar al usuario y resolver primero.

¿Qué verificar?

Duplicado de ID: si el usuario proporciona
```
US-XXX
```
, confirmar que esa carpeta no existe en
```
docs/specs/user-stories/
```
.
Solapamiento de alcance: revisar los títulos y descripciones de otras US para detectar si el actor + valor + alcance ya está cubierto por una historia existente.
INVEST parcialmente valorable: si la información recibida no permite valorar todas las dimensiones, la historia sí puede crearse pero con
```
Estado: Draft
```
y las lagunas documentadas en Observaciones. Solo es un bloqueante si el actor o el valor de negocio son completamente desconocidos. Si hay conflicto de ID o solapamiento de alcance:

⚠️ No es posible crear la historia todavía:
- <razón concreta>
- [US-XXX: Título](docs/specs/user-stories/US-XXX-nombre/README.md) — <razón del solapamiento, si aplica>

Sugerir al usuario: (a) ajustar el alcance, (b) actualizar la US existente, o (c) proporcionar la información faltante.

创建文件前，需验证以下条件。若任一条件不满足，请勿创建——告知用户并先解决问题。

需验证哪些内容？

ID重复：若用户提供
```
US-XXX
```
，确认
```
docs/specs/user-stories/
```
中不存在该文件夹。
范围重叠：查看其他用户故事的标题和描述，检测角色+价值+范围是否已被现有用户故事覆盖。
INVEST部分可评估：若收到的信息无法评估所有维度，用户故事仍可创建但需标记为「状态：草稿（Draft）」，并在「备注」中记录信息缺口。仅当角色或业务价值完全未知时，才禁止创建。 若存在ID冲突或范围重叠：

⚠️ 目前无法创建该用户故事：
- <具体原因>
- [US-XXX: 标题](docs/specs/user-stories/US-XXX-nombre/README.md) — <重叠原因（若适用）>

建议用户：(a) 调整范围，(b) 更新现有用户故事，或(c) 提供缺失的信息。

Flujo: Crear una historia nueva

流程：创建新用户故事

Fijar el ID y nombre de carpeta

Usar el
```
US-XXX
```
indicado por el usuario o inferir el siguiente libre listando carpetas
```
US-*
```
en
```
docs/specs/user-stories/
```
.
Proponer el
```
nombre-corto
```
en kebab-case; validar con el usuario si hay ambigüedad.
Crear la carpeta
```
US-XXX-[nombre-corto]/
```
y
```
assets/
```
si habrá archivos vinculados.

Escribir el
README.md
usando
```
assets/user-story-template.md
```
como molde:

Descripción: Como/Quiero/Para con modalidad normativa RFC 2119 (ver Notas — RFC 2119) en el idioma de preferencia.
Referencias: enlaces de diseño y archivos en
```
assets/
```
; los archivos aportados no deben quedar solo en el chat.
Criterios de aceptación (sección con dos subsecciones; ids solo
```
BR-XX
```
y
```
SC-XX
```
):
- Reglas de negocio: cada regla con id secuencial BR-01, BR-02, … y palabra clave normativa en MAYÚSCULAS (DEBE, NO DEBE, DEBERÍA, etc.). Los ids son únicos en el ámbito de la US; renumerar si se reordenan o eliminan reglas.
- Escenarios: cada escenario con id secuencial SC-01, SC-02, … en la línea
```
Escenario: SC-XX - <nombre>
```
  . Redactar en formato Gherkin con la palabra clave de cada paso en TODO MAYÚSCULAS en el idioma de preferencia (DADO / CUANDO / ENTONCES / Y / PERO en español; GIVEN / WHEN / THEN / AND / BUT en inglés). Los escenarios no deben contradecir ninguna obligación (DEBE) ni prohibición (NO DEBE) de las reglas de negocio.
Unidades de trabajo: al nivel de granularidad del repo (p. ej.
```
frontend
```
,
```
backend
```
, o
```
micro-autenticacion
```
,
```
micro-catalogo
```
).
Complejidad sugerida: story points solo en valores Fibonacci 1, 2, 3, 5, 8, 13 con justificación breve de alcance, riesgo e incertidumbre.
Validación — INVEST: tabla con las seis dimensiones (I, N, V, E, S, T); valor de cada una:
```
Cumple
```
/
```
No cumple
```
/
```
Parcial
```
con nota. Si alguna dimensión falla, documentarlo sin disimular.
Validación — Definition of Ready (DoR): tabla con los seis criterios de la plantilla. Para cada uno:
```
Cumple
```
/
```
No cumple
```
/
```
Parcial
```
(el criterio Referencias de UI admite además
```
No aplica
```
). Ver criterios exactos en el checklist de Ready.
Observaciones: (1) prerrequisitos o dependencias aún no listas; (2) datos o aclaraciones pendientes del usuario o producto; (3) decisiones pendientes; (4) otras notas. Si no hay nada que reportar en algún ítem, dejarlo vacío.

Documentación técnica (solo si el usuario la pide explícitamente)

Crear o actualizar documentos en
```
docs/specs/technical-docs/
```
.
No integrarla en la descripción funcional de la US. Solo puede referenciarse desde las secciones INVEST u Observaciones del DoR para justificar complejidad, dependencias o restricciones técnicas que condicionan algún criterio (p. ej. «Ver
technical-docs/contrato-api.md
— justifica la estimación de la dimensión E»).

Glosario (si aplica)

Si aparecen términos de dominio nuevos, crear o reutilizar entrada en
```
docs/specs/glossary.md
```
con definición breve en contexto producto/dominio.

Cierre

Si la US queda en Draft, identificar las lagunas documentadas en Observaciones (datos faltantes, dependencias sin confirmar, dimensiones de INVEST en
```
Parcial
```
o
```
No cumple
```
, criterios del DoR sin satisfacer) y ofrecer al usuario, mediante la herramienta de preguntas estructuradas, las preguntas concretas que cerrarían cada laguna. Reglas:
- Una pregunta por laguna, con opciones cuando la respuesta admita categorías (idioma, formato, prioridad, dependencias enumerables, story points Fibonacci); entrada libre solo para campos narrativos (refinamiento del valor, reglas nuevas, criterios verificables).
- Respetar el máximo de tres preguntas por bloque; si hay más lagunas, encadenar tandas hasta agotarlas o hasta que el usuario indique que prefiere mantener el resto como Draft.
- Tras recibir respuestas, actualizar las secciones afectadas del
```
README.md
```
  , revalidar los checklists de INVEST y DoR, y promover a
```
Estado: Ready
```
  solo si quedan completos. Si alguna laguna sigue abierta, mantener
```
Draft
```
  y reflejar el residual en Observaciones.
Si la US queda en Ready, sugerir explícitamente al usuario que ejecute
```
/story-plan
```
para crear las tareas
```
TK-XXX
```
.
Si el usuario pide crearlas en continuidad o en el mismo turno: invocar
/story-plan
obligatoriamente; no crear tareas directamente desde este skill. El conocimiento y las reglas de formato de los
```
TK-XXX
```
residen en ese skill.

确定ID和文件夹名称

使用用户指定的
```
US-XXX
```
，或列出
```
docs/specs/user-stories/
```
下的
```
US-*
```
文件夹，推断下一个可用ID。
建议使用kebab-case格式的
```
nombre-corto
```
；若存在歧义，需与用户确认。
创建
```
US-XXX-[nombre-corto]/
```
文件夹，若需关联文件则同时创建
```
assets/
```
文件夹。

使用
assets/user-story-template.md
作为模板编写
README.md
：

描述：采用「作为/想要/为了」结构，并遵循RFC 2119规范（查看备注 — RFC 2119），使用偏好语言。
参考资料：添加设计链接和
```
assets/
```
中的文件；用户提供的文件不得仅留在聊天中。
验收标准（包含两个子章节；ID仅可为
```
BR-XX
```
和
```
SC-XX
```
）：
- 业务规则：每条规则使用连续ID BR-01、BR-02…，并将规范关键字设为大写（DEBE、NO DEBE、DEBERÍA等）。ID在用户故事范围内唯一；若规则重新排序或删除，需重新编号。
- 场景：每个场景使用连续ID SC-01、SC-02…，格式为
```
Escenario: SC-XX - <名称>
```
  。采用Gherkin格式编写，每个步骤的关键字设为全大写，使用偏好语言（西班牙语为DADO / CUANDO / ENTONCES / Y / PERO；英语为GIVEN / WHEN / THEN / AND / BUT）。场景不得与业务规则中的任何强制要求（DEBE）或禁止项（NO DEBE）冲突。
工作单元：与仓库粒度一致（例如
```
frontend
```
、
```
backend
```
，或
```
micro-autenticacion
```
、
```
micro-catalogo
```
）。
建议复杂度：仅使用斐波那契数列值1、2、3、5、8、13作为故事点，并简要说明范围、风险和不确定性。
验证 — INVEST：包含六个维度（I、N、V、E、S、T）的表格；每个维度的取值为
```
符合
```
/
```
不符合
```
/
```
部分符合
```
，并附带说明。若任一维度不满足，需如实记录。
验证 — 就绪定义（DoR）：包含模板中六个准则的表格。每个准则的取值为
```
符合
```
/
```
不符合
```
/
```
部分符合
```
（「UI参考资料」准则还可选择
```
不适用
```
）。查看就绪检查清单中的具体准则。
备注：(1) 尚未就绪的前置条件或依赖；(2) 用户或产品团队待确认的数据或说明；(3) 待决策事项；(4) 其他说明。若某条目无内容，留空即可。

技术文档（仅当用户明确要求时）

创建或更新
```
docs/specs/technical-docs/
```
中的文档。
不得将技术文档整合到用户故事的功能描述中。仅可在INVEST章节或DoR的备注中引用，以说明复杂度、依赖或限制某些准则的技术条件（例如*«查看
```
technical-docs/contrato-api.md
```
— 证明E维度的估算合理性»*）。

术语表（若适用）

若出现新的领域术语，在
```
docs/specs/glossary.md
```
中创建或复用条目，并简要说明产品/领域上下文定义。

收尾

若用户故事处于草稿（Draft）状态，识别备注中记录的信息缺口（缺失数据、未确认依赖、INVEST维度为
部分符合
或
不符合
、DoR准则未满足），并通过结构化提问工具向用户提出具体问题以填补缺口。规则如下：
- 每个缺口对应一个问题；若答案可分类（语言、格式、优先级、可枚举依赖、斐波那契故事点），提供选项；仅叙事性字段（价值细化、新规则、可验证准则）使用自由输入。
- 每组最多3个问题；若缺口超过3个，分组提问直至所有缺口覆盖或用户表示希望保持草稿状态。
- 收到答案后，更新
```
README.md
```
  的相关章节，重新验证INVEST和DoR检查清单；仅当所有检查清单完成时，才升级为「状态：就绪（Ready）」。若仍有缺口未填补，保持「草稿（Draft）」状态并在备注中记录剩余缺口。
若用户故事处于**就绪（Ready）**状态，明确建议用户执行
```
/story-plan
```
以创建
```
TK-XXX
```
任务。
若用户要求在当前对话中连续创建任务：必须调用
/story-plan
；不得直接从此Skill创建任务。
```
TK-XXX
```
的创建逻辑和格式规则由该Skill负责。

Flujo: Actualizar una historia existente

流程：更新现有用户故事

Identificar el archivo — por ID, nombre-corto o título.
Leer el
README.md
actual completo antes de editar.
Aplicar los cambios solicitados por el usuario. Reglas invariantes:

Si el cambio afecta reglas de negocio: mantener los ids
```
BR-XX
```
existentes; renumerar solo si se reordenan o eliminan reglas.
Si el cambio afecta escenarios: mantener los ids
```
SC-XX
```
existentes; renumerar solo si se reordenan o eliminan escenarios.
Si hay conflicto entre el texto de un
```
TK-XXX
```
y el
```
README.md
```
de la US: la US prevalece. Corregir las tareas, no la historia.
Si el usuario cambia el estado a Ready: verificar todas las condiciones del checklist de Ready antes de guardar.

Criterios de aceptación: si se añaden o modifican, aplicar las mismas reglas de formato del flujo de creación (paso 2).
Si la US queda en
Estado: Draft
tras los cambios (sea porque ya lo estaba, sea porque los cambios la degradaron desde Ready), ofrecer al usuario las preguntas que cerrarían las lagunas residuales mediante la herramienta de preguntas estructuradas, aplicando las mismas reglas del paso 5 del flujo de creación (una pregunta por laguna, opciones cuando la respuesta admita categorías, máximo tres por bloque, encadenar tandas si hace falta). Si las respuestas completan los checklists de INVEST y DoR, promover a
```
Estado: Ready
```
. Si el usuario prefiere mantener Draft o salta preguntas, respetarlo y reflejar el residual en Observaciones.
Confirmar mostrando las secciones modificadas.

定位文件 — 通过ID、短名称或标题查找。
编辑前完整阅读当前
README.md
。
应用用户请求的变更。不变规则：

若变更涉及业务规则：保留现有
```
BR-XX
```
ID；仅当规则重新排序或删除时，才重新编号。
若变更涉及场景：保留现有
```
SC-XX
```
ID；仅当场景重新排序或删除时，才重新编号。
若
```
TK-XXX
```
任务文本与用户故事
```
README.md
```
冲突：用户故事优先级更高。需修正任务，而非修改用户故事。
若用户将状态改为就绪（Ready）：保存前需验证就绪检查清单的所有条件。

验收标准：若添加或修改验收标准，需遵循创建流程第2步的相同格式规则。
若变更后用户故事处于「状态：草稿（Draft）」（无论是原本就是草稿，还是变更后从就绪状态降级），通过结构化提问工具向用户提出填补剩余缺口的问题，遵循创建流程第5步的相同规则（每个缺口对应一个问题，答案可分类时提供选项，每组最多3个问题，必要时分组提问）。若答案完成INVEST和DoR检查清单，升级为「状态：就绪（Ready）」。若用户希望保持草稿或跳过某些问题，需尊重用户选择并在备注中记录剩余缺口。
确认 — 展示修改的章节。

Checklist antes de redactar

编写前检查清单

Información:

Actor y valor de negocio claros
Reglas de negocio con suficiente detalle para valorar INVEST
Idioma de preferencia determinado y
```
.agents/MEMORY.md
```
actualizado si fue necesario
Si es US de UI: referencias de diseño presentes o acordadas
Dependencias con otras US o sistemas identificadas Validación:
ID
```
US-XXX
```
sin carpeta existente (creación) o carpeta identificada (actualización)
Sin solapamiento de alcance con US existentes
Actor y valor de negocio identificados (mínimo para crear); si INVEST no es completamente valorable →
```
Estado: Draft
```
con lagunas en Observaciones Condiciones para
Estado: Ready
:
Sección Criterios de aceptación completa: al menos una
```
BR-XX
```
y un
```
SC-XX
```
; escenarios en Gherkin con palabras clave en MAYÚSCULAS y en el idioma de preferencia del documento
DoR completado según la plantilla
Unidades de trabajo identificadas
Observaciones sin aclaraciones ni pendientes abiertos Formato:
Plantilla
```
assets/user-story-template.md
```
leída
Reglas de negocio con identificadores
```
BR-01
```
,
```
BR-02
```
, … sin saltos; escenarios con
```
SC-01
```
,
```
SC-02
```
, … sin saltos
Palabras clave normativas en MAYÚSCULAS en el idioma de preferencia (DEBE, NO DEBE, DEBERÍA…)
Archivos del usuario guardados en
```
assets/
```
y enlazados con ruta relativa
Detalle técnico en
```
technical-docs/
```
o
```
TK-XXX
```
, no en el
```
README.md
```

信息：

角色和业务价值明确
业务规则足够详细，可评估INVEST
已确定偏好语言，必要时已更新
```
.agents/MEMORY.md
```
若为UI类用户故事：已提供或确认设计参考
已识别与其他用户故事或系统的依赖关系 验证：
```
US-XXX
```
ID无对应文件夹（创建场景）或已定位对应文件夹（更新场景）
与现有用户故事无范围重叠
已识别角色和业务价值（创建的最低要求）；若无法完全评估INVEST → 「状态：草稿（Draft）」并在备注中记录信息缺口 「就绪（Ready）」状态条件：
验收标准章节完整：至少包含一个
```
BR-XX
```
和一个
```
SC-XX
```
；场景采用Gherkin格式，关键字为全大写，使用文档偏好语言
已按模板完成DoR检查
已识别工作单元
备注中无待确认或未解决的事项 格式：
已阅读
```
assets/user-story-template.md
```
模板
业务规则使用连续ID
```
BR-01
```
、
```
BR-02
```
…无间隔；场景使用连续ID
```
SC-01
```
、
```
SC-02
```
…无间隔
规范关键字为偏好语言的全大写（DEBE、NO DEBE、DEBERÍA…）
用户提供的文件已保存到
```
assets/
```
中，并使用相对路径链接
技术细节放在
```
technical-docs/
```
或
```
TK-XXX
```
中，而非
```
README.md
```

Ejemplos

示例

Ejemplo 1 — Entrada mínima viable

Entrada: «US nueva: como farmacéutico quiero ver alertas de interacción al añadir un medicamento a la receta, para evitar recetas inseguras. Reglas: mostrar alerta antes de guardar; permitir continuar con justificación.»
Salida: Carpeta
```
US-0XX-alertas-interaccion-receta/
```
con
```
README.md
```
completo (Como/Quiero/Para, BR-01 y BR-02 con modalidad RFC 2119, SC-01 y SC-02 en Gherkin con caso feliz y excepción, INVEST y DoR completados, story points con justificación).

Ejemplo 2 — Falta información

Entrada: «Historia de exportar informes.»
Comportamiento: El agente no crea carpetas; lanza una tanda de preguntas mediante la herramienta de preguntas estructuradas (quién exporta, formatos admitidos, permisos, qué se entiende por "informe", criterios verificables) con opciones cuando aplique. Solo procede a redactar cuando puede valorar INVEST y escribir Gherkin.

Ejemplo 3 — Historia con UI

Entrada: Historia con enlace a Figma y capturas en
```
assets/
```
.
Salida:
```
README.md
```
con sección Referencias completa; fila Referencias de UI en DoR en
```
Cumple
```
o
```
Parcial
```
con notas;
```
Estado: Ready
```
solo si Gherkin y DoR lo permiten.

Ejemplo 4 — Ready y tareas

Entrada: Historia cerrada en Ready; el usuario dice: «crea las tareas para implementarla».
Salida: El agente no crea tareas directamente; invoca
```
/story-plan
```
pasando el contexto de la US. Toda la lógica de creación de
```
TK-XXX
```
(stubs, plantilla, work-units) es responsabilidad de ese skill.

Ejemplo 5 — Draft con cierre asistido

Entrada: «US nueva: como analista quiero descargar el reporte mensual de ventas en CSV para procesarlo localmente.» Hay actor y valor, pero no se conocen story points, dependencias ni si existen referencias de UI.
Comportamiento: El agente crea
```
US-0XX-descarga-reporte-mensual-csv/
```
con
```
Estado: Draft
```
, documenta las lagunas en Observaciones, y en el cierre lanza una tanda de preguntas estructuradas:
- "¿Story points (Fibonacci)?" → opciones
```
1
```
  /
```
2
```
  /
```
3
```
  /
```
5
```
  (con
```
8
```
  /
```
13
```
  accesibles si pide más).
- "¿Hay dependencias con otra US o sistema?" → opciones
```
Ninguna
```
  /
```
Otra US del backlog
```
  /
```
Sistema externo
```
  .
- "¿La historia involucra UI propia?" → opciones
```
Sí, tengo Figma
```
  /
```
Sí, sin referencias aún
```
  /
```
No, solo backend
```
  .
Resultado: Con las respuestas, el agente actualiza el
```
README.md
```
, revalida INVEST y DoR, y promueve a
```
Estado: Ready
```
si los checklists quedan completos. Si el usuario salta una pregunta o queda residual, la US permanece en Draft con la nota correspondiente.

示例1 — 最小可行输入

输入: «新用户故事：作为药剂师，我希望在向处方添加药物时看到相互作用警报，以避免不安全的处方。规则：保存前显示警报；允许提供理由后继续。»
输出: 创建
```
US-0XX-alertas-interaccion-receta/
```
文件夹，包含完整的
```
README.md
```
（「作为/想要/为了」结构、符合RFC 2119规范的BR-01和BR-02、包含正常流程和异常流程的Gherkin格式SC-01和SC-02、已完成的INVEST和DoR检查、带说明的故事点）。

示例2 — 信息缺失

输入: «导出报告的用户故事。»
行为: 代理不创建文件夹；通过结构化提问工具批量提问（谁导出、支持的格式、权限、「报告」的定义、可验证准则），适用时提供选项。仅当可评估INVEST并编写Gherkin场景时，才开始编写。

示例3 — UI类用户故事

输入: 包含Figma链接和
```
assets/
```
中截图的用户故事。
输出:
```
README.md
```
的「参考资料」章节完整；DoR中的「UI参考资料」行标记为
```
符合
```
或
```
部分符合
```
并附带说明；仅当Gherkin和DoR满足条件时，才标记为「状态：就绪（Ready）」。

示例4 — 就绪状态与任务

输入: 用户故事已标记为就绪；用户说：«创建实现该故事的任务。»
输出: 代理不直接创建任务；调用
```
/story-plan
```
并传递用户故事上下文。所有
```
TK-XXX
```
任务的创建逻辑（存根、模板、工作单元）均由该Skill负责。

示例5 — 带辅助收尾的草稿

输入: «新用户故事：作为分析师，我希望以CSV格式下载月度销售报告，以便本地处理。» 已明确角色和价值，但未知故事点、依赖关系以及是否存在UI参考。
行为: 代理创建
```
US-0XX-descarga-reporte-mensual-csv/
```
文件夹，标记为「状态：草稿（Draft）」，在备注中记录信息缺口，并在收尾时通过结构化提问工具批量提问：
- «故事点（斐波那契数列）？» → 选项
```
1
```
  /
```
2
```
  /
```
3
```
  /
```
5
```
  （若用户需要可提供
```
8
```
  /
```
13
```
  ）。
- «是否依赖其他用户故事或系统？» → 选项
```
无
```
  /
```
待办列表中的其他用户故事
```
  /
```
外部系统
```
  。
- «该用户故事涉及自有UI吗？» → 选项
```
是，我有Figma
```
  /
```
是，尚无参考
```
  /
```
否，仅后端
```
  。
结果: 根据答案，代理更新
```
README.md
```
，重新验证INVEST和DoR检查清单；若检查清单完成，升级为「状态：就绪（Ready）」。若用户跳过某个问题或仍有剩余缺口，用户故事保持草稿状态并记录对应备注。

Anti-patterns

反模式

Inventar reglas de negocio o exclusiones que el usuario no dio.
Poner detalle técnico (clases, endpoints, esquemas) en el
```
README.md
```
en lugar de remitirlo a
```
technical-docs/
```
o
```
TK-XXX
```
.
Declarar
```
Estado: Ready
```
sin Criterios de aceptación completo o sin referencias de diseño cuando la historia involucra UI.
Declarar
```
Estado: Ready
```
con Observaciones que aún listen aclaraciones o pendientes sin resolver.
Resolver un conflicto entre
```
TK-XXX
```
y el
```
README.md
```
de la US degradando la US; la US prevalece.
Crear tareas
```
TK-XXX
```
directamente desde este skill sin invocar
```
/story-plan
```
; la creación de tareas siempre se delega a ese skill.
Copiar
```
assets/user-story-template.md
```
al repo del producto como artefacto en lugar de usarlo como molde.
Lanzar preguntas al usuario como prosa libre cuando el cliente expone una herramienta de preguntas estructuradas; o ir descubriendo huecos turno a turno en lugar de agrupar todas las preguntas pendientes en una sola tanda al inicio.

编造用户未提及的业务规则或例外情况。
将技术细节（类、端点、Schema）放在
```
README.md
```
中，而非指向
```
technical-docs/
```
或
```
TK-XXX
```
。
当用户故事涉及UI时，未完成验收标准或无设计参考就标记为「状态：就绪（Ready）」。
备注中仍有待确认或未解决事项时，标记为「状态：就绪（Ready）」。
解决
```
TK-XXX
```
任务与用户故事
```
README.md
```
的冲突时，降级用户故事；用户故事优先级更高。
不调用
```
/story-plan
```
直接从此Skill创建
```
TK-XXX
```
任务；任务创建必须委托给该Skill。
将
```
assets/user-story-template.md
```
复制到产品仓库作为工件，而非用作模板。
当客户提供结构化提问工具时，仍用自由文本提问；或不将所有信息缺口分组批量提问，而是逐个提问。

Notas

备注

Handoffs del ciclo

流程交接

Posición: inicio del pipeline

story-define

→

story-plan

→

story-implement

→

story-integrate


Entrada	Necesidad funcional del usuario. No requiere US previa.
Salida mínima (creación)	Carpeta `US-XXX-[nombre-corto]/README.md` con actor y valor de negocio; puede quedar en `Estado: Draft` con lagunas en Observaciones.
Salida para continuar	`Estado: Ready` en el `README.md` ; INVEST y DoR completos; al menos un `BR-XX` y un `SC-XX` ; Observaciones sin pendientes abiertos.
Siguiente paso	`story-plan` — invocar `/story-plan` (o continuidad explícita del usuario). No crear `TK-XXX` desde este skill.
Si queda en Draft	No handoff a plan ni implement. Cerrar lagunas con preguntas estructuradas o mantener Draft documentado.
Regreso desde plan	Conflicto US ↔ TK detectado en `story-plan` → actualizar la US aquí; `story-plan` corrige el TK. La US prevalece sobre el TK.
Regreso desde integrate	Alcance reducido o `progress.md` incompleto detectado en `story-integrate` → ajustar la US aquí y alinear TKs con `story-plan` antes de reintentar el merge.

位置：

story-define

→

story-plan

→

story-implement

→

story-integrate

pipeline的起始阶段。


输入	用户的功能需求。无需预先存在用户故事。
最小输出（创建场景）	`US-XXX-[nombre-corto]/README.md` 文件夹，包含角色和业务价值；可标记为「状态：草稿（Draft）」并在备注中记录信息缺口。
可继续流程的输出	`README.md` 中标记为「状态：就绪（Ready）」；INVEST和DoR检查完成；至少包含一个 `BR-XX` 和一个 `SC-XX` ；备注中无未解决事项。
下一步	`story-plan` — 调用 `/story-plan` （或用户明确要求连续执行）。不得从此Skill创建 `TK-XXX` 任务。
若处于草稿状态	不交接至计划或实现阶段。通过结构化提问填补缺口，或保持已记录的草稿状态。
从计划阶段返回	`story-plan` 中检测到用户故事与任务冲突 → 在此处更新用户故事； `story-plan` 修正任务。用户故事优先级高于任务。
从集成阶段返回	`story-integrate` 中检测到范围缩小或 `progress.md` 不完整 → 在此处调整用户故事，并通过 `story-plan` 对齐任务后再尝试合并。

RFC 2119

Tabla de equivalencias para palabras clave normativas (en MAYÚSCULAS en el idioma de preferencia):

Nivel (semántica RFC 2119)	Inglés ( `en` )	Español ( `es` )
Obligación absoluta	MUST / REQUIRED	DEBE / ES OBLIGATORIO
Prohibición absoluta	MUST NOT / SHALL NOT	NO DEBE / ESTÁ PROHIBIDO
Recomendación fuerte	SHOULD / RECOMMENDED	DEBERÍA / ES RECOMENDABLE
Desaconsejado salvo causa	SHOULD NOT	NO DEBERÍA / NO ES RECOMENDABLE
Permiso u opcionalidad	MAY / OPTIONAL	PUEDE / OPCIONAL

Elegir una forma por nivel y mantenerla consistente en toda la US. Si el usuario pide no usar RFC 2119, documentarlo en Observaciones; el formato Gherkin en MAYÚSCULAS se mantiene salvo petición explícita en contra.

规范关键字的对应表（在偏好语言中为全大写）：

级别（RFC 2119语义）	英语（ `en` ）	西班牙语（ `es` ）
绝对强制	MUST / REQUIRED	DEBE / ES OBLIGATORIO
绝对禁止	MUST NOT / SHALL NOT	NO DEBE / ESTÁ PROHIBIDO
强烈推荐	SHOULD / RECOMMENDED	DEBERÍA / ES RECOMENDABLE
不推荐（除非特殊原因）	SHOULD NOT	NO DEBERÍA / NO ES RECOMENDABLE
允许或可选	MAY / OPTIONAL	PUEDE / OPCIONAL

每个级别选择一种表述，并在整个用户故事中保持一致。若用户要求不使用RFC 2119，需在备注中记录；除非用户明确要求，否则Gherkin格式的全大写关键字需保留。