Work Research

Skill: Investigación de trabajo

Skill genérico de investigación. Recopila información, la sintetiza y la persiste de forma estandarizada. Corre seis flujos según la entrada; todos comparten el mismo esqueleto —capturar intención → cargar contexto → investigar → sintetizar → guardar— y la misma salida estandarizada, con una excepción declarada: Analizar issue.

Propósito: resolver dudas y preparar el terreno antes de especificar, planificar o implementar. La investigación alimenta decisiones; no modifica artefactos existentes ni genera código. Tampoco genera el plan de implementación: ese paso lo continúan work-define o work-plan.

Este archivo contiene solo lo transversal. El procedimiento de cada flujo vive en su propio archivo de references/, que se carga únicamente cuando ese flujo se selecciona.

Flujos

El flujo se determina por la entrada en el Paso 1. No mezclar flujos en una misma ejecución: si la investigación revela que hace falta otro, se cierra el actual y se ofrece el siguiente como handoff.

Cada flujo se identifica por su nombre, nunca por su número de fila: el orden de la tabla es de lectura, no un identificador.

Los cuatro flujos de análisis se solapan en sus señales de entrada; los criterios de desempate están en Desempates, dentro del Paso 1.

Salida estandarizada

Toda investigación genera una carpeta research/RS-XXX-{slug}/ con un README.md como informe principal, redactado con [assets/research-template.md](assets/research-template.md). Puede contener archivos adicionales en la misma carpeta si el flujo los define, siempre referenciados desde el README.md.

Dónde vive la carpeta research/:

Artefacto archivado. Si la carpeta de un US-XXX/TK-XXX/WI-XXX/RS-XXX no aparece en su ruta activa, buscarla bajo docs/archive/ (archive/user-stories/, archive/work-items/, archive/research/) antes de darla por inexistente: work-integrate y pr-create pueden moverla ahí al cerrar el trabajo, si el usuario lo confirma. Nunca recrearla en la ruta activa. Ver work-integrate/references/archive.md. Lo que se haga con el hallazgo depende de dónde escriba el flujo:

• Flujos que escribirían el RS-XXX dentro del research/ del artefacto — solo Analizar decisiones pendientes: parar y avisar. Un trabajo cerrado no tiene decisiones pendientes que resolver, y retomarlo exige desarchivarlo, decisión del usuario.
• Flujos que lo leen como contexto y escriben fuera (Analizar issue, que produce un dossier y un WI-XXX nuevo; Investigación libre): continuar. Leer un artefacto archivado es siempre legítimo — investigar un bug de algo ya entregado es el caso normal.
• Analizar test case cambia de grupo según el padre: con padre activo escribe en su research/; con padre archivado no escribe dentro pero tampoco para — lee el padre como contexto y guarda el RS-XXX en docs/specs/research/, la ruta que su propia tabla ya reserva para un TC sin padre local. Auditar el caso de prueba de un trabajo entregado es legítimo y frecuente; ver references/test-case/flow.md.

Ver work-integrate/references/archive.md.

Archivos adicionales por flujo:

Salidas fuera de research/

• Analizar legado crea además, por cada feature descubierto, una carpeta docs/specs/features/FT-XXX-{slug}/ con su README.md ([assets/legacy/feature-template.md](assets/legacy/feature-template.md)) y sus casos de prueba vía test-define, en su propio subárbol y con numeración independiente. Condiciones y doctrina en [references/legacy/flow.md](references/legacy/flow.md).
• Analizar issue es la única excepción a la salida estandarizada: no crea un RS-XXX. Su entregable es el WI de tipo bug-fix que crea work-plan en docs/specs/work-items/WI-XXX-{kebab-case}/README.md. Este skill produce el dossier de bug con [assets/issue/diagnosis-template.md](assets/issue/diagnosis-template.md), lo presenta y lo pasa como insumo del handoff. Solo si el usuario lo pide explícitamente se guarda además un RS-XXX en docs/specs/research/.

Resolución de la integración con el gestor de proyectos

Antes de ejecutar este skill, DEBES leer ${PLUGIN_ROOT}/reference/project-management.md.

Las reglas de project-management.md son obligatorias y tienen prioridad para determinar si hay integración con un gestor de proyectos, con qué proveedor y con qué datos de conexión.

No continúes hasta haber leído y aplicado project-management.md.

Delta de este skill: cuando la integración está activa, cualquier artefacto que el usuario pase por su código o URL —no solo un bug— se lee vía MCP y enruta al flujo que corresponda a su tipo. Para work-research la integración es de solo lectura: trae contexto; no crea ni modifica work items. Todo el detalle propio de cada proveedor (herramienta MCP, nombres de campos, tipos de work item) vive exclusivamente en su archivo de references/.

• Desactivada → trabajar con lo que aporte el usuario y con el repo; no leer ninguna referencia de proveedor.
• Activada → cargar references/<proveedor>.md (p. ej. references/azure-devops.md) y seguir únicamente sus pasos para obtener el artefacto. Si este skill no tiene referencia para ese proveedor, o su MCP no está conectado, informarlo y continuar con la información que aporte el usuario — nunca detener la investigación por esto.

Enrutado por tipo de artefacto (los nombres exactos de cada tipo los define el archivo de referencia del proveedor):

Si el artefacto existe a la vez en el gestor y en el repo, leer ambos: el documento local es la especificación; el work item aporta estado, comentarios, adjuntos y decisiones que nunca llegaron al documento. Si discrepan, señalarlo como hallazgo en lugar de elegir uno por cuenta propia.

Cómo preguntar al usuario

Mecanismo, ritmo y fallback compartidos: ${PLUGIN_ROOT}/reference/asking.md.

Cada vez que este skill o sus referencias digan preguntar, pedir, confirmar, validar o sugerir algo al usuario, asume ese mecanismo; no se repite allí.

No preguntar lo que ya consta en el artefacto, en el work item del gestor o en la conversación.

Modo de ejecución

Si este skill es invocado dentro de una sesión activa de work-implement (el agente principal está ejecutando una TK o un WI), ejecutar la investigación como subagente o tarea delegada:

• Lanzar la investigación usando la herramienta de subagente/tarea del cliente.
• El subagente ejecuta el flujo de forma autónoma hasta el Paso 4 inclusive, sin escribir nada en disco: la confirmación del usuario no se salta por estar en subagente.
• Al terminar, devuelve al agente principal el contenido íntegro propuesto (los archivos que se escribirían, completos) junto con la ruta tentativa. El agente principal lo presenta al usuario tal cual y ejecuta el Paso 5 solo tras la confirmación. En Analizar issue no hay RS: devuelve el dossier completo y, si el handoff ya se confirmó, la ruta del WI creado.
• El agente principal continúa sin interrumpir el flujo de la sesión, pero no da por guardada una investigación que el usuario no confirmó.

Si no hay sesión de implementación activa, ejecutar de forma interactiva con el usuario (flujo normal).

Rutas de las referencias compartidas

${PLUGIN_ROOT} es la raíz del plugin instalado (la carpeta que contiene skills/, agents/ y reference/), y toda referencia compartida de este skill se escribe como ${PLUGIN_ROOT}/reference/<archivo>.md. Resolverla así, en este orden: (1) en Claude Code, ${PLUGIN_ROOT} es ${CLAUDE_PLUGIN_ROOT} — comprobar con echo "$CLAUDE_PLUGIN_ROOT" y usar ese valor; (2) en cualquier otro cliente, o si la variable está vacía, la carpeta desde la que se cargó este archivo, dos niveles arriba. El destino de cada enlace markdown (../../reference/…) existe solo para navegar el repositorio en GitHub o en un editor: no resolverlo desde el directorio de trabajo. Nunca buscar reference/ en el proyecto: un <proyecto>/reference/language.md que no existe no es un archivo que falte, es una ruta mal resuelta — corregir la raíz y volver a leer, sin preguntar al usuario ni saltarse la lectura.

Resolución de idioma

Antes de ejecutar este skill, DEBES leer ${PLUGIN_ROOT}/reference/language.md.

Las reglas de language.md son obligatorias y tienen prioridad para determinar el idioma de todos los artefactos y mensajes generados por este skill.

No continúes hasta haber leído y aplicado language.md.

Excepción deliberada: si hay artefacto o proyecto vinculado, redactar el informe en el idioma de ese contexto. Ante conflicto con el idioma resuelto, preguntar.

Paso 1 — Capturar la intención y elegir el flujo

Evaluar la entrada en este orden y quedarse con la primera coincidencia:

1. ¿Es un identificador del gestor de proyectos (#4821, una URL del gestor, un código con prefijo propio del sistema)? → resolver la vinculación (Resolución de la integración con el gestor de proyectos), leer el work item por MCP y enrutar según su tipo con la tabla de esa sección. Leer antes de preguntar: lo que ya está en el work item no se pregunta.
2. ¿Es un caso de prueba (TC-XXX, "revisa este test", "¿este caso de prueba está bien?", "¿el test cubre esto?")? → Analizar test case.
3. ¿Describe un comportamiento defectuoso —algo que el sistema hace y no debería, o deja de hacer— o un bug reportado? Señales: "hay un bug", "falla", "error en producción", "no funciona X", "¿por qué devuelve Y?", un stack trace, una captura de error. → Analizar issue. Tiene prioridad aunque haya un US/WI en contexto: ese artefacto pasa a ser la referencia del comportamiento esperado, no el objeto de la investigación.
4. ¿Hay un artefacto US-XXX / TK-XXX / WI-XXX / FT-XXX mencionado o implícito? → Analizar decisiones pendientes. Cargarlo como contexto sin preguntar; si hay ambigüedad (número sin prefijo, referencia vaga), preguntar. Un FT-XXX documenta código ya implementado: sobre él las «decisiones pendientes» suelen ser de cobertura o de especificación incompleta, no de diseño.
5. ¿La entrada es código existente que hay que "documentar hacia atrás" —descubrir qué hace y crear features y pruebas desde él porque no tiene requisitos escritos o su cobertura es inadecuada? Señales: "analiza este código", "ingeniería inversa", "no tenemos requisitos/pruebas de este módulo". → Analizar legado. Si no está claro qué código entra en el alcance, pedirlo; no inventar comportamiento ausente.
6. ¿Hay un proyecto origen y uno destino (migrar código, features o dependencias entre dos proyectos)? → Analizar migración. Si falta identificar alguno de los dos, pedirlo; no inventar rutas ni stacks.
7. Si nada de lo anterior aplica → Investigación libre.

Una vez elegido el flujo, cargar su archivo de references/ y seguirlo. No leer las referencias de los demás flujos.

Desempates

Cuando una entrada dispara dos reglas, manda el objeto de la duda, no el orden de la lista:

En cualquier flujo, antes de investigar:

• Clarificar lagunas de alcance. Si la entrada tiene vacíos que impedirían una investigación de calidad (alcance impreciso, contexto faltante, restricciones no mencionadas), resolverlos con la herramienta de preguntas estructuradas.

• Formular la pregunta de investigación en una oración concisa y confirmarla: opciones [Confirmar] / [Cancelar] — el ajuste llega por respuesta libre, no como opción; si el usuario pide uno, aplicarlo y volver a formular la pregunta. No investigar hasta recibir confirmación. Qué forma toma la pregunta según el flujo:

  Flujo	La pregunta es…
  Investigación libre	El tema, acotado a un dominio
  Analizar decisiones pendientes	«¿Qué falta decidir o aclarar en para poder planificarlo/implementarlo?»
  Analizar issue	«¿Por qué ocurre y qué prueba lo demuestra?» — requiere antes el reporte normalizado mínimo (observado, esperado, disparador)
  Analizar test case	«¿ verifica realmente , y la implementación lo satisface?»
  Analizar legado	«¿Qué hace hoy <código en alcance> y qué features y reglas implementa?»
  Analizar migración	El objetivo de la migración: qué se migra y de qué origen a qué destino

Paso 2 — Cargar contexto

Qué leer y en qué orden lo define el archivo de referencia del flujo elegido. Reglas comunes a todos:

• Leer antes de investigar. Nunca investigar sobre un artefacto sin haberlo abierto.
• No duplicar investigaciones previas. Revisar el research/ correspondiente —y, si la base es docs/specs/research/, también docs/archive/research/—; si ya hay un RS sobre el mismo tema, mostrarlo al usuario y partir de él.
• Verificar contra el repo, no contra la memoria. Stack, versiones y estructura se comprueban en los manifiestos y el código.
• Registrar lo que no existe. «No hay ADR sobre esto», «no hay pruebas de este módulo» son hallazgos, no omisiones.

Paso 2.5 — Inspeccionar referencias visuales (imágenes y Figma)

Si el usuario proporcionó referencias (imágenes, capturas, enlaces a Figma) —en el mensaje o dentro del artefacto cargado— inspeccionarlas antes de investigar:

1. Abrir e inspeccionar cada referencia en detalle (layouts, componentes, estados, anotaciones), no de forma superficial.
2. Detectar lagunas (estado no cubierto, medida no definida, comportamiento no anotado, texto ilegible). No asumir ni rellenar por cuenta propia.
3. Resolver cada laguna con la herramienta de preguntas estructuradas antes de continuar. No avanzar al Paso 3 con dudas pendientes.
4. Si un enlace de Figma no es accesible, pedir capturas o exportación.

Paso 3 — Investigar

Ejecutar el procedimiento del archivo de referencia del flujo elegido, usando búsqueda web, documentación oficial, repositorios públicos e inspección directa del código cuando corresponda.

Calidad de las fuentes (todos los flujos)

• Priorizar documentación oficial, RFC, papers, repositorios activos.
• Indicar la fecha de la fuente cuando la vigencia importa (versiones, APIs, precios).
• Si la información es contradictoria o incierta, decirlo explícitamente en lugar de sintetizar como si fuera certeza.
• Todo hallazgo sobre el código cita archivo y símbolo. Un hallazgo sin evidencia es una hipótesis: se marca como tal y se verifica o se descarta.

Paso 4 — Sintetizar y presentar

Regla dura, transversal a todos los flujos: nada se escribe en disco antes de la confirmación de este paso. Ni el README.md, ni los archivos adicionales, ni la carpeta RS-XXX-{slug}/. Preguntar «¿guardo el resultado?» sobre un archivo que ya está escrito no es una confirmación: es un reporte disfrazado de pregunta.

1. Redactar el contenido en la conversación, no en el sistema de archivos. Componer el README.md con assets/research-template.md —si no hay artefacto vinculado, marcar Impacto en el artefacto como N/A — investigación independiente— y los archivos adicionales que defina el flujo (ver Salida estandarizada).
2. Presentar en el chat el contenido íntegro y literal del README.md del RS —y solo ese archivo—, precedido de su ruta tentativa y su estado propuesto (Ready / Draft). Lo que se muestra debe ser exactamente lo que se escribirá:
   • No resumir. No sustituir el informe por un resumen ejecutivo, una lista de hallazgos clave, una tabla de conclusiones ni una descripción de lo que contiene. Si la plantilla incluye una sección de resumen, esa sección se muestra como parte del contenido completo, nunca en lugar de él.
   • No alterar. No reordenar secciones, no reformular, no recortar citas, no omitir secciones vacías o largas, no «limpiar» el formato para la vista de chat.
   • No abreviar por longitud. Un informe largo se presenta largo, en bloques sucesivos si hace falta. … o «(resto omitido)» no son aceptables.
   • Los archivos complementarios NO se muestran. discovery.md, validation.md, analysis.md y cualquier otro archivo adicional del flujo no se vuelcan en el chat: son documentos de trabajo del RS, no el informe. De ellos se lista únicamente nombre, ruta tentativa, estado propuesto y una línea de qué contienen — la misma información que el README.md ya declara en «Archivos adicionales». El usuario los revisa en disco después de guardar, o los pide explícitamente si quiere verlos antes.
3. Preguntar (herramienta estructurada): «¿La investigación responde tu pregunta?» Opciones: [Sí, guardar] / [Profundizar en un subtema] / [Descartar]. No ofrecer una opción de "ajustar el informe": el ajuste se pide por respuesta libre, donde el usuario ya explica qué cambiar. Dejar explícito en el mensaje que todavía no se ha escrito nada.
   • Sí → Paso 5: escribir en disco el contenido tal como se presentó, con Estado: Ready —o Draft si el flujo declara pendientes abiertos; su referencia dice cuándo aplica.
   • Profundizar → investigación adicional y volver al punto 1 de este paso.
   • Ajuste pedido en respuesta libre → aplicar los cambios y volver a presentar el contenido completo antes de preguntar de nuevo. Nunca escribir una versión que el usuario no ha visto entera.
   • Descartar → el skill termina. No hay nada que borrar, porque nada se escribió.

Analizar issue: no aplican ni el README.md del RS ni el Paso 5. Este flujo presenta su dossier y hace handoff con su propio cierre — ver [references/issue/flow.md](references/issue/flow.md). La regla de presentación íntegra sí le aplica: el dossier se muestra completo, sin resumir.

Paso 5 — Guardar el informe

Solo se llega aquí con la confirmación explícita del Paso 4. Este es el primer y único punto del skill donde se crean carpetas o se escriben archivos del RS-XXX.

0. Verificar la confirmación. Si el usuario no eligió [Sí, guardar] sobre el contenido íntegro ya presentado, no continuar. Si el contenido cambió después de esa presentación, volver al Paso 4 y presentarlo de nuevo entero antes de escribir.
1. Determinar la carpeta base —la que contendrá las carpetas RS-XXX-*— según haya artefacto vinculado o no (ver Salida estandarizada): <carpeta-del-artefacto>/research/ si lo hay, docs/specs/research/ si no. La base ya incluye el segmento research/: no anidarlo dos veces. Si el artefacto vinculado resultó estar archivado, aquí ya no se llega: la regla de artefacto archivado obligó a parar antes.
2. Determinar el siguiente RS-XXX leyendo las carpetas RS-XXX-* existentes en esa base y tomando el mayor número + 1. Empezar en 001 si no hay ninguna.
   • Si la base es docs/specs/research/, escanear también docs/archive/research/ y tomar el mayor de las dos. work-integrate y pr-create archivan ahí las investigaciones sueltas que se quedan sin artefacto activo que las referencie; su número sigue ocupado, y mirar solo la ruta activa haría retroceder el contador y reemitir un RS-XXX ya usado. Ver work-integrate/references/archive.md.
3. Construir el {slug}: descripción corta del tema en kebab-case (p. ej. viabilidad-redis-cache, impacto-refactor-pagos, orm-sequelize-a-prisma).
4. Crear <base>/RS-XXX-{slug}/ y escribir dentro el README.md con su estado (Ready, o Draft si quedan pendientes declarados). Añadir los archivos adicionales del flujo, referenciados desde el README.md. El contenido escrito es literalmente el presentado en el Paso 4, salvo el RS-XXX definitivo si el secuencial cambió entre la presentación y la escritura.
5. Informar la ruta exacta donde se guardó. Si el RS-XXX definitivo difiere del tentativo mostrado en el Paso 4, decirlo.

Flujos multi-archivo — Analizar legado y Analizar migración. Tampoco reservan la carpeta al empezar: el RS-XXX es tentativo durante toda la investigación y el secuencial se revalida aquí, en la escritura. Sus archivos complementarios (discovery.md, validation.md) se componen en la conversación sin volcarlos en el chat y se escriben junto con el README.md, en esta única operación, tras la confirmación del Paso 4. Sus compuertas internas (no crear features con el discovery en Draft, no preparar la validación antes de cerrar el discovery) siguen vigentes: son compuertas de contenido, no de escritura. Si el usuario descarta, no hay carpeta huérfana ni secuencial quemado, porque nunca se creó.

Numeración y nomenclatura

Reglas comunes de identificadores y secuenciales: ${PLUGIN_ROOT}/reference/artifacts.md. Lo específico de los RS:

• Secuencial XXX: tres dígitos, por carpeta base de destino. Leer las carpetas RS-XXX-* existentes y tomar el siguiente número. Cuando la base es docs/specs/research/, el escaneo incluye docs/archive/research/: archivar no libera el número.
• Slug: kebab-case, descriptivo del tema. Máximo 5 palabras.
• Un RS por pregunta de investigación. Si la sesión produce varias, generar un RS por cada una con su propio secuencial. Excepción: una migración con varios proyectos destino escribe un RS en cada uno, con el mismo {slug} y un secuencial común (ver [references/migrate/flow.md](references/migrate/flow.md)) — sigue siendo una sola pregunta de investigación.
• No aplica a Analizar issue, que no genera un RS (ver Salida estandarizada).

Handoffs

Este skill alimenta otros skills pero no los invoca automáticamente salvo donde se indica. El detalle de cada handoff vive en el archivo de referencia de su flujo; aquí queda el mapa general.

Cuando otro skill reciba un RS como insumo, leerlo desde research/RS-XXX-{slug}/README.md (y sus archivos adicionales) antes de ejecutar su propio flujo.

Al cerrar, ofrecer al usuario el handoff correspondiente con la referencia al RS generado (en Analizar issue, con el dossier de bug).

Mapa de referencias

…(truncated)