Redacción de una incidencia
Prepara el texto de una incidencia a partir de lo descrito por el usuario
($ARGUMENTS y la conversación). El usuario copiará el texto en el
gestor de incidencias, donde creará la incidencia y le asignará responsable,
prioridad, versión, etc. Esta habilidad no crea la incidencia en el gestor.
Gestor: solo lectura
En el gestor (Redmine, GitHub, GitLab) el agente solo puede leer las incidencias. No debe nunca modificarlas, ni siquiera si el usuario lo pide:
- nada de creación, modificación, cierre, reapertura o eliminación;
- nada de comentarios, notas, adjuntos, tiempo empleado;
- nada de cambios de estado, responsable, prioridad, versión, etiquetas.
Usa solo peticiones de lectura: curl sin -X ni datos (por lo tanto GET),
gh issue view, gh issue list. Nunca POST, PUT, PATCH, DELETE, ni
comandos como gh issue create, edit, comment, close, reopen,
delete. Si es necesario insertar texto en el gestor, escríbelo en un archivo
en issues/: lo copia el usuario.
1. Carpeta issues
En la raíz del proyecto (raíz del repositorio git, si existe) debe
existir la carpeta issues/ con un .gitignore que ignore todo el
contenido excepto a sí mismo:
*
!.gitignore
Si la carpeta o el .gitignore faltan, créalos. Si el .gitignore
existe con un contenido diferente, no lo modifiques: comunícalo al usuario.
2. Recopilación y verificación de la información
- Clasifica la solicitud: bug, funcionalidad o tarea (mantenimiento, actualización, refactorización, documentación...).
- Verifica lo descrito en el código del proyecto: busca los archivos, las clases, las rutas, las tablas y los comportamientos mencionados, y comprueba que existan y funcionen según lo descrito. Anota los archivos implicados.
- Identifica la información faltante o ambigua, por ejemplo:
- bug: pasos para reproducirlo, comportamiento esperado y actual, entorno (producción, staging, local), mensajes de error o logs;
- funcionalidad: quién la usa, qué debe poder hacer, casos límite, restricciones;
- para todas: criterios para considerar la incidencia resuelta.
- Si falta algo necesario, o si el código no se corresponde con lo descrito, pregunta al usuario antes de escribir. Haz las preguntas todas juntas y solo sobre lo que realmente se necesita.
No propongas ni implementes la solución: la incidencia describe el problema y el resultado esperado. Las notas técnicas solo sirven para orientar a quien trabajará en ella.
3. Escritura del archivo
Escribe el archivo issues/<AAAA-MM-DD>-<slug>.md, donde slug es el
slug del título en minúsculas, con palabras separadas por - y sin
caracteres especiales (máximo 50 caracteres). Si el archivo ya existe,
añade un sufijo -2, -3...
Estructura del archivo:
# <Título breve y específico>
## Contexto
[Dónde se sitúa el problema o la tarea, y por qué es necesaria.]
## Descripción
[Bug: comportamiento actual. Funcionalidad/tarea: lo que hay que hacer.]
## Pasos para reproducir
1. [...]
## Comportamiento esperado
[...]
## Criterios de aceptación
- [ ] [Condición verificable]
## Notas técnicas
- `ruta/del/archivo` — [por qué es relevante]
## Referencias
- [Enlace, incidencias relacionadas, logs, capturas de pantalla]
Reglas:
- Pasos para reproducir solo para bugs; Comportamiento esperado para bugs y funcionalidades. Omite Notas técnicas y Referencias si están vacías.
- La línea
# Títulova en el campo título del gestor; el resto, desde los títulos##hacia abajo, va en la descripción. - Formato CommonMark; código y logs en bloque de código con el lenguaje.
- Idioma: español. Sin emojis.
- Texto conciso y comprensible para quien no haya seguido la conversación: sin referencias a "como se dijo antes" ni a la sesión.
4. Respuesta al usuario
Indica:
- la ruta del archivo creado;
- el título propuesto y el tipo (bug, funcionalidad, tarea);
- que, después de crear la incidencia en el gestor, conviene renombrar el
archivo incluyendo el número de incidencia (por ejemplo
issues/123-<slug>.md): asíopen-issue 123lo encuentra incluso sin acceso al gestor.