story-integrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Integración de historia de usuario

Skill：用户故事集成

Guía para cerrar e integrar el trabajo de una historia de usuario

US-XXX

: verificar que la carpeta de la US tenga su

progress.md

con todas las tareas en

Done

, y luego hacer merge de la rama actual hacia la rama desde la que se creó.

Alcance del submit: El skill cierra localmente lo ya implementado. Verifica condiciones y ejecuta
git merge --no-ff
. No hace push, no borra ramas, no crea MRs/PRs, no resuelve conflictos, no modifica
progress.md
. Lo que no esté en
Done
bloquea el merge — el usuario decide cómo proceder, nunca se fuerza.

Encaja al final del ciclo iniciado por story-define → story-plan → story-implement. Ver Handoffs del ciclo.

关闭并集成用户故事

US-XXX

工作内容的指南：验证该用户故事的文件夹中

progress.md

内的所有任务均处于

Done

状态，然后将当前分支合并到其创建来源的分支。

提交范围说明：该Skill仅在本地关闭已完成的工作内容。它会验证条件并执行
git merge --no-ff
命令。不会执行push操作、删除分支、创建MR/PR、解决冲突或修改
progress.md
。任何未处于
Done
状态的任务都会阻止合并——由用户决定后续操作，绝不强制执行。

该Skill适用于story-define → story-plan → story-implement流程的收尾阶段。详见流程交接。

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:

Una pregunta por turno cuando sea posible; máximo tres preguntas en un mismo bloque.
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.
No repreguntar lo que ya está respondido en el contexto, en
```
.agents/MEMORY.md
```
o en
```
progress.md
```
de la US.
Una sola tanda al inicio para resolver lagunas antes de cualquier operación git (US asociada a la rama, carpeta ambigua, rama base); no ir descubriendo huecos turno a turno. Rama base ambigua: listar los candidatos detectados como opciones tappables (p. ej.
```
develop
```
,
```
main
```
,
```
release/2026.q2
```
); no proponer un default implícito.
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, confirmar o sugerir al usuario asume este mecanismo; no se vuelve a repetir.

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

尽可能一次只提一个问题；同一模块中最多提三个问题。
当答案可分类时，提供简短且互斥的选项（每个问题2-4个选项）；仅当无法合理枚举选项时，才使用自由输入。
不要重复询问上下文、
```
.agents/MEMORY.md
```
或用户故事的
```
progress.md
```
中已明确的内容。
在执行任何Git操作前，一次性解决所有信息缺口（如分支关联的用户故事、模糊的文件夹、基础分支）；不要逐次发现问题。基础分支模糊时：将检测到的候选分支列为可点击选项（例如
```
develop
```
、
```
main
```
、
```
release/2026.q2
```
）；不要默认推荐某一分支。
备选方案：若客户未提供该结构化工具，则用自由文本列出选项（1、2、3…）进行提问。

后续所有标注询问用户、与用户验证、确认或向用户建议的章节均默认遵循此机制，不再重复说明。

Resolución de idioma

语言解析规则

Orden canónico compartido con el resto del ciclo de historias. 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>
```
.

与其他用户故事流程共享标准优先级。按以下顺序执行，找到适用项后停止：

.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
Carpeta de la US	`docs/specs/user-stories/US-XXX-[nombre-corto]/`
Progreso de la US	`docs/specs/user-stories/US-XXX-[nombre-corto]/progress.md`
Tareas referenciadas	`docs/specs/user-stories/US-XXX-[nombre-corto]/TK-XXX-[kebab-case].md`

工件	路径
用户故事文件夹	`docs/specs/user-stories/US-XXX-[nombre-corto]/`
用户故事进度	`docs/specs/user-stories/US-XXX-[nombre-corto]/progress.md`
关联任务	`docs/specs/user-stories/US-XXX-[nombre-corto]/TK-XXX-[kebab-case].md`

Convenciones de rama

分支命名规范

Formato canónico:
```
feature/US-XXX-[nombre-corto]
```
con prefijo feature/
obligatorio,
```
US-XXX
```
en mayúsculas y nombre en kebab-case.
```
XXX
```
: tres dígitos con cero a la izquierda; coincide con el número de la carpeta de la US.

La carpeta de la US se deriva descontando el prefijo

feature/

feature/US-042-exportacion-csv

→

docs/specs/user-stories/US-042-exportacion-csv/

Una rama sin
```
feature/
```
o sin formato
```
US-XXX-...
```
no es submiteable por este skill.

Ejemplos:

feature/US-042-exportacion-csv

feature/US-013-ajuste-permisos

标准格式：
```
feature/US-XXX-[nombre-corto]
```
，必须包含
feature/
前缀，
```
US-XXX
```
为大写，名称采用kebab-case格式。
```
XXX
```
：三位数字，不足三位时前面补零；需与用户故事文件夹的编号一致。

用户故事文件夹由分支名称去掉

feature/

前缀得到：

feature/US-042-exportacion-csv

→

docs/specs/user-stories/US-042-exportacion-csv/

。

不符合
```
feature/
```
前缀或
```
US-XXX-...
```
格式的分支无法通过此Skill提交。

示例：

feature/US-042-exportacion-csv

、

feature/US-013-ajuste-permisos

。

Información requerida antes de mergear

合并前需确认的信息

Antes de tocar git, el agente debe tener clara la siguiente información. No asumir nada — si algún dato no se resuelve, preguntar al usuario.

Dato	Cómo obtenerlo	Si no está disponible
Rama actual	`git branch --show-current`	Si no encaja con el patrón `feature/US-XXX-[nombre-corto]` : preguntar a qué US corresponde antes de continuar
Carpeta de la US	Derivar del nombre de rama descontando el prefijo `feature/`	Si la carpeta no existe: parar e informar; si hay varias coincidentes: preguntar cuál
Estado de `progress.md`	Leer el archivo en la carpeta de la US	Si no existe: parar e informar; el merge requiere `progress.md` poblado
Working tree	`git status --porcelain`	Si hay salida: parar e informar; no se mergea con cambios pendientes
Rama base	(1) `git reflog show <branch>` → línea `Created from` ; (2) `git config --get branch.<branch>.merge` ; (3) preguntar al usuario	No asumir `main` , `master` ni `develop` por defecto
Idioma de preferencia	Ver Resolución de idioma	Preguntar y persistir en `.agents/MEMORY.md` con `preferred language: <código>`

Leer
progress.md
completo antes de iniciar cualquier operación git. Las tres condiciones (rama, working tree, estados) se evalúan antes de cambiar de rama o invocar
git merge
.

执行Git操作前，Agent必须明确以下信息。请勿假设任何内容——若某一信息无法确定，需询问用户。

信息	获取方式	无法获取时的处理
当前分支	`git branch --show-current`	若不符合 `feature/US-XXX-[nombre-corto]` 格式：先询问该分支对应的用户故事，再继续操作
用户故事文件夹	从分支名称中去掉 `feature/` 前缀推导得到	若文件夹不存在：停止操作并告知用户；若存在多个匹配项：询问用户选择哪一个
`progress.md` 状态	读取用户故事文件夹中的该文件	若文件不存在：停止操作并告知用户；合并操作需要已填写的 `progress.md`
工作区状态	`git status --porcelain`	若有输出：停止操作并告知用户；存在未提交更改时无法合并
基础分支	(1) `git reflog show <branch>` → 查找 `Created from` 行；(2) `git config --get branch.<branch>.merge` ；(3) 询问用户	请勿默认 `main` 、 `master` 或 `develop` 为基础分支
偏好语言	详见语言解析规则	询问用户并将答案保存到 `.agents/MEMORY.md` 中，格式为 `preferred language: <代码>`

执行任何Git操作前，需完整读取
progress.md
。需先验证三个条件（分支、工作区、任务状态），再切换分支或执行
git merge
。

Validación antes de mergear

合并前的验证

Antes de cambiar de rama o ejecutar el merge, verificar las siguientes condiciones. Si alguna falla, no mergear — informar al usuario y resolver primero.

¿Qué verificar?

Rama actual con formato válido:
```
feature/US-XXX-[nombre-corto]
```
. Sin el prefijo
```
feature/
```
o sin el segmento
```
US-XXX-...
```
no se puede derivar la carpeta de la US.
Working tree limpio:
```
git status --porcelain
```
sin salida. Cualquier cambio sin commitear bloquea el merge.

Carpeta de la US existe:

docs/specs/user-stories/US-XXX-[nombre-corto]/

presente con

progress.md

dentro.

Todas las tareas en
Done
: parsear
```
progress.md
```
y confirmar que cada entrada tiene estado
```
Done
```
(case-insensitive, sin espacios extra). Estados como
```
Pending
```
,
```
In Progress
```
o vacío bloquean el merge.
Code review con veredicto Apto: ejecutar code-review
(modificador
```
default
```
) antes del merge. Solo un veredicto ✅ Apto permite continuar. ❌ No apto e ⚠️ Incompleto bloquean el merge hasta que el usuario corrija los problemas y el review se repita con resultado Apto.
Rama base resoluble: identificada por reflog, por config, o confirmada explícitamente por el usuario. Si hay varios candidatos plausibles y ninguno definitivo, preguntar.

Si hay conflicto:

⚠️ No es posible mergear todavía:
- <razón concreta>
- [TK-XXX: estado-actual] — <detalle si aplica>

Ejemplos de razón concreta:

Rama actual no cumple feature/US-XXX-...: rama es 'fix/hotfix-cache'

Working tree sucio: 3 archivos modificados

progress.md: TK-002 en In Progress, TK-005 en Pending

Rama base ambigua: candidatos main, develop, release/2026.q2

切换分支或执行合并前，需验证以下条件。若任一条件不满足，请勿合并——告知用户并先解决问题。

需要验证哪些内容？

当前分支格式有效：符合
```
feature/US-XXX-[nombre-corto]
```
格式。若无
```
feature/
```
前缀或
```
US-XXX-...
```
段，则无法推导用户故事文件夹。
工作区干净：
```
git status --porcelain
```
无输出。任何未提交的更改都会阻止合并。

用户故事文件夹存在：

docs/specs/user-stories/US-XXX-[nombre-corto]/

文件夹存在且包含

progress.md

。

所有任务处于
Done
状态：解析
```
progress.md
```
并确认每一项任务的状态均为
```
Done
```
（不区分大小写，无多余空格）。
```
Pending
```
、
```
In Progress
```
或空白状态都会阻止合并。
代码评审结果为通过：合并前执行**
```
code-review
```
（默认参数）。只有✅ 通过的评审结果才能继续操作。❌ 不通过和⚠️ 未完成**会阻止合并，直到用户修复问题并重新评审得到通过结果。
基础分支可确定：通过reflog、配置或用户明确确认确定基础分支。若存在多个合理候选分支且无法明确，需询问用户。

若存在冲突：

⚠️ 暂时无法合并：
- <具体原因>
- [TK-XXX: 当前状态] — <适用时补充细节>

具体原因示例：

当前分支不符合feature/US-XXX-...格式：分支为'fix/hotfix-cache'

、

工作区未清理：3个文件已修改

、

progress.md: TK-002处于In Progress状态，TK-005处于Pending状态

、

基础分支模糊：候选分支为main、develop、release/2026.q2

。

Flujo: Submit estándar

流程：标准提交

Camino feliz cuando todas las verificaciones pasan.

Detectar rama actual con
```
git branch --show-current
```
y validar el patrón
```
feature/US-XXX-[nombre-corto]
```
. Si no encaja, parar y preguntar.
Verificar working tree limpio con
```
git status --porcelain
```
. Si hay salida, parar e informar.
Localizar la carpeta de la US descontando el prefijo
```
feature/
```
del nombre de rama:
```
feature/US-XXX-[nombre-corto]
```
→
```
docs/specs/user-stories/US-XXX-[nombre-corto]/
```
. Si la carpeta no existe o hay varias coincidentes, parar.
Leer
progress.md
y validar que todas las tareas tienen estado
```
Done
```
. Si alguna no lo está, parar mostrando la lista completa de tareas no
```
Done
```
con su estado actual.
Ejecutar
code-review
(modificador
```
default
```
) sobre la rama actual. Si el veredicto es ❌ No apto o ⚠️ Incompleto, parar y reportar el informe al usuario — no continuar con el merge hasta obtener veredicto ✅ Apto en una nueva ejecución.
Resolver la rama base:
- ```
git reflog show <branch>
```
  → buscar la entrada inicial con
```
Created from <ref>
```
  o
```
branch: Created from <ref>
```
  .
- Fallback:
```
git config --get branch.<branch>.merge
```
  y derivar la rama base local correspondiente.
- Si ninguno concluye o hay ambigüedad: preguntar al usuario sin proponer un default.
Calcular delta con
```
git rev-list --count <base>..HEAD
```
para reportar cuántos commits se van a integrar.
Cambiar a la rama base con
```
git checkout <base>
```
. Si falla, parar y reportar.
Ejecutar el merge con
```
git merge --no-ff <feature-branch> -m "Merge US-XXX: <nombre-corto>"
```
. El mensaje de merge usa solo
```
US-XXX: <nombre-corto>
```
(sin el prefijo
```
feature/
```
). Si surge conflicto, ir al flujo de conflictos.
Reportar resultado al usuario: rama origen (con prefijo
```
feature/
```
), rama destino, número de commits integrados, hash del commit de merge, estado del HEAD y nota explícita de que no se hizo push ni se borró la rama de la US.

所有验证通过后的顺畅流程。

检测当前分支：执行
```
git branch --show-current
```
并验证是否符合
```
feature/US-XXX-[nombre-corto]
```
格式。若不符合，停止操作并询问用户。
验证工作区干净：执行
```
git status --porcelain
```
。若有输出，停止操作并告知用户。
定位用户故事文件夹：从分支名称中去掉
```
feature/
```
前缀得到文件夹路径：
```
feature/US-XXX-[nombre-corto]
```
→
```
docs/specs/user-stories/US-XXX-[nombre-corto]/
```
。若文件夹不存在或存在多个匹配项，停止操作。
读取
progress.md
：验证所有任务均处于
```
Done
```
状态。若存在未完成任务，停止操作并列出所有未处于
```
Done
```
状态的任务及其当前状态。
执行
code-review
：对当前分支执行
```
code-review
```
（默认参数）。若评审结果为**❌ 不通过或⚠️ 未完成**，停止操作并向用户报告评审结果——直到重新评审得到**✅ 通过**结果，才能继续合并。
确定基础分支：
- ```
git reflog show <branch>
```
  → 查找初始记录中的
```
Created from <ref>
```
  或
```
branch: Created from <ref>
```
  。
- 备选方案：
```
git config --get branch.<branch>.merge
```
  并推导对应的本地基础分支。
- 若上述方法均无法确定或存在模糊性：询问用户，不提供默认选项。
计算提交增量：执行
```
git rev-list --count <base>..HEAD
```
以报告即将集成的提交数量。
切换到基础分支：执行
```
git checkout <base>
```
。若操作失败，停止操作并报告。
执行合并：执行
```
git merge --no-ff <feature-branch> -m "Merge US-XXX: <nombre-corto>"
```
。合并消息仅使用
```
US-XXX: <nombre-corto>
```
（不含
```
feature/
```
前缀）。若出现冲突，进入冲突处理流程。
向用户报告结果：告知用户源分支（含
```
feature/
```
前缀）、目标分支、集成的提交数量、合并提交的哈希值、HEAD的状态，并明确说明未执行push操作，也未删除用户故事分支。

Flujo: Manejo de conflictos

流程：冲突处理

Cuando

git merge

produce conflictos.

Abortar inmediatamente con
```
git merge --abort
```
para restaurar el repo al estado previo al merge. No intentar resolución automática ni usar
```
--strategy=ours
```
/
```
--strategy=theirs
```
.
Identificar archivos en conflicto parseando la salida del intento de merge.
Reportar al usuario la lista de archivos en conflicto y dejar claro que el repo quedó como estaba. Indicar que el siguiente paso (rebase, merge manual, decisión de alcance) está fuera del skill.
Parar. No reintentar; no encadenar otra acción git sin nueva instrucción del usuario.

当

git merge

产生冲突时的处理流程。

立即终止合并：执行
```
git merge --abort
```
以将仓库恢复到合并前的状态。请勿尝试自动解决冲突或使用
```
--strategy=ours
```
/
```
--strategy=theirs
```
参数。
识别冲突文件：解析合并尝试的输出结果，找出冲突文件。
向用户报告：列出冲突文件，并明确告知用户仓库已恢复到合并前状态。说明后续步骤（变基、手动合并、范围决策）超出该Skill的处理范围。
停止操作：请勿重试；未得到用户新指令前，请勿执行其他Git操作。

Flujo: Rama base ambigua

流程：基础分支模糊处理

Cuando reflog y config no concluyen, o existen varios candidatos plausibles.

Listar los candidatos detectados (p. ej.
```
main
```
,
```
develop
```
, ramas de release con commits ancestros del HEAD actual).
Preguntar al usuario cuál es la rama base correcta. No proponer un default ni inferir por convención del proyecto sin confirmación.
Esperar respuesta antes de continuar al paso 7 del flujo estándar. Sin respuesta clara, no hay merge.

当reflog和配置均无法确定基础分支，或存在多个合理候选分支时的处理流程。

列出候选分支：列出检测到的候选分支（例如
```
main
```
、
```
develop
```
、与当前HEAD有祖先提交的发布分支）。
询问用户：确认正确的基础分支。请勿默认推荐某一分支，也请勿未经确认就根据项目惯例推断。
等待用户回复：得到回复后再继续标准流程的第7步。若无明确回复，不得执行合并。

Checklist antes de mergear

合并前检查清单

Información:

Rama actual detectada y validada contra
```
feature/US-XXX-[nombre-corto]
```

Carpeta de la US localizada en

docs/specs/user-stories/US-XXX-[nombre-corto]/

Rama base resuelta (reflog, config o confirmación del usuario)
Idioma de preferencia determinado y
```
.agents/MEMORY.md
```
actualizado si fue necesario

Validación:

```
git status --porcelain
```
sin salida (working tree limpio)
```
progress.md
```
existe en la carpeta de la US
Todas las tareas de
```
progress.md
```
en estado
```
Done
```
code-review
ejecutado con veredicto ✅ Apto
Sin commits sin commitear ni stash sin aplicar relevante al alcance

Ejecución:

```
git checkout <base>
```
exitoso
```
git merge --no-ff
```
exitoso, sin conflictos
Hash del commit de merge capturado para el reporte
Número de commits integrados calculado antes del checkout

Cierre:

Reporte al usuario con rama origen, rama destino, commits integrados y hash de merge
Sin push ejecutado
Sin borrado de rama ejecutado
```
progress.md
```
no fue modificado por el skill

信息确认：

已检测当前分支并验证符合
```
feature/US-XXX-[nombre-corto]
```
格式

已定位用户故事文件夹至

docs/specs/user-stories/US-XXX-[nombre-corto]/

已确定基础分支（通过reflog、配置或用户确认）
已确定偏好语言，必要时已更新
```
.agents/MEMORY.md
```

验证项：

```
git status --porcelain
```
无输出（工作区干净）
用户故事文件夹中存在
```
progress.md
```
```
progress.md
```
中的所有任务均处于
```
Done
```
状态
已执行
```
code-review
```
且结果为**✅ 通过**
无与提交范围相关的未提交内容或未应用的stash

执行项：

```
git checkout <base>
```
执行成功
```
git merge --no-ff
```
执行成功且无冲突
已捕获合并提交的哈希值用于报告
切换分支前已计算集成的提交数量

收尾项：

已向用户报告源分支、目标分支、集成的提交数量及合并哈希值
未执行push操作
未执行分支删除操作
未修改
```
progress.md
```

Ejemplos

示例

Ejemplo 1 — Camino feliz

Entrada: Rama
```
feature/US-042-exportacion-csv
```
, working tree limpio,
```
progress.md
```
con tres tareas todas en
```
Done
```
, reflog indica
```
Created from develop
```
.

Salida:

git checkout develop

→

git merge --no-ff feature/US-042-exportacion-csv -m "Merge US-042: exportacion-csv"

→ reporte: «Merged 7 commits de

feature/US-042-exportacion-csv

→

develop

. Commit de merge:

a1b2c3d

. HEAD en

develop

, working tree limpio. La rama de US no fue borrada ni se hizo push.»

Ejemplo 2 — Tarea pendiente

Entrada: Rama
```
feature/US-013-ajuste-permisos
```
, working tree limpio,
```
progress.md
```
con TK-001 en
```
Done
```
y TK-002 en
```
In Progress
```
.

Salida: Sin operaciones git. Mensaje:

⚠️ No es posible mergear todavía:
- progress.md tiene tareas no Done:
  - TK-001: Done
  - TK-002: In Progress
- Completa o marca explícitamente cada tarea como Done antes de reintentar.

Ejemplo 3 — Rama base ambigua

Entrada: Rama
```
feature/US-077-...
```
, reflog sin entrada
```
Created from
```
, sin upstream local; existen
```
main
```
,
```
develop
```
y
```
release/2026.q2
```
como ancestros plausibles.
Comportamiento: El agente lista los candidatos y pregunta cuál es la rama base correcta. No asume
```
main
```
ni
```
develop
```
. No mergea hasta tener respuesta.

Ejemplo 4 — Working tree sucio

Entrada: Rama
```
feature/US-051-...
```
, dos archivos modificados sin commitear,
```
progress.md
```
íntegro en
```
Done
```
.
Salida: Sin operaciones git. Mensaje listando los archivos pendientes y pidiendo commit, stash o descarte antes de reintentar.

Ejemplo 5 — Conflicto en el merge

Entrada: Verificaciones OK, rama base
```
main
```
,
```
git merge --no-ff
```
produce conflictos en
```
src/app/Module.java
```
.
Comportamiento: El agente ejecuta
```
git merge --abort
```
, deja el repo en el estado previo, lista los archivos en conflicto y pide al usuario resolverlos manualmente. No reintenta.

Ejemplo 6 — Rama sin prefijo
feature/

Entrada: Rama

US-099-cleanup-logs

(sin el prefijo

feature/

progress.md

íntegro en

Done

Salida: Sin operaciones git. Mensaje: «La rama actual
```
US-099-cleanup-logs
```
no cumple el patrón
```
feature/US-XXX-[nombre-corto]
```
. Renombra la rama con
```
git branch -m feature/US-099-cleanup-logs
```
antes de reintentar el submit.»

示例1 — 顺畅流程

输入：分支为
```
feature/US-042-exportacion-csv
```
，工作区干净，
```
progress.md
```
中的三个任务均处于
```
Done
```
状态，reflog显示
```
Created from develop
```
。
输出：执行
```
git checkout develop
```
→
```
git merge --no-ff feature/US-042-exportacion-csv -m "Merge US-042: exportacion-csv"
```
→ 报告：«已将
```
feature/US-042-exportacion-csv
```
的7个提交合并至
```
develop
```
。合并提交哈希值：
```
a1b2c3d
```
。HEAD位于
```
develop
```
，工作区干净。用户故事分支未被删除，未执行push操作。»

示例2 — 存在未完成任务

输入：分支为
```
feature/US-013-ajuste-permisos
```
，工作区干净，
```
progress.md
```
中TK-001处于
```
Done
```
状态，TK-002处于
```
In Progress
```
状态。

输出：未执行任何Git操作。消息：

⚠️ 暂时无法合并：
- progress.md存在未完成任务：
  - TK-001: Done
  - TK-002: In Progress
- 请完成所有任务或明确标记为Done后重试。

示例3 — 基础分支模糊

输入：分支为
```
feature/US-077-...
```
，reflog无
```
Created from
```
记录，无本地上游分支；
```
main
```
、
```
develop
```
和
```
release/2026.q2
```
均为合理的祖先分支。
行为：Agent列出候选分支并询问用户正确的基础分支。不会默认
```
main
```
或
```
develop
```
。得到回复前不会执行合并。

示例4 — 工作区未清理

输入：分支为
```
feature/US-051-...
```
，两个文件已修改但未提交，
```
progress.md
```
所有任务均处于
```
Done
```
状态。
输出：未执行任何Git操作。消息列出未提交文件，并要求用户提交、暂存或丢弃更改后重试。

示例5 — 合并冲突

输入：所有验证通过，基础分支为
```
main
```
，执行
```
git merge --no-ff
```
时
```
src/app/Module.java
```
产生冲突。
行为：Agent执行
```
git merge --abort
```
，将仓库恢复到合并前状态，列出冲突文件并要求用户手动解决。不会重试。

示例6 — 分支无
feature/
前缀

输入：分支为
```
US-099-cleanup-logs
```
（无
```
feature/
```
前缀），
```
progress.md
```
所有任务均处于
```
Done
```
状态。
输出：未执行任何Git操作。消息：«当前分支
```
US-099-cleanup-logs
```
不符合
```
feature/US-XXX-[nombre-corto]
```
格式。请先执行
```
git branch -m feature/US-099-cleanup-logs
```
重命名分支，再尝试提交。»

Anti-patterns

反模式

Hacer merge sin verificar
```
progress.md
```
o ignorando tareas no
```
Done
```
.
Hacer merge sin haber ejecutado
```
code-review
```
o con veredicto ❌ No apto / ⚠️ Incompleto — el merge solo procede con veredicto ✅ Apto.
Modificar
```
progress.md
```
para «forzar» que aparezcan en
```
Done
```
sin que el trabajo esté completo.
Aceptar ramas sin prefijo
```
feature/
```
o con prefijos alternativos (
```
feat/
```
,
```
bugfix/
```
,
```
hotfix/
```
) como rama de submit.
Asumir
```
main
```
,
```
master
```
o
```
develop
```
como rama base sin confirmarlo por reflog, config o usuario.
Resolver conflictos automáticamente o usar
```
--strategy=ours
```
/
```
--strategy=theirs
```
para hacerlo pasar.
Usar merge fast-forward por defecto cuando el historial de la rama de US se perdería; preservar con
```
--no-ff
```
salvo petición explícita del usuario.
Hacer push de la rama base o borrar la rama de la US sin que el usuario lo pida explícitamente fuera del skill.
Mergear con working tree sucio o desde una rama que no encaja con
```
feature/US-XXX-[nombre-corto]
```
.
Cerrar varias US en una sola pasada del skill; este flujo cubre una US por ejecución.
Reintentar el merge tras un conflicto sin nueva instrucción del usuario.
Narrar el trabajo realizado en el mensaje al usuario («leí progress.md», «detecté la rama»); solo reportar resultados y pendientes.
Lanzar preguntas al usuario como prosa libre cuando el cliente expone una herramienta de preguntas estructuradas; preguntar la rama base sin listar candidatos como opciones tappables cuando la herramienta está disponible.

未验证
```
progress.md
```
或忽略未完成任务就执行合并。
未执行
```
code-review
```
或评审结果为**❌ 不通过** / ⚠️ 未完成时执行合并——只有评审结果为**✅ 通过**才能执行合并。
修改
```
progress.md
```
以“强制”任务显示为
```
Done
```
，但实际工作未完成。
接受无
```
feature/
```
前缀或使用其他前缀（
```
feat/
```
、
```
bugfix/
```
、
```
hotfix/
```
）的分支作为提交分支。
未经reflog、配置或用户确认，就默认
```
main
```
、
```
master
```
或
```
develop
```
为基础分支。
自动解决冲突或使用
```
--strategy=ours
```
/
```
--strategy=theirs
```
参数“蒙混过关”。
默认使用快进合并，导致用户故事分支的历史丢失；除非用户明确要求，否则需使用
```
--no-ff
```
参数保留历史。
未经用户明确要求，就推送基础分支或删除用户故事分支。
工作区未清理或分支不符合
```
feature/US-XXX-[nombre-corto]
```
格式时执行合并。
一次提交多个用户故事；此流程每次仅处理一个用户故事。
发生冲突后未得到用户新指令就重试合并。
向用户描述内部操作过程（如“已读取progress.md”、“已检测分支”）；仅需报告结果和待办事项。
客户提供结构化提问工具时，仍用自由文本提问；使用该工具时，询问基础分支需列出候选分支作为可点击选项。

Notas

说明

Handoffs del ciclo

流程交接

Posición: cierre local — último paso del pipeline de historias (sin push ni PR).


Entrada	Rama `feature/US-XXX-[nombre-corto]` ; working tree limpio; commits de la implementación ya hechos ( `git-commit` ); `progress.md` con cada TK listada en `Done` ; `code-review` con veredicto ✅ Apto.
Salida	Merge `--no-ff` a la rama base local; reporte con hash de merge. Sin push ni borrado de rama.
Siguiente paso (fuera del skill)	Push de la rama base y CI — decisión del usuario.
PR/MR ( `git-pr` )	Abrir antes de este skill, estando en `feature/US-XXX-[nombre-corto]` (o con la feature ya publicada en remoto). Tras el merge local, la rama activa es la base; `git-pr` bloquea en `main` / `master` / `develop` / `trunk` .
Regreso a implement	TK no `Done` o `progress.md` incompleto → completar en `story-implement` y actualizar `progress.md` antes de reintentar.
Regreso a define / plan	Alcance de US reducido o TK fuera de entrega → alinear con `story-define` / `story-plan` , corregir `progress.md` y reintentar.

定位：本地收尾——用户故事流程的最后一步（不含push或PR）。


输入	分支为 `feature/US-XXX-[nombre-corto]` ；工作区干净；已完成实现提交（ `git-commit` ）； `progress.md` 中每一项TK均标记为 `Done` ； `code-review` 结果为✅ 通过。
输出	已在本地执行 `--no-ff` 合并至基础分支；已报告合并哈希值。未执行push或分支删除操作。
后续步骤（Skill外）	推送基础分支并执行CI——由用户决定。
PR/MR ( `git-pr` )	需在该Skill执行前打开，此时处于 `feature/US-XXX-[nombre-corto]` 分支（或功能已推送至远程）。本地合并后，当前分支为基础分支； `git-pr` 在 `main` / `master` / `develop` / `trunk` 分支上会被阻止。
返回实现阶段	TK未标记为 `Done` 或 `progress.md` 不完整 → 回到 `story-implement` 完成工作并更新 `progress.md` 后重试。
返回定义/规划阶段	用户故事范围缩小或TK超出交付范围 → 与 `story-define` / `story-plan` 对齐，修正 `progress.md` 后重试。

progress.md

El skill lee

progress.md

para verificar estados, pero no lo modifica. La actualización de estados durante la implementación es responsabilidad de story-implement. Si al revisar el archivo aparecen tareas en

In Progress

que sí están terminadas en código, el usuario debe corregir el archivo antes de reintentar el submit — no es papel del submit ajustar progreso.

该Skill仅读取

progress.md

以验证任务状态，不会修改它。实现过程中更新任务状态是story-implement的职责。若检查时发现

progress.md

中标记为

In Progress

的任务实际已在代码中完成，用户需先修正该文件，再尝试提交——提交操作不负责调整进度。

Estados de

progress.md

progress.md的任务状态

Estados válidos por tarea: Pending
, In Progress
, Done
. Solo Done
(case-insensitive, sin espacios extra) cierra una tarea para merge.

任务的有效状态：Pending
、In Progress
、Done
。只有**

Done

**（不区分大小写，无多余空格）表示任务已完成，可进行合并。

Detección de rama base

基础分支检测

git reflog show <branch>

es la fuente más fiable, pero solo funciona localmente y se pierde si la rama se clonó fresh o si

gc.reflogExpire

ya pasó. El fallback a

git config --get branch.<branch>.merge

cubre el caso de upstream local. Cuando ambos fallan, la pregunta al usuario es por diseño, no por descuido: el skill no debe adivinar la rama de integración.

git reflog show <branch>

是最可靠的来源，但仅在本地有效，若分支是全新克隆或

gc.reflogExpire

已过期则会丢失记录。备选方案

git config --get branch.<branch>.merge

适用于本地上游分支的情况。当两种方法都失败时，询问用户是设计要求，而非疏忽：Skill不得猜测集成分支。

Sin push intencional

不执行push操作的原因

La decisión de cuándo publicar el merge en el remoto queda fuera del skill, para preservar el control del usuario sobre integración con CI/CD, MRs/PRs y revisión. El mensaje final al usuario debe dejar explícito que el merge es solo local y que push y limpieza de ramas son pasos manuales posteriores.

何时将合并结果推送到远程仓库由用户决定，以保留用户对CI/CD集成、MR/PR和评审的控制权。最终需明确告知用户合并仅在本地完成，推送和分支清理是后续手动步骤。

Mensaje al usuario

用户消息规范

Solo resultados y lo que el usuario debe saber o decidir. No incluir razonamiento interno, cadenas de pensamiento ni narración del trabajo en curso. Si hay condiciones que bloquean el merge, listarlas en viñetas con detalle suficiente para que el usuario pueda actuar (qué archivos, qué tareas, qué estados).

仅需告知用户结果及需要了解或决定的内容。不得包含内部推理、思考过程或操作描述。若存在阻止合并的条件，需列出具体细节（如哪些文件、哪些任务、什么状态），以便用户采取行动。