repo_Claude/.claude/commands/issues/create-batch.md

version, updated, tags

version	updated	tags
1.0.0	2026-03-13	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

/issues:create-batch <path-to-yaml>

Formato YAML esperado

# 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

/issues:create-batch migration-issues.yaml

Crea la misma issue de migración en tres workspaces diferentes.

Ejemplo 2: Onboarding de nuevos servicios

/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 <nombre>
• Si es "issue ya existe": verificar con ls workspaces/<nombre>/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/<workspace>/dev/issues/<number>-<slug>.md
  ...

Para ejecutarlas en paralelo: /issues:execute-parallel <plan.yaml>

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:

# 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:

# Crear el workspace primero
/workspace:create-repo <nombre>
# O importarlo si ya existe en Gitea
/workspace:import-repo <nombre>

Error: "issue already exists"

Causa: Ya existe un issue con ese número en el workspace.

Solución:

# Ver issues existentes en el workspace
ls workspaces/<nombre>/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