Operación · Solución de problemas

Solución de problemas

Síntomas, causa y siguiente paso para los fallos habituales del arnés y del CLI.

diez síntomas · causa · siguiente paso

La personalización sigue pendiente

rei init despliega el esqueleto con marcadores REI:PENDIENTE en la documentación del proyecto. Mientras queden marcadores, rei init status informa de los documentos pendientes y sale con 1: los agentes trabajarían con reglas genéricas.

  1. Ejecuta rei init status para ver qué documentos faltan.
  2. Abre /personalize en OpenCode o Claude Code, o pide «personaliza mi proyecto» para que el Initializer conduzca la entrevista.
  3. Revisa que AGENTS.md y .rei/docs/project/ describan tu repositorio y no el esqueleto.
  4. Repite rei init status: debe salir 0 cuando no quede nada pendiente.

rei check falla

rei check ejecuta sus comprobaciones del arnés y los checks declarados en .rei/config.json. Sale con 1 si hay al menos un [FAIL] o si un check del proyecto falla; el código 2 está reservado al uso incorrecto.

  1. Lee la salida: distingue un fallo del arnés de un check del proyecto.
  2. Si falla un check, ejecuta su comando por separado y corrige la causa.
  3. Comprueba que el check esté bien declarado: id, description y command como array.
  4. Repite rei check --quiet hasta obtener 0. No desactives el check para que pase.

Más de un Work Item en in_progress

El arnés solo admite un Work Item activo. rei status set <id> in_progress rechaza un segundo Work Item, también con --force; rei check, rei doctor y rei items status fallan si detectan más de uno.

  1. Ejecuta rei items status y localiza el Work Item marcado con << ACTIVO.
  2. Cierra el activo (review o done), bloquéalo o termina su revisión.
  3. Confirma que ya no queda ninguno en in_progress.
  4. Inicia el siguiente Work Item solo cuando el anterior haya salido del estado.

La sesión no inicia

rei session start <id> <tipo> solo crea la sesión si el Work Item existe, el tipo coincide con meta.json y su estado es pending. En cualquier otro caso rechaza con causa y siguiente paso sin escribir current.md.

  1. Ejecuta rei item show <id> para ver el tipo y el estado reales.
  2. Si el tipo no coincide con el argumento, repite el comando con el tipo de meta.json.
  3. Si el estado es ready, no reinicies: aprueba la planificación o pide cambios.
  4. Si está en in_progress, review o changes_requested, retoma la sesión existente con rei item show <id>.
  5. Si está en done o blocked, crea un Work Item nuevo con rei new.

gh ausente o sin autenticación

La integración con GitHub Issues se apoya en gh para las acciones reales; el CLI rei nunca llama a GitHub. Si gh no está instalado o no tiene sesión, el mensaje lo dice con causa y siguiente paso. Son avisos que no bloquean rei github: el comando sale 0.

  1. Instala GitHub CLI y comprueba que gh está en el PATH.
  2. Ejecuta gh auth login y después gh auth status.
  3. Ejecuta rei github status para ver el estado offline de la configuración y la disponibilidad de gh.
  4. Repite la acción de GitHub Issues solo cuando gh responda con una sesión válida.

El visor no abre o su dirección local no responde

rei view sirve el visor en local. Sin modo se queda en primer plano hasta Ctrl+C; --open arranca o reutiliza el servidor en segundo plano y abre el navegador sin bloquear. Si la página no responde, el servidor de fondo pudo quedar parado o haber perdido su registro temporal.

  1. Ejecuta rei view <id> --open para arrancar o reutilizar el servidor y abrir el navegador.
  2. Si sigue sin responder, detén el servidor con rei view --stop y vuelve a abrirlo.
  3. Sin <id>, el visor usa el Work Item de la sesión activa; comprueba que exista con rei session.
  4. Revisa viewer.autoOpenOnReady si esperabas que se abriera en la puerta de aprobación.

Checksum inválido al actualizar

rei update descarga la última release, verifica el SHA-256 del archive contra checksums.txt y solo entonces reemplaza el binario. Un checksum inválido, un fallo de red o un error de permisos abortan la actualización con código 1 y no dejan el binario degradado.

  1. Ejecuta rei update --check para confirmar la versión disponible sin descargar.
  2. Repite rei update cuando la red esté estable.
  3. Si el fallo de integridad persiste, descarga el archive de la página de releases y verifica su SHA-256 contra checksums.txt antes de reemplazar el binario.

El proyecto no usa git

git no es obligatorio: el workflow sigue funcionando en modo lectura. Lo que se pierde es la revisión acotada al diff y el registro de commits en meta.json. rei check inicializa git automáticamente si falta.

  1. Ejecuta rei check: crea la estructura e inicializa git si no existe.
  2. Si decides usar git, confirma que el repositorio tiene un commit inicial antes de aprobar un Work Item.
  3. Sin git, base_commit y last_review_commit quedan vacíos; el flujo no se bloquea por ello.
  4. Con git, registra los commits antes de solicitar revisión para que rei review-diff acote el diff.

El síntoma no está aquí

Esta página cubre los fallos que documentan la guía de uso y los documentos del arnés. Si el síntoma no aparece, empieza por la pregunta frecuente correspondiente y, si tampoco está, consulta el comando concreto con rei <comando> --help.

Aprobación de la planificación

Pendiente

La firma humana libera la hoja. El silencio no aprueba.

La aprobación se registra desde el CLI; el visor no la sustituye.