g-ki/agent-skills

Tarea de Spike (Investigación)

Responde una pregunta lo suficientemente bien como para tomar una decisión, dentro del tiempo asignado al spike. El entregable es un registro de decisión, no código fusionado.

Entrada

$ARGUMENTS

• Ticket, obligatorio: una clave de gestor de tareas (p. ej., ENG-130) o un ID local (p. ej., T-03) de un ticket con tipo spike. Si no es un spike, detente y señala /implement-task.
• --tasks <archivo>: el archivo de tareas local. Si no se proporciona, busca el archivo *.tasks.md que contenga el ticket en la carpeta de RFC local del proyecto, ignorada por git (p. ej., .rfcs/), luego docs/rfcs/.
• --branch <nombre>: nombre de la rama para un prototipo, si es necesario. De lo contrario, <usuario>/<slug-del-proyecto>/spike-<rama-de-la-tarea>, siguiendo la misma regla de nombre que /implement-task.
• --unattended: iniciado por un orquestador; nadie puede responder preguntas. Nunca preguntes; cuando necesites preguntar, detente y explica en el informe. Trabaja en tu propio árbol de trabajo.

Lee el ticket del gestor de tareas si está publicado (el gestor es la fuente de verdad para su contenido), de lo contrario del archivo de tareas. Los archivos locales de RFC y tareas viven solo en la carpeta principal del proyecto: si estás en un árbol de trabajo, encuéntralo con git worktree list (primera entrada) y léelos allí usando la ruta absoluta. Nunca edites archivos ni ejecutes comandos git en la carpeta principal, excepto para escribir el registro de decisión como se describe a continuación.

1. Enmarca la pregunta

Antes de recopilar cualquier cosa, escribe:

• La pregunta, como una oración que tenga una respuesta ("¿Puede Postgres LISTEN/NOTIFY manejar 2k eventos/s en el tamaño de nuestra instancia?", no "investigar eventos").
• La decisión que desbloquea, y qué tickets dependen de ella.
• Las opciones entre las que se decide, incluyendo "no hacer nada" o la opción más simple cuando sea plausible.
• Criterios de decisión, tomados de la sección DRIVE del RFC cuando sea posible (restricciones, valores, resultados esenciales), para que la evidencia se juzgue en función de lo que el equipo ya acordó que es importante.
• El límite de tiempo del ticket (por defecto: aproximadamente un día de esfuerzo). Hecho significa que la pregunta está respondida o que se ha agotado el tiempo, lo que ocurra primero.

Si el ticket es demasiado vago para enmarcar una pregunta, detente e informa bloqueado con las preguntas que necesitan respuestas.

2. Recopila evidencia, la más barata primero

Detente tan pronto como la evidencia resuelva la pregunta; no investigues por completitud.

1. El código base: patrones existentes, restricciones, intentos previos, comentarios e historial alrededor del área (git log en rutas relevantes).
2. Fuentes primarias: documentación oficial, registros de cambios, notas de versión, rastreadores de problemas de las bibliotecas o servicios involucrados. Prefiérelas sobre publicaciones de blog. Si hay una skill de deep-research disponible y la pregunta necesita investigación externa amplia, úsala.
3. Mide: cuando la lectura no pueda resolverla (rendimiento, compatibilidad, "¿esta API realmente se comporta así?"), construye el prototipo o benchmark más pequeño que responda la pregunta, en la rama de spike, desde la última versión principal. Existe para producir evidencia: sin pruebas más allá de lo que la medición necesita, sin pulir, y nunca se fusiona. Empuja la rama para que la evidencia sea reproducible, pero no abras un PR.

Mantén un registro de cómo sabes cada cosa: medido (lo ejecutaste), documentado (una fuente primaria lo dice) o supuesto (inferencia). Cita enlaces y rutas de archivo.

3. Decide qué recomendar

• Puntúa cada opción según los criterios de decisión, utilizando la evidencia.
• Recomienda una opción, con un nivel de confianza: alto (medido o bien documentado), medio (documentado pero no probado en nuestro contexto), bajo (principalmente inferencia).
• Cuando la confianza es baja, prefiere la opción que sea más barata de revertir, y di qué señal te haría cambiar.
• Si el límite de tiempo se agotó antes de que la pregunta fuera respondida, dílo claramente: informa lo que se sabe y recomienda el siguiente paso más pequeño (un spike de seguimiento más acotado, o un valor predeterminado reversible para continuar).

4. Propón cambios en el backlog

La decisión generalmente cambia el plan. Propón, no apliques:

• Tickets para agregar, en el mismo formato que el archivo de tareas (título, alcance, archivos, criterios de aceptación, dependencias), cada uno de 1 punto de historia.
• Tickets para cambiar (alcance, criterios o dependencias) y tickets para eliminar, cada uno con el motivo.
• Secciones del RFC que necesitan actualización.

5. Escribe el registro e informa

1. Escribe el registro de decisión usando templates/decision.md como <nombre-del-rfc>.<id-del-ticket>.decision.md junto al archivo de tareas en la carpeta principal del proyecto (el único archivo que escribes allí). Es un archivo local no rastreado, como el RFC.
2. Si el ticket está publicado, publica un resumen breve en el issue del gestor de tareas: la pregunta, la recomendación y confianza, y la evidencia clave en tres a cinco líneas, claramente marcado como propuesto, pendiente de aprobación.
3. Si estás trabajando directamente con el usuario, establece el estado del ticket a decision-proposed en el archivo de tareas, guíalo a través de la recomendación y pídele que apruebe, elija otra opción o extienda el spike. En modo desatendido, deja los estados al orquestador.
4. Finaliza con el informe:

RESULTADO: decision-proposed | inconclusive | blocked
TICKET: <id local> / <clave del gestor o "unpublished">
REGISTRO: <ruta absoluta al registro de decisión>
RECOMENDACIÓN: <una línea> (confianza: alta | media | baja)
PROTOTIPO: <rama o "none">
NOTAS: <cambios en el backlog en una línea: +N tickets, ~N cambiados, -N eliminados; o por qué está bloqueado>