--- version: 1.0.0 updated: 2026-03-13 tags: [issues, workspace, batch, orchestration] --- # Command: create-batch Crea múltiples issues en workspaces hijos a partir de un archivo YAML, pidiendo confirmación antes de proceder. ## Para el usuario ### Cuándo usar este comando Usar cuando necesites crear la misma issue (o issues relacionadas) en múltiples workspaces simultáneamente. Ideal para migraciones, estandarizaciones o lanzamientos coordinados. ### Sintaxis ```bash /issues:create-batch ``` ### Formato YAML esperado ```yaml # migration-issues.yaml issues: - workspace: auth-service number: "0010" slug: migrate-to-v2-schema title: Migrate to v2 database schema description: Update database schema to v2 with new user fields tags: [database, migration] status: pending - workspace: payment-service number: "0008" slug: migrate-to-v2-schema title: Migrate to v2 database schema description: Update database schema to v2 with new payment fields tags: [database, migration] status: pending - workspace: notification-service number: "0005" slug: migrate-to-v2-schema title: Migrate to v2 database schema description: Update database schema to v2 with new notification fields tags: [database, migration] status: pending ``` **Campos obligatorios por entry:** `workspace`, `number`, `slug`, `title` **Campos opcionales:** `description`, `tags`, `status` (default: `pending`) **Restricciones de formato:** - `number`: exactamente 4 dígitos opcionalmente seguidos de una letra minúscula (ej: `0001`, `0012a`) - `slug`: lowercase alfanumérico con guiones, sin guiones al inicio o final (ej: `implement-auth`) - `status`: `pending`, `in_progress`, o `completed` ### Ejemplos **Ejemplo 1: Creación batch de migración** ```bash /issues:create-batch migration-issues.yaml ``` Crea la misma issue de migración en tres workspaces diferentes. **Ejemplo 2: Onboarding de nuevos servicios** ```bash /issues:create-batch new-services-setup.yaml ``` ## Para Claude ### Precondiciones Verificar antes de ejecutar: - [ ] El argumento del comando es un path a un archivo YAML - [ ] El archivo YAML existe y es legible - [ ] `dev/feature_flags.json` tiene `centralized_issue_orchestration` habilitado (opcional, advertir si no) ### Inputs - `yamlPath`: path al archivo YAML (argumento obligatorio del comando) Si no se proporciona el path, solicitarlo al usuario. ### Flujo obligatorio #### 1. Leer y validar el archivo YAML Leer el archivo YAML indicado y parsearlo. Verificar: - El archivo existe - El YAML es sintácticamente válido - La estructura tiene clave `issues` con al menos una entrada - Cada entrada tiene campos obligatorios (`workspace`, `number`, `slug`, `title`) Si hay errores de validación, mostrarlos todos antes de detenerse. #### 2. Mostrar plan de creación Mostrar al usuario lo que se va a crear: ``` Plan de creación: workspace-1: 0010-migrate-to-v2-schema workspace-2: 0008-migrate-to-v2-schema workspace-3: 0005-migrate-to-v2-schema Total: 3 issues en 3 workspaces ``` #### 3. Verificar workspaces disponibles Para cada workspace en el YAML, verificar que existe en `config.ReposBasePath`. Si algún workspace no existe, advertir al usuario pero no detener el proceso (se reportará como fallo en el reporte final). #### 4. Pedir confirmación ``` ¿Proceder con la creación? (s/n): ``` - Si responde afirmativo → continuar - Si responde negativo → **STOP**: "Operación cancelada. No se crearon issues." #### 5. Ejecutar creación via app.CreateIssuesBatchCommand Invocar la lógica app layer para crear cada issue: - Validar spec con `core.ValidateIssueSpec()` - Verificar workspace existe con `shell.WorkspaceExists()` - Verificar issue no existe con `shell.IssueExists()` - Crear issue con `shell.CreateIssueFile()` El proceso continúa aunque fallen issues individuales (partial failure). #### 6. Mostrar reporte detallado ``` Creando issues... ✓ auth-service/0010-migrate-to-v2-schema.md ✓ payment-service/0008-migrate-to-v2-schema.md ✗ notification-service: workspace no existe Resultado: 2/3 issues creadas exitosamente 1 fallo(s): - notification-service/0005-migrate-to-v2-schema: workspace no existe ``` #### 7. Si hubo fallos, indicar cómo resolver Para cada fallo: - Si es "workspace no existe": `dataforge workspace create ` - Si es "issue ya existe": verificar con `ls workspaces//dev/issues/` - Si es error de validación: corregir el YAML y reintentar ### Verificación final Informar al usuario: ``` ✓ Batch completado: X/Y issues creadas Archivos creados: workspaces//dev/issues/-.md ... Para ejecutarlas en paralelo: /issues:execute-parallel ``` ## Convenciones - **Partial failure**: nunca abortar el batch por fallos individuales — reportar al final - **Confirmación obligatoria**: siempre pedir confirmación antes de crear - **Sin auto-commit**: no hacer commit automático, dejar que el usuario gestione git - **Idempotente**: si el issue ya existe, reportar como fallo, no sobrescribir ## Troubleshooting ### Error: "YAML parse error" **Causa:** El archivo YAML tiene errores de sintaxis. **Solución:** ```bash # Verificar sintaxis con un linter cat batch.yaml # Revisar indentación y caracteres especiales ``` Errores comunes: - Números sin comillas: `number: 0001` → `number: "0001"` - Tags sin lista: `tags: backend,auth` → `tags: [backend, auth]` ### Error: "workspace X does not exist" **Causa:** El workspace no está creado en el sistema. **Solución:** ```bash # Crear el workspace primero /workspace:create-repo # O importarlo si ya existe en Gitea /workspace:import-repo ``` ### Error: "issue already exists" **Causa:** Ya existe un issue con ese número en el workspace. **Solución:** ```bash # Ver issues existentes en el workspace ls workspaces//dev/issues/ # Usar un número diferente o verificar si ya está implementado ``` ### Error: "batch file contains no issues" **Causa:** El archivo YAML está vacío o tiene `issues: []`. **Solución:** Agregar al menos una entrada al archivo YAML con todos los campos obligatorios. ## Reglas críticas - **Confirmación obligatoria**: nunca crear sin confirmación del usuario - **Partial failure permitido**: continuar aunque fallen issues individuales - **Sin sobrescritura**: nunca sobrescribir issues existentes - **Validación completa**: validar YAML y specs antes de mostrar el plan - **Reporte detallado**: siempre mostrar qué se creó y qué falló - **Sin auto-commit**: dejar git al usuario