jackleh/claude-skills

Iniciar Elemento de Trabajo

Convierte un ticket de ADO pegado en: una rama nueva (o correctamente reanudada), una memoria de contexto que sesiones posteriores puedan retomar, un descubrimiento fundamentado del código fuente, y ya sea un análisis de causa raíz o un diseño de funcionalidad. Termina en un punto de control: presenta los hallazgos y espera. En esta habilidad no se escribe código de corrección ni de funcionalidad; el usuario aprueba primero la dirección, porque un RCA incorrecto que se implementa rápido cuesta un ciclo completo de QA.

0. Cargar la configuración local

Lee primero config.local.md en la carpeta de esta habilidad — antes de analizar el ticket. Contiene los sustantivos que esta habilidad deliberadamente no incluye de forma fija: prefijo de rama, rama base, el documento de capas del proyecto, dónde residen las investigaciones, los puntos ciegos del índice de código y las memorias pasadas que vale la pena señalar. La calidad del descubrimiento depende de esos detalles específicos, así que no lo omitas.

Si falta (instalación nueva), infiere lo que puedas — rama base desde git remote show origin (rama HEAD), prefijo de las ramas existentes del usuario (git branch --list "*/*") — dile al usuario lo que inferiste y ofrécete a guardarlo como config.local.md (consulta config.example.md).

El directorio de memoria es el que tu prompt del sistema nombra para este proyecto; el repositorio es en el que estás trabajando. Ninguno necesita configuración.

1. Analizar el ticket

Extrae, de lo que se haya pegado. El copiado de página de ADO es ruidoso: la primera línea es el tipo y el ID en mayúsculas (USER STORY 12345, BUG 12346), cada etiqueta de campo está en su propia línea con el valor en la siguiente (State / Dev In Progress), las etiquetas aparecen como líneas sueltas cerca de la parte superior, y hay elementos de la interfaz de usuario que ignorar (Save, Follow, Click to add …, switch to HTML editor, secciones vacías de TestRail). Las imágenes y los archivos adjuntos no sobreviven al pegado.

• ID (número) y Tipo de elemento de trabajo — Bug vs. User Story / Feature / PBI / Task. Si el tipo no se indica, infiérelo (pasos de reproducción + esperado/real ⇒ bug; "Como un … quiero" o criterios de aceptación ⇒ característica) y di lo que inferiste.
• Título, Estado, Área/Iteración si están presentes
• Bug: pasos de reproducción, esperado vs. real, número de compilación, plataforma/dispositivo/SO, enlaces profundos, nombres de registros adjuntos, capturas de pantalla mencionadas
• Característica: descripción, criterios de aceptación, diseños vinculados, nombres de características experimentales / flags
• Discusión/comentarios: intentos anteriores, notas de QA y sus fechas, números de PR

Si no hay ID, pídelo antes de crear nada — el ID impulsa la rama y los nombres de la memoria. Anota cualquier cosa referenciada pero no visible (capturas de pantalla, registros) para poder preguntar por ello en el punto de control en lugar de adivinar su contenido.

2. Rama

Ejecuta git en el repositorio en el que estás trabajando (si la sesión está en un worktree u otro clon, usa ese — nunca hagas cd para alejarte de él):

git status --porcelain

Si el árbol está sucio, detente. Enumera los archivos y la rama actual, y pregunta cómo proceder (llevar los cambios, guardarlos temporalmente o confirmarlos en la rama anterior). Los archivos no confirmados de un elemento se filtrarán en las confirmaciones del siguiente; el usuario decide esto, no tú.

Cuando esté limpio:

git fetch origin
git branch --list "<prefijo>/<id>*"; git branch -r --list "origin/<prefijo>/<id>*"

Si no existe una rama para el ID, crea <prefijo>/<id> desde origin/<base> y registra el SHA corto (git rev-parse --short HEAD).

Si <prefijo>/<id> o <prefijo>/<id>-N ya existe (local o remoto), mira el más reciente antes de decidir — el mismo ID puede llegar en tres momentos muy diferentes:

git log --oneline origin/<base>..<prefijo>/<id>[-N]   # ¿commits sin fusionar?
git log --oneline origin/<base> --grep=<id>           # "Merged PR NNNN: ... <id>" = se fusionó

ADO hace squash-merge, por lo que una rama fusionada aún muestra sus commits como "adelantados" respecto a la base — la línea Merged PR en la rama base es lo que indica que aterrizó. Léelo junto con el Estado del ticket y la fecha del comentario de QA más reciente frente a la última confirmación de la rama.

Rama existente más reciente	Estado típico del ticket	Qué hacer
Sin commits más allá de origin/<base> (a menudo la rama en la que estás, el usuario la creó antes de pegar)	Nuevo / Dev In Progress	Reutilízala. Haz checkout, git merge --ff-only origin/<base>.
Fusionada (un Merged PR para este ID en la base) y QA ha fallado desde entonces	Activo / reabierto, comentario de fallo de QA más reciente que la fusión	Crea el siguiente sufijo (-1, -2, …) desde origin/<base>; el intento anterior se convierte en material de descubrimiento principal.
Commits sin fusionar (subidos o no), o un PR aún abierto	Revisión de PR / Listo para Prueba / En Progreso	En vuelo — no crees rama. Informa lo que hay en ella (commits, si está subida, qué tan atrasada está respecto a la base), conviértela en el tema del descubrimiento y pregunta si reanudar o comenzar un nuevo intento.

Si las señales discrepan (por ejemplo, el estado dice Nuevo pero hay una rama sin fusionar), trátalo como en vuelo y pregunta — crear una rama duplicada es el error costoso. Si git fetch falla (VPN / autenticación), dilo y usa la origin/<base> local, señalando que la base puede estar desactualizada.

No hagas push ni confirmes — el usuario no lo ha pedido.

3. Memoria de contexto (escríbela ahora, actualízala después)

Escribe la memoria antes del descubrimiento, con estado ⏳, para que el elemento se pueda reanudar incluso si la sesión muere a medio camino de la investigación. Usa references/memory-template.md.

• Bug → bug-<id>-context.md, característica/historia/tarea → feature-<id>-context.md
• Si ya existe una para este ID, actualízala en lugar de crear una segunda — y corrige cualquier cosa en ella que el estado de git ahora contradiga.
• Agrega un puntero de una línea a MEMORY.md. Sin él, las sesiones posteriores nunca encuentran la memoria.

4. Descubrimiento del código fuente

El objetivo es encontrar las rutas de código reales que toca el ticket y el historial a su alrededor — lo suficiente para que el RCA/diseño cite archivo:línea, no suposiciones.

• Usa el índice de código si lo hay (CodeGraph, LSP): comienza con una consulta de contexto sobre los sustantivos del ticket (página, control, servicio, DTO), luego una llamada de exploración sobre lo que surja; llamantes/impacto en el símbolo sospechoso. Verifica en la configuración los puntos ciegos del índice (tipos de archivo que no analiza) y haz grep de esos en su lugar.
• Rutas y nombres de UI: las rutas de página, nombres de componentes, clases CSS y esquemas de enlace profundo del ticket son buenos términos de grep.
• Trabajo anterior: git log --oneline --all --grep=<id>, git log --oneline -20 -- <archivos sospechosos>, la carpeta de documentos/investigaciones del proyecto (configuración) y el directorio de memoria para informes sobre la misma área. Una corrección anterior para el mismo síntoma que falló en QA es lo más valioso que puedes encontrar.
• Compara los casos que pasan y los que fallan. Cuando QA enumera casos que pasan y uno que falla, encuentra qué es realmente diferente entre ellos en el código: la página anfitriona, la ruta de datos, la sincronización — antes de decidir un mecanismo.
• Cada plataforma/cabezal: si la UI se comparte entre plataformas (shell móvil, web), verifica si el ticket es específico de una plataforma y si el código también lo es.
• No compiles durante el descubrimiento. Leer código es suficiente aquí; las compilaciones son lentas y pertenecen a la implementación.

Para barridos amplios a través de muchas carpetas, un subagente de Exploración está bien; para un área conocida, hazlo directamente.

5a. Bug → análisis de causa raíz

Usa la habilidad superpowers:systematic-debugging para el método si está disponible. El estándar es medido, no adivinado: nombra el mecanismo y la archivo:línea exacta, y explica por qué produce precisamente el síntoma reportado y no otro (por qué falla el caso que falla y pasan los que pasan).

• Traza la ruta desde la acción del usuario en los pasos de reproducción hasta el estado defectuoso. Cita las líneas relevantes.
• Reproduce cuando sea factible sin un dispositivo: pruebas de componentes para estado/marcado, una réplica estática headless-browser para problemas de diseño/desplazamiento/CSS (la configuración puede apuntar a una memoria que describa un arnés existente). Si no puedes reproducir, dilo claramente, expresa tu nivel de confianza y qué evidencia lo confirmaría (por ejemplo, una línea de registro específica o una captura de pantalla de QA).
• Separa la causa raíz de los factores contribuyentes y de los problemas adyacentes que pertenecen a otros tickets.
• Propón una dirección de corrección (o 2-3 opciones con una recomendación) y la prueba de regresión que la fijaría — pero no las escribas todavía.
• Elemento en vuelo (paso 2): el RCA se convierte en una revisión de la corrección ya en la rama — ¿aborda la falla de QA más reciente, y qué riesgos residuales harían que fallara en el dispositivo? Recomienda reanudarlo y di qué resultado de QA justificaría un nuevo intento.

5b. Característica → diseño y elaboración

Usa la habilidad superpowers:brainstorming para la conversación de diseño si está disponible.

Primero evalúa si los criterios de aceptación son suficientes. Lo son cuando:

• cada CA se puede convertir en una aserción de prueba concreta y mapear a un archivo para modificar, y
• los estados de la UI (cargando, vacío, error, deshabilitado), el comportamiento por plataforma, los eventos de analytics y el uso de características experimentales están especificados o claramente no aplican.

Si son suficientes, no hagas preguntas por hacerlas — presenta el diseño. Si no lo son, se requiere elaboración: pregunta solo sobre las brechas, agrupadas en un solo AskUserQuestion (hasta 4 preguntas, opciones concretas, un valor predeterminado recomendado primero). Las CA vagas que se adivinan generan retrabajo.

Ordena cada brecha antes de preguntar: si la respuesta cambiaría el diseño (qué se muestra, de dónde vienen los datos, qué ve el usuario al tocar), es una pregunta. Si es algo con una convención obvia del proyecto — una clave de característica experimental, un nombre de evento de analytics, un registro de DI — elige el valor convencional, escríbelo en el diseño como Asumido: para que el usuario pueda corregirlo de un vistazo, y no preguntes. El lote de 4 preguntas es toda la solicitud; no hay un "además, por favor confirma…" después de él, porque eso son solo más preguntas sin opciones.

El diseño cubre:

• Archivos para agregar/modificar, colocados según las capas del proyecto (la configuración apunta al documento que las define), incluido el registro de DI en cada plataforma
• Flujo de datos: de dónde vienen los datos, qué servicio posee el estado, cómo llega al componente
• Mapeo CA → prueba, nombrando el proyecto de prueba para cada una
• Diferencias entre plataformas, analytics/flags, riesgos y preguntas abiertas

6. Punto de control

Actualiza el archivo de memoria con lo que encontraste (estado 🔄, resumen de causa raíz o diseño, preguntas abiertas), luego preséntalo al usuario:

Bug:

## Bug <id>: <título>
Rama: <prefijo>/<id> (desde origin/<base> @ <sha>)   — o: en vuelo en <rama>, sin rama nueva
Memoria: bug-<id>-context.md

### Causa raíz
<mecanismo, archivo:línea, por qué coincide con el síntoma> — Confianza: <alta/media/baja + qué la aumentaría>

### Evidencia
<citas de código, resultados de reproducción, historial: PRs/intentos anteriores>

### Corrección propuesta
<dirección u opciones + recomendación; prueba de regresión a agregar; archivos a modificar>

### Necesito de ti
<capturas de pantalla/registros faltantes, decisiones>

Característica:

## Feature <id>: <título>
Rama / Memoria: ...

### Lo que dicen las CA vs. lo que falta
### Diseño propuesto (archivos, flujo de datos, CA → pruebas, cada plataforma, Asumido: …)
### Preguntas  (o "Ninguna — las CA son suficientes")

Luego detente y espera la aprobación. Si el RCA o el diseño abarca 5+ archivos o cambia la arquitectura, ofrécete a redactarlo en la carpeta de documentos/investigaciones del proyecto (configuración) — ofrécelo, no lo crees automáticamente.