rai backlog

Gestiona ítems del backlog mediante ProjectManagementAdapter. El adapter (Jira, filesystem, etc.) se selecciona automáticamente o mediante -a.

Configuración¶

Requisitos de Máquina¶

El adapter de Jira requiere Atlassian CLI (ACLI) instalado y autenticado.

# Verificar que ACLI está instalado
acli --version

# Autenticar (abre el navegador para OAuth)
acli jira auth login --site your-org.atlassian.net

Para configuración detallada, configuración multi-instancia y solución de problemas, consulta Configurar Integraciones.

Configuración del Proyecto¶

.raise/jira.yaml — Requerido. Define instancias de Jira y enrutamiento de proyectos.

# .raise/jira.yaml (mínimo)
default_instance: myorg

instances:
  myorg:
    site: myorg.atlassian.net
    email: you@myorg.com
    projects: [PROJ]

projects:
  PROJ:
    instance: myorg
    name: My Project

Selección de Adapter¶

Orden de resolución:

Flag -a <name> en el comando — apunta a un solo adapter directamente.
-a all — compone explícitamente todos los adapters configurados.
Sin flag — detección automática. Con exactamente un adapter registrado, se usa directamente. Con 2+ adapters registrados (por ejemplo los adapters locales siempre activos filesystem/sqlite más un remoto configurado como jira), se auto-componen en un CompositeBacklogAdapter: las escrituras van a cada adapter local y a cada remoto configurado; las lecturas prefieren el remoto cuando está disponible.

No existe un adapter por defecto a nivel de manifest — la detección automática + auto-composición cubre el caso común local+remoto sin configuración adicional.

Notas sobre Jira¶

La búsqueda requiere JQL¶

rai backlog search pasa la cadena de consulta directamente a la API de búsqueda de Jira. El texto plano no funciona — debes usar JQL.

# incorrecto — no devuelve resultados
rai backlog search "PROJ-302"

# correcto — JQL
rai backlog search "issue = PROJ-302"
rai backlog search "project = PROJ AND status = 'In Progress'"

Si la clave de tu proyecto es una palabra clave reservada de JQL, entre comillas: project = "MYPROJECT".

Nombres de estado para `transition`¶

Los nombres de estado se convierten por convención: in-progress → In Progress, done → Done. Usa minúsculas con guiones:

Nombre de estado	Estado en Jira
`backlog`	Backlog
`selected`	Selected For Development
`in-progress`	In Progress
`done`	Done

rai backlog transition PROJ-123 in-progress
rai backlog transition PROJ-123 done

`rai backlog create`¶

Crea un nuevo ítem en el backlog.

Argumento	Descripción
`SUMMARY`	Título del issue (requerido)

Flag	Corta	Descripción
`--project`	`-p`	Clave del proyecto, ej. `PROJ` (requerido)
`--type`	`-t`	Tipo de issue. Por defecto: `Task`
`--labels`	`-l`	Etiquetas separadas por comas
`--parent`		Clave del issue padre
`--description`	`-d`	Descripción del issue (markdown)
`--adapter`	`-a`	Nombre del adapter
`--format`	`-f`	Formato de salida: `human`, `agent`. Por defecto: `human`

# Crear una tarea
rai backlog create "Add CLI docs" -p PROJ

# Crear con etiquetas y padre
rai backlog create "Fix login bug" -p PROJ -t Bug -l "priority,frontend" --parent PROJ-100

`rai backlog get`¶

Recupera los detalles de un ítem del backlog.

Argumento	Descripción
`KEY`	Clave del issue, ej. `PROJ-123` (requerido)

Flag	Corta	Descripción
`--adapter`	`-a`	Nombre del adapter

rai backlog get PROJ-123

`rai backlog get-comments`¶

Recupera los comentarios de un ítem del backlog.

Argumento	Descripción
`KEY`	Clave del issue (requerido)

Flag	Corta	Descripción
`--limit`	`-n`	Máximo de comentarios. Por defecto: `10`
`--adapter`	`-a`	Nombre del adapter

rai backlog get-comments PROJ-123
rai backlog get-comments PROJ-123 --limit 5

`rai backlog search`¶

Busca ítems en el backlog. El formato de consulta es específico del adapter (JQL para Jira).

Argumento	Descripción
`QUERY`	Consulta de búsqueda (requerido)

Flag	Corta	Descripción
`--limit`	`-n`	Máximo de resultados. Por defecto: `50`
`--adapter`	`-a`	Nombre del adapter
`--format`	`-f`	Formato de salida: `human`, `agent`. Por defecto: `human`

# Búsqueda JQL
rai backlog search "project = PROJ AND status = 'In Progress'"

# Limitar resultados
rai backlog search "project = PROJ" -n 10

`rai backlog transition`¶

Transiciona un ítem del backlog a un nuevo estado.

Argumento	Descripción
`KEY`	Clave del issue (requerido)
`STATUS`	Estado objetivo (requerido)

Flag	Corta	Descripción
`--adapter`	`-a`	Nombre del adapter

rai backlog transition PROJ-123 in-progress
rai backlog transition PROJ-123 done

`rai backlog batch-transition`¶

Transiciona múltiples ítems del backlog a la vez.

Argumento	Descripción
`KEYS`	Claves de issue separadas por comas (requerido)
`STATUS`	Estado objetivo (requerido)

Flag	Corta	Descripción
`--adapter`	`-a`	Nombre del adapter

rai backlog batch-transition PROJ-1,PROJ-2,PROJ-3 done

`rai backlog update`¶

Actualiza campos de un ítem del backlog.

Argumento	Descripción
`KEY`	Clave del issue (requerido)

Flag	Corta	Descripción
`--summary`	`-s`	Nuevo resumen
`--labels`	`-l`	Etiquetas separadas por comas
`--priority`		Nombre de la prioridad
`--assignee`		Identificador del asignado
`--adapter`	`-a`	Nombre del adapter

rai backlog update PROJ-123 -s "Updated title" -l "urgent"
rai backlog update PROJ-123 --priority High --assignee alice

`rai backlog link`¶

Vincula dos ítems del backlog.

Argumento	Descripción
`SOURCE`	Clave del issue origen (requerido)
`TARGET`	Clave del issue destino (requerido)
`LINK_TYPE`	Tipo de vínculo, ej. `blocks`, `relates` (requerido)

Flag	Corta	Descripción
`--adapter`	`-a`	Nombre del adapter

rai backlog link PROJ-100 PROJ-101 blocks
rai backlog link PROJ-200 PROJ-201 relates

`rai backlog comment`¶

Añade un comentario a un ítem del backlog.

Argumento	Descripción
`KEY`	Clave del issue (requerido)
`BODY`	Texto del comentario en markdown (requerido)

Flag	Corta	Descripción
`--adapter`	`-a`	Nombre del adapter

rai backlog comment PROJ-123 "Implementation complete, ready for review."

`rai backlog sync`¶

Regenera governance/backlog.md desde un adapter remoto.

Flag	Corta	Descripción
`--project`	`-p`	Filtro de clave de proyecto (ej. `PROJ`)
`--adapter`	`-a`	Nombre del adapter

rai backlog sync -p PROJ

`rai backlog pending-ops`¶

Inspecciona y gestiona el diario de operaciones pendientes — la cola de operaciones del backlog que fallaron al sincronizarse con un adapter remoto (ej. Jira) y están en espera de reintento.

`rai backlog pending-ops list`¶

Lista las operaciones pendientes activas o en dead-letter.

Flag	Corta	Descripción
`--dead`		Muestra las ops en dead-letter en lugar de la cola activa
`--format`	`-f`	Formato de salida: `human` (por defecto), `agent`

# Cola activa (ops en espera de reintento)
$ rai backlog pending-ops list
0 ops queued

# Cola dead-letter (ops que agotaron todos los reintentos)
$ rai backlog pending-ops list --dead
2 dead-letter ops:
  50c9f836f47e  transition_issue  RAISE-4000  2026-05-06T04:33:24+00:00  (5 attempts)
  5bf892ffbe3c  transition_issue  RAISE-4017  2026-05-06T04:48:21+00:00  (5 attempts)

`rai backlog pending-ops count`¶

Imprime el número de operaciones pendientes activas. Útil para scripts y verificaciones de estado.

$ rai backlog pending-ops count
0

`rai backlog pending-ops purge`¶

Elimina ops de la cola activa.

Flag	Corta	Descripción
`--id`		Elimina solo la op con este ID
`--yes`	`-y`	Omite la confirmación

# Limpiar todas las ops activas (pide confirmación)
$ rai backlog pending-ops purge
3 ops queued. Purge all? [y/N]: y
Purged 3 ops.

# Limpiar una op específica por ID
$ rai backlog pending-ops purge --id 50c9f836f47e
Removed op 50c9f836f47e (transition_issue RAISE-4000)

# Omitir confirmación (útil en scripts)
$ rai backlog pending-ops purge -y

Las ops en dead-letter no se pueden limpiar con este comando

purge solo limpia la cola activa (.raise/sync/backlog-pending-ops.jsonl).

Las ops en dead-letter viven en un archivo separado (.raise/sync/backlog-dead-letter.jsonl) y no se eliminan con purge. Para limpiar las entradas dead-letter, elimina o edita ese archivo directamente:

# Limpiar todas las ops dead-letter
rm .raise/sync/backlog-dead-letter.jsonl

# O inspeccionar primero, luego eliminar
rai backlog pending-ops list --dead
rm .raise/sync/backlog-dead-letter.jsonl

¿Por qué terminan las ops en dead-letter? Cuando una operación remota (ej. una transición de Jira) falla, RaiSE la encola para reintento. Después de 5 fallos consecutivos, mueve la op a dead-letter para evitar bucles infinitos de reintentos. Causa común: un error tipográfico en el nombre del estado (ej. "commited" en lugar de "committed").

Ver también: rai adapter

rai backlog

Configuración¶

Requisitos de Máquina¶

Configuración del Proyecto¶

Selección de Adapter¶

Notas sobre Jira¶

La búsqueda requiere JQL¶

Nombres de estado para transition¶

rai backlog create¶

rai backlog get¶

rai backlog get-comments¶

rai backlog search¶

rai backlog transition¶

rai backlog batch-transition¶

rai backlog update¶

rai backlog link¶

rai backlog comment¶

rai backlog sync¶

rai backlog pending-ops¶

rai backlog pending-ops list¶

rai backlog pending-ops count¶

rai backlog pending-ops purge¶