investigate

Visión general de la skill investigate

Qué hace la skill investigate

La skill investigate sirve para depuración sistemática y análisis de causa raíz cuando algo está roto, es inestable o se comporta de forma distinta a la esperada. Está pensada para personas que necesitan más que un parche rápido: si quieres entender por qué ocurre un error, qué cambió y qué corrección es segura, investigate ayuda a estructurar ese trabajo.

Quién debería usarla

Usa la skill investigate para revisión de código, triaje de incidentes, corrección de errores y situaciones de “ayer funcionaba”. Encaja especialmente bien cuando necesitas que un agente deje de adivinar, reúna evidencia y avance desde los síntomas hacia una causa confirmada antes de cambiar código.

Por qué destaca

Su principal diferencia es la regla de “no hay correcciones sin causa raíz”. Eso hace que la skill investigate sea más disciplinada que un prompt genérico de depuración: empuja el flujo de trabajo hacia investigación, análisis, hipótesis e implementación, en lugar de saltar directamente a editar. También admite activación proactiva, algo útil en flujos con agentes, donde la skill debe activarse en cuanto aparecen errores o stack traces.

Cómo usar la skill investigate

Instálala e invócala

Instala la skill investigate con:

npx skills add garrytan/gstack --skill investigate

Úsala cuando tu prompt describa con claridad un estado de fallo, como un stack trace, un error 500, una regresión o una salida inesperada. Para obtener mejores resultados, nombra el síntoma, dónde aparece y cómo debería verse el funcionamiento correcto.

Da la entrada inicial correcta

Un buen prompt para usar investigate incluye:

• el mensaje de error exacto o un fragmento del log
• el comando, endpoint o acción de usuario que lo dispara
• qué cambió recientemente
• lo que ya comprobaste
• el impacto y la urgencia

Ejemplo: “Investiga por qué npm test ahora falla en CI después del último merge. Compara main vs. HEAD, revisa los cambios recientes en el middleware de auth y no propongas cambios de código hasta confirmar la causa raíz.”

Lee primero los archivos correctos

Empieza por SKILL.md y después inspecciona SKILL.md.tmpl para ver el comportamiento plantillado o la lógica de enrutamiento. Como este repositorio no tiene carpetas separadas rules/, resources/ ni scripts/, el valor principal está en el propio archivo de la skill y en cualquier referencia en línea que incluya. Para investigate for Code Review, presta especial atención al lenguaje de activación y a los límites de las operaciones seguras antes de editar.

Consejos de flujo de trabajo que mejoran el resultado

Trata investigate como un flujo de decisión, no como un chat libre. Pide al agente que:

1. identifique el modo de fallo,
2. reúna evidencia de apoyo,
3. formule una o dos hipótesis comprobables,
4. verifique la causa más probable,
5. implemente la corrección más pequeña y segura.

Si omites el paso 1, la skill puede seguir generando análisis, pero será menos útil para revisión de código o respuesta a incidentes.

Preguntas frecuentes sobre la skill investigate

¿investigate es solo para bugs?

No. La skill investigate también encaja en regresiones, despliegues fallidos, integraciones rotas y cambios de comportamiento poco claros. Si la tarea es “averigua por qué está pasando esto”, investigate suele ser el mejor punto de partida.

¿En qué se diferencia de un prompt normal?

Un prompt normal puede pedir una corrección de inmediato. La skill investigate es más estructurada: obliga primero a pensar en la causa raíz, lo que reduce ediciones frágiles y hace que el cambio final sea más fácil de defender en una revisión de código.

¿investigate es buena para principiantes?

Sí, si la persona puede aportar un síntoma y algo de contexto. Los principiantes suelen beneficiarse de la skill porque reduce la improvisación, pero aun así necesitan compartir evidencia concreta, como logs, pasos para reproducirlo o un comando fallido.

¿Cuándo no debería usarla?

No uses investigate cuando ya sepas exactamente qué cambio quieres, o cuando estés haciendo una edición de contenido sencilla sin ningún fallo que diagnosticar. En esos casos, un prompt de tarea más simple es más rápido.

Cómo mejorar la skill investigate

Aporta evidencia, no solo una queja

La mayor mejora de calidad viene de entradas más precisas. En lugar de “la app está rota”, proporciona la petición que falla, el texto del error, la ruta del archivo, el entorno y el último estado que funcionaba bien. La skill investigate rinde mejor cuando puede anclar cada hipótesis en evidencia observable.

Reduce el espacio de búsqueda

Si el problema está en Code Review, identifica el subsistema probable y la ventana de cambios. Por ejemplo: “Céntrate en auth, solo en los cambios de los dos últimos commits, y verifica si el bug se reproduce en staging.” Eso evita que investigate se disperse demasiado y aumenta la probabilidad de encontrar rápido la causa raíz.

Itera después del primer intento

Si la primera respuesta no es concluyente, pide una investigación más ajustada en lugar de una reescritura más amplia. Buenos seguimientos son: “Enumera las tres hipótesis principales con niveles de confianza”, “Muestra qué evidencia refutaría cada una” o “Traza el fallo desde la entrada hasta la salida y detente antes de programar”.