Troubleshooting

La mayoría de problemas vienen de git hooks locales, git notes faltantes o configuración de GitHub Pages.

Checks rápidos

1. Revisa el setup local.

   npx agent-note status

2. Comprueba que el commit tenga note.

   npx agent-note show

3. Comprueba las notes remotas.

   git fetch origin refs/notes/agentnote:refs/notes/agentnote
   git notes --ref=agentnote show HEAD

Empieza por el síntoma

Síntoma	Empieza aquí
PR Report vacío	Confirma que las notes se subieron y que el workflow obtiene todo el historial git
Falta un prompt esperado	Compara compact y full
Dashboard abre, pero la PR no tiene datos	Revisa si las notes de esa PR ya se publicaron
git commit no crea note	Ejecuta init otra vez y revisa la línea git: en status
Falta Line Estimate	Revisa si el agent puede entregar suficiente evidencia de edición

PR Report vacío

• El branch de PR se pushó después de activar Agent Note.
• refs/notes/agentnote existe en el remote.
• actions/checkout usa fetch-depth: 0.
• La PR contiene commits con archivos tocados por el agente.

Agent Note no escribe note para commits donde no puede asociar ningún archivo commitado con el agente.

Si el header muestra Total AI Ratio: — y Agent Note data: No tracked commits, la PR tiene commits pero no se encontraron datos de Agent Note para ellos. No es lo mismo que un AI Ratio real de 0%.

Faltan prompts

Prompt selection usa la ventana commit-to-commit, no toda la sesión.

• compact mantiene el informe enfocado mostrando los prompts que explican el commit.
• full muestra todos los prompts guardados.
• Los prompts de tareas antiguas se recortan cuando el commit actual tiene explicación propia.
• 📝 Context aparece para prompts cortos cuando un nombre de archivo o identificador de código ayuda a entenderlos.

with:
  prompt_detail: full

Dashboard sin datos

• GitHub Pages debe usar GitHub Actions como source.
• El workflow debe ejecutar dashboard: true.
• El primer deploy exitoso crea /dashboard/.
• Si Pull Request Deploys está bloqueado, los datos de Open PR aparecen después del merge.

Nota

?pr=123 funciona solo después de publicar las notes de esa PR.

Dashboard abre otra PR

La página inicial del Dashboard debe mostrar el historial compartido sin forzar ?pr=. Solo los enlaces del PR Report añaden el ?pr=<number> de la PR actual.

Si un deploy antiguo de Pages todavía redirige, vuelve a ejecutar el workflow Dashboard o espera el próximo deploy exitoso desde main.

git commit no se trackea

npx agent-note status
npx agent-note init --agent claude

Los git hooks son locales a .git/, así que cada clone necesita init.

Falta Line Estimate

Suele ser normal. Claude Code normalmente entrega suficiente evidencia para Line Estimate. Codex CLI solo puede estimar líneas cuando el conteo de patches del transcript coincide con el diff final. Cursor solo puede hacerlo cuando los conteos de edición coinciden y el archivo final todavía coincide con la última edición de IA. Gemini CLI actualmente muestra solo AI Ratio a nivel de archivo.

Cuando la evidencia está incompleta, Agent Note vuelve a una evaluación segura en lugar de adivinar.