Solución de problemas
Síntomas, causa y siguiente paso para los fallos habituales del arnés y del CLI.
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.
- Ejecuta
rei init statuspara ver qué documentos faltan. - Abre
/personalizeen OpenCode o Claude Code, o pide «personaliza mi proyecto» para que el Initializer conduzca la entrevista. - Revisa que
AGENTS.mdy.rei/docs/project/describan tu repositorio y no el esqueleto. - 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.
- Lee la salida: distingue un fallo del arnés de un check del proyecto.
- Si falla un check, ejecuta su comando por separado y corrige la causa.
- Comprueba que el check esté bien declarado:
id,descriptionycommandcomo array. - Repite
rei check --quiethasta 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.
- Ejecuta
rei items statusy localiza el Work Item marcado con << ACTIVO. - Cierra el activo (review o done), bloquéalo o termina su revisión.
- Confirma que ya no queda ninguno en in_progress.
- Inicia el siguiente Work Item solo cuando el anterior haya salido del estado.
links.json inválido
.rei/specs/<id>/links.json es un índice local recuperable, no la fuente de verdad. Si el JSON está roto o su forma no es válida, rei validate lo informa como WARN —nunca como FAIL— y rei item show o rei items status lo señalan como nota sin bloquear el Work Item.
- Ejecuta
rei validatepara leer la causa concreta. - Localiza la issue por su marcador rei:work-item:<id>, no por el título ni por la label.
- Reescribe
links.jsoncon su forma válida: provider, repo, issue, url, base y epic cuando correspondan. - Vuelve a validar; el aviso desaparece sin cambiar el estado del Work Item.
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.
- Ejecuta
rei item show <id>para ver el tipo y el estado reales. - Si el tipo no coincide con el argumento, repite el comando con el tipo de
meta.json. - Si el estado es ready, no reinicies: aprueba la planificación o pide cambios.
- Si está en in_progress, review o changes_requested, retoma la sesión existente con
rei item show <id>. - 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.
- Instala GitHub CLI y comprueba que
ghestá en el PATH. - Ejecuta
gh auth loginy despuésgh auth status. - Ejecuta
rei github statuspara ver el estado offline de la configuración y la disponibilidad degh. - Repite la acción de GitHub Issues solo cuando
ghresponda 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.
- Ejecuta
rei view <id> --openpara arrancar o reutilizar el servidor y abrir el navegador. - Si sigue sin responder, detén el servidor con
rei view --stopy vuelve a abrirlo. - Sin
<id>, el visor usa el Work Item de la sesión activa; comprueba que exista conrei session. - Revisa
viewer.autoOpenOnReadysi 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.
- Ejecuta
rei update --checkpara confirmar la versión disponible sin descargar. - Repite
rei updatecuando la red esté estable. - Si el fallo de integridad persiste, descarga el archive de la página de releases y verifica su SHA-256 contra
checksums.txtantes 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.
- Ejecuta
rei check: crea la estructura e inicializagitsi no existe. - Si decides usar
git, confirma que el repositorio tiene un commit inicial antes de aprobar un Work Item. - Sin
git,base_commitylast_review_commitquedan vacíos; el flujo no se bloquea por ello. - Con
git, registra los commits antes de solicitar revisión para querei review-diffacote 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.
La firma humana libera la hoja. El silencio no aprueba.