# Gaia Debugging

> Diagnostica por qué falló una pregunta de GAIA: extrae la traza, clasifica el modo de fallo y propone una corrección antes de reenviar.

Fuente: https://skillsagentes.com/skills/ruvnet/ruflo/gaia-debugging
Markdown: https://skillsagentes.com/skills/ruvnet/ruflo/gaia-debugging.md

Repositorio: https://github.com/ruvnet/ruflo
Autor: ruvnet
Licencia: MIT
Actualizado: el mes pasado
Coste de contexto: 53 tok instalada, 1.1k tok al activarse, 1.1k tok con todos los archivos del bundle
Bundle: 1 archivo, 4 KB
Permisos que pide: bash read mcp__plugin_ruflo-core_ruflo__memory_search mcp__plugin_ruflo-core_ruflo__memory_store mcp__plugin_ruflo-core_ruflo__agentdb_pattern_search mcp__plugin_ruflo-core_ruflo__agentdb_pattern_store

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add ruvnet/ruflo --skill gaia-debugging --agent claude-code
# Cursor
npx -y skills add ruvnet/ruflo --skill gaia-debugging --agent cursor
# Codex
npx -y skills add ruvnet/ruflo --skill gaia-debugging --agent codex
# Gemini CLI
npx -y skills add ruvnet/ruflo --skill gaia-debugging --agent gemini
# Windsurf
npx -y skills add ruvnet/ruflo --skill gaia-debugging --agent windsurf
# Cline
npx -y skills add ruvnet/ruflo --skill gaia-debugging --agent cline
```

## Qué hace

- Carga la traza de una pregunta GAIA fallida por task_id y la clasifica en una taxonomía de modos de fallo
- Distingue entre falta de herramienta, error de razonamiento, bug de extracción, loop, cambio de dataset o timeout
- Reejecuta la pregunta con logging extendido y aplica una corrección dirigida según el tipo de fallo
- Guarda el patrón de fallo y su solución para futuras consultas

## Cuándo usarla

- Un task_id concreto devuelve la respuesta incorrecta o hace timeout
- La tasa de aciertos bajó entre dos ejecuciones y hay que encontrar la regresión
- Una clase de preguntas falla de forma consistente

## Qué la activa

- "Diagnostica por qué falló la pregunta task_id=abc123 en GAIA"
- "La tasa de aciertos bajó en la última corrida, encuentra la regresión"

## Antes de instalar

- Necesita en el PATH: node, npx
- Variables de entorno: CODE, FAILURE_CODE, FIX_DESCRIPTION, MODEL, RESULTS, TASK_ID
- reads environment config

## Archivos

- SKILL.md — 4 KB

## SKILL.md

Reproducido tal cual desde ruvnet/ruflo bajo MIT. Esta sección es el documento original y está en inglés.

# GAIA Debugging Skill

When a GAIA question fails, systematically diagnose the root cause and propose
a targeted fix.

## When to use

- A specific `task_id` returns the wrong answer or times out
- Pass-rate dropped between two runs and you need to find the regression
- You want to understand why a particular question class is consistently failing

## Failure mode taxonomy

| Code | Mode | Symptom | Fix direction |
|------|------|---------|--------------|
| TG | Tool Gap | Agent lacks a required tool (no image OCR, no PDF reader) | Add tool to catalogue |
| RM | Reasoning Miss | Agent has the right data but draws wrong conclusion | Improve system prompt, add CoT instruction |
| EB | Extraction Bug | Answer is in the trace but `FINAL_ANSWER:` regex fails | Fix answer extraction pattern |
| LI | Loop Issue | Agent loops (re-asks same tool call) and hits turn limit | Increase max-turns or add loop-detection |
| DS | Dataset Shift | Ground truth differs from what web currently shows | Flag for HAL dataset audit |
| AT | API Timeout | Tool call times out; agent never gets the result | Increase per-turn timeout |

## Diagnostic workflow

### Step 1 — Load the question trace

```bash
# Find the result for the task_id in the latest run
RESULTS=~/.cache/ruflo/gaia/results-latest.json
node -e "
  const r = JSON.parse(require('fs').readFileSync('$RESULTS'));
  const q = r.results.find(x => x.task_id === '$TASK_ID');
  console.log(JSON.stringify(q, null, 2));
"
```

### Step 2 — Classify the failure

Look at the trace output:

1. **No tools called at all** → RM or configuration issue
2. **Tool called but returned error** → TG or AT
3. **Tool returned data, wrong answer** → RM or EB
4. **Correct answer in trace but marked wrong** → EB
5. **max-turns hit** → LI or question too hard for current model

### Step 3 — Re-run with extended logging

```bash
node v3/@claude-flow/cli/bin/cli.js gaia-bench run \
  --level 1 --limit 1 \
  --task-id $TASK_ID \
  --models claude-sonnet-4-6 \
  --max-turns 20 \
  --output json
```

### Step 4 — Apply targeted fix

| Failure | Action |
|---------|--------|
| TG — missing web_browse | Verify `gaia-tools/index.ts` exports `web_browse`; check tool registration |
| TG — missing image OCR | Add `image_describe` tool call; verify `GOOGLE_AI_API_KEY` |
| RM — reasoning | Add a system prompt instruction: "Before answering, list all facts you have gathered" |
| EB — extraction | Test the `FINAL_ANSWER_RE` regex against the trace manually |
| LI — loop | Add a tool-call deduplication guard in `gaia-agent.ts` |
| AT — timeout | Set `DEFAULT_PER_TURN_TIMEOUT_MS` higher or use `--max-turns` flag |

### Step 5 — Verify fix and store pattern

```bash
# Re-run the single question
node … gaia-bench run --task-id $TASK_ID --models $MODEL --output json

# If now passing, store the pattern
npx @claude-flow/cli@latest memory store \
  --namespace gaia-debug-patterns \
  --key "fix-$FAILURE_CODE-$(date +%Y%m%d)" \
  --value "task_id=$TASK_ID, mode=$FAILURE_CODE, fix=$FIX_DESCRIPTION"
```

## Quick reference: tool catalogue check

```bash
node -e "
  const { createDefaultToolCatalogue } = require('./v3/@claude-flow/cli/src/benchmarks/gaia-tools/index.js');
  const cat = createDefaultToolCatalogue({});
  console.log('Tools registered:', cat.definitions.map(t => t.name));
"
```

Expected: `web_search`, `file_read`, `web_browse`, `image_describe`, `python_exec`

## Pattern storage

After resolving a debugging session, store the finding:
```bash
npx @claude-flow/cli@latest memory store \
  --namespace gaia-debug-patterns \
  --key "session-$(date +%Y%m%d-%H%M)" \
  --value '{"task_id":"$TASK_ID","failure_mode":"$CODE","fix":"$FIX","verified":true}'
```

Search for similar past failures:
```bash
npx @claude-flow/cli@latest memory search \
  --namespace gaia-debug-patterns \
  --query "extraction bug final answer regex"
```

## Dónde encaja

- Categoría: [Testing y QA](https://skillsagentes.com/categorias/testing-qa.md) — Flujos de testing unitario, de integración y end-to-end.
- Creador: [ruvnet](https://skillsagentes.com/creators/ruvnet.md) — 275 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Harness Gepa](https://skillsagentes.com/skills/ruvnet/ruflo/harness-gepa.md): Inspecciona y audita genomas GEPA: carga y valida un genoma, renderiza el system prompt que compila, o clasifica los modos de fallo de una transcripción de ejecución.
- [Deepseek Reason](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-reason.md): Completion en modo razonamiento contra deepseek-reasoner (R1) de DeepSeek. Devuelve el chain-of-thought por separado de la respuesta final. Lee DEEPSEEK_API_KEY y degrada si falta o la API no responde.
- [Deepseek Chat](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-chat.md): Completion de un solo turno contra el modelo deepseek-chat de DeepSeek vía /v1/chat/completions. Lee DEEPSEEK_API_KEY y degrada con status:degraded si falta o la API no responde. Para tareas sin razonamiento.
- [Adr Index](https://skillsagentes.com/skills/ruvnet/ruflo/adr-index.md): Construye o reconstruye el índice de ADRs y su grafo de dependencias ejecutando scripts/import.mjs, en vez de cientos de llamadas MCP.
- [Agntcy Status](https://skillsagentes.com/skills/ruvnet/ruflo/agntcy-status.md): Muestra el estado de la integración AGNTCY/SLIM/CASA: si los paquetes están instalados, qué transporte está activo y si el enforcement de CASA está habilitado.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)