Skill: Integración de historia de usuario

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.

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.

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>
```
.

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`

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

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
.

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

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.

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.

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.

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

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.»

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.

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.

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.

Estados de

progress.md

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

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.

Sin push intencional

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.

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).

story-integrate

NPX Install

Tags

SKILL.md Content