rauleburro Jira Task Workflow
Guía el proceso completo de implementación de una tarea individual de Jira, desde el análisis hasta el código con tests. El valor está en no saltar al código antes de entender el problema — cada fase construye sobre la anterior.
Flujo general
1. Obtener ticket → 2. Analizar código/docs → 3. Diagrama arquitectura
|
v
4. Ping-pong con usuario → 5. Modo Planning → 6. Setup rama + worktree
|
v
7. Implementar + Tests
Fase 1: Obtener el ticket de Jira
Cuando el usuario pase un ID de Jira (formato PROYECTO-NUMERO):
Obtención del ticket
Usar herramientas MCP de Jira si están disponibles (mcp__atlassian__jira_get_issue). Si no hay MCP, usar la API REST como fallback:
curl -s -u "$JIRA_USER_EMAIL:$JIRA_API_TOKEN" \
-H "Content-Type: application/json" \
"$JIRA_BASE_URL/rest/api/3/issue/PROYECTO-123" | python3 -m json.tool
Qué extraer del ticket
- Título y descripción completa
- Tipo (bug, feature, improvement, task)
- Prioridad y story points si existen
- Criterios de aceptación (suelen estar en la descripción)
- Subtareas vinculadas
- Comentarios relevantes (pueden tener contexto adicional)
Presenta un resumen estructurado al usuario para confirmar que entendiste la tarea correctamente.
Fase 2: Analizar código fuente y documentación
Documentación existente
Busca documentación en el proyecto (docs/, Docs/, o la carpeta que use el proyecto). Lee documentos relacionados con el área que toca la tarea: arquitectura, decisiones previas, specs, guías.
Código fuente
Usa el agente Explore para análisis profundo del código relacionado:
- Modelos/tipos involucrados y sus relaciones
- Componentes, páginas, o API routes afectados
- Tests existentes en el área
- Middleware, hooks, o código auxiliar relevante
- Dependencias entre módulos
El objetivo es entender el estado actual antes de proponer cambios. No propongas nada todavía — primero entiende.
Fase 3: Diagrama de arquitectura actual (ASCII)
Genera un diagrama ASCII de la arquitectura del área afectada. El diagrama es un apoyo visual — el texto descriptivo es donde está el valor real.
+------------------+ +------------------+ +------------------+
| | | | | |
| Componente A +------>+ Componente B +------>+ Componente C |
| | | | | |
+------------------+ +--------+---------+ +------------------+
|
v
+------------------+
| |
| Componente D |
| |
+------------------+
Contenido obligatorio junto al diagrama
- Descripción de cada componente: Qué hace, qué archivos lo componen, qué modelos usa
- Flujo de datos: Cómo se mueven los datos entre componentes
- Puntos de integración: APIs externas, servicios, base de datos
- Estado actual vs. lo que pide la tarea: Qué existe y qué falta
Fase 4: Ping-pong con el usuario
Esta es la fase más importante. Aquí se toman las decisiones de diseño.
Cómo funciona
- Presenta tu análisis: qué entendiste del ticket, qué encontraste en el código, y tu propuesta de implementación
- El usuario responde con feedback, preguntas, correcciones, o aprobación
- Itera hasta alinearse en:
- Qué se va a implementar exactamente
- Cómo se va a implementar (enfoque técnico)
- Qué NO se va a implementar (límites del alcance)
- Qué riesgos existen y cómo mitigarlos
Reglas del ping-pong
- Sé directo: "propongo X porque Y", no "podríamos considerar tal vez..."
- Máximo 2-3 opciones con pros/contras claros y tu recomendación
- Cuando el usuario decida, confirma y avanza. No re-preguntes lo mismo
- Si la tarea es más grande de lo estimado, dilo y propón cómo dividirla
Fase 5: Modo Planning
Una vez alineados, entra en modo planning (EnterPlanMode) para crear el plan de implementación.
Estructura del plan
- Resumen de la tarea (1-2 oraciones)
- Decisiones tomadas en el ping-pong
- Iteraciones (si la tarea es compleja)
- Pasos de implementación por iteración:
- Archivos a crear/modificar
- Modelos/migraciones si aplica
- Componentes/páginas/API routes
- Lógica de negocio
- Tests requeridos (ver Fase 6)
Archivo de iteración
Crear en docs/<area-tarea>/iteraciones/ (o la carpeta de docs del proyecto):
# Iteración NN - <Descripción>
**Ticket**: PROYECTO-XXX
**Fecha**: YYYY-MM-DD
**Estado**: En progreso | Completada
## Objetivo
Qué se busca lograr en esta iteración.
## Decisiones tomadas
- Decisión 1: razón
- Decisión 2: razón
## Cambios realizados
- [ ] Archivo 1: descripción del cambio
- [ ] Archivo 2: descripción del cambio
## Tests
- [ ] Test 1: qué verifica
- [ ] Test 2: qué verifica
## Notas para la siguiente iteración
Qué queda pendiente o qué tener en cuenta.
Fase 6: Setup — Rama, worktree y estado Jira
Antes de escribir código, preparar el entorno de trabajo aislado.
1. Crear rama desde main
git checkout main && git pull
git checkout -b feature/<KEY>-<slug> # ej. feature/IRB-365-restrict-payment-filter
2. Crear worktree (si se trabaja con agentes en paralelo)
Si se va a usar un agente con isolation: "worktree", el worktree se crea automáticamente. Si se trabaja directamente, la rama creada en el paso anterior es suficiente.
3. Mover la tarea a "En curso" en Jira
Usar MCP de Jira para transicionar el ticket al estado "En curso" / "In Progress":
mcp__atlassian__jira_transition_issue(issue_key, transition_name="En curso")
Esto señaliza al equipo que alguien está trabajando activamente en la tarea.
Fase 7: Implementación + Tests
Git workflow
- Rama ya creada en Fase 6:
feature/<KEY>-<slug> - Commits con formato:
type(scope): description [KEY] - No hacer commit con tests fallando o lint errors
Tests — parte obligatoria, no opcional
Cobertura mínima: 80% del código nuevo/modificado (idealmente mayor)
Qué cubrir
- Modelos/tipos: Creación, validaciones, métodos custom
- API routes/Server actions: Respuestas HTTP, validación de input, errores
- Componentes: Renderizado, props, interacciones de usuario
- Edge cases: Datos vacíos, límites, errores esperados
Ejecución de tests
Detectar automáticamente el stack del proyecto y usar los comandos correctos:
# Next.js / React (Jest)
npm run test -- --coverage
# Django / Python
docker compose exec web python manage.py test <app>
docker compose exec web coverage run --source='<app>' manage.py test <app>
# Otros — usar lo que tenga configurado el proyecto
Si la cobertura está por debajo del 80%, identificar qué falta y agregarlo.
Validación pre-commit
Antes de hacer commit, ejecutar:
npm run lint # o el linter del proyecto
npm run test # todos deben pasar
npm run build # debe compilar
Al finalizar — Mover a "Code Review" en Jira
Una vez que el código está commiteado, los tests pasan y la validación es exitosa, transicionar el ticket a "Code Review":
mcp__atlassian__jira_transition_issue(issue_key, transition_name="Code Review")
Esto indica al equipo que la tarea está lista para ser revisada.
Documentación
Qué documentar
Genera documentación en la carpeta de docs del proyecto cuando la tarea introduce:
- Arquitectura nueva o cambios significativos
- Decisiones de diseño no obvias
- Configuración necesaria
- Flujos de datos complejos
Convención
Seguir el estilo de la documentación existente. La documentación debe ser útil para alguien que no participó en las decisiones.
Resumen visual
USUARIO PASA ID JIRA
|
v
+--[1. Obtener ticket]--+
| - Descripción |
| - Criterios |
+----------+-------------+
|
v
+--[2. Analizar código]--+
| - Docs existentes |
| - Código fuente |
| - Tests existentes |
+----------+--------------+
|
v
+--[3. Diagrama ASCII]---+
| - Arquitectura actual |
| - Texto descriptivo |
+----------+--------------+
|
v
+--[4. Ping-pong]--------+
| - Propuesta |
| - Feedback | <--- Loop hasta alineamiento
| - Decisiones |
+----------+--------------+
|
v
+--[5. Planning]---------+
| - Plan de implementación|
| - Iteraciones |
+----------+--------------+
|
v
+--[6. Setup]-------------+
| - Rama desde main |
| - Worktree si aplica |
| - Jira → "En curso" |
+----------+--------------+
|
v
+--[7. Implementar]------+
| - Código + Tests |
| - 80% coverage mínimo |
| - lint + build OK |
| - Jira → "Code Review" |
+-------------------------+