# Regla: Lectura de documentos Office y Jupyter con MarkItDown

Esta regla aplica cuando un agente necesita **leer el contenido** de un archivo
en formato Office o Jupyter. No aplica a operaciones de escritura, copia o listado.

---

## Cuándo aplica

Cuando el agente necesita acceder al contenido de archivos con estas extensiones:

| Extensión | Formato |
|-----------|---------|
| `.docx` | Word — documentos, especificaciones, ADRs |
| `.xlsx` `.xls` | Excel — datos, métricas, matrices |
| `.pptx` | PowerPoint — presentaciones, roadmaps |
| `.ipynb` | Jupyter Notebook — análisis, experimentos |

## Regla obligatoria

NUNCA usar el Read tool directamente para estos formatos — no los soporta y
devuelve contenido binario ilegible. Usar en su lugar:

```bash
# Opción 1: markitdown instalado globalmente (pip install markitdown)
markitdown <ruta-al-archivo>

# Opción 2: wrapper del vendor de swl-ses (si está disponible)
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
python "$PROJECT_ROOT/scripts/vendor/markitdown/cli.py" <ruta-al-archivo>

# Opción 3: módulo Python directamente
python -m markitdown <ruta-al-archivo>
```

**Verificar disponibilidad antes de usar**:
```bash
markitdown --version 2>/dev/null && echo "CLI_OK" || echo "NO_DISPONIBLE"
```

Si no está disponible:
```
markitdown no está instalado. Para habilitarlo:
  pip install markitdown[pdf,docx,pptx,xlsx]

Mientras tanto, pedir al usuario que proporcione el contenido en texto plano.
```

## Lo que sí usa el Read tool

El Read tool sigue siendo correcto para:
- `.pdf` (hasta 20 páginas con parámetro `pages:`)
- `.md`, `.txt`, `.markdown`
- Código fuente (`.py`, `.js`, `.ts`, `.java`, etc.)
- Cualquier archivo de texto plano

## Referencia completa

Para casos avanzados (ingest masivo, URLs YouTube, ZIP con documentos mixtos,
árbol de decisión completo): `Skill("swl-markitdown")`.