---
description: Revisa y corrige avisos comunes de markdownlint en ficheros .md del repo (raíz, .claude, .agents, packages...). No hay devDep ni CI; el repaso es manual y se invoca a demanda.
---

# /md-lint — limpieza de markdown

Aplica un repaso de estilo a los `.md` del repo según las reglas que más se cuelan en este proyecto. No hay `markdownlint-cli2` instalado y no se quiere añadir como devDep — el barrido es manual contra el set de reglas de abajo.

## Argumento

`$ARGUMENTS` opcional. Si está, acota el barrido a esa ruta (fichero concreto, carpeta, glob). Si no, barre todo el repo excluyendo:

- `node_modules/`
- `dist/`
- `.git/`
- `coverage/`

Para listar candidatos:

```bash
find . -name "*.md" -not -path "./node_modules/*" -not -path "./dist/*" -not -path "./.git/*" -not -path "*/coverage/*"
```

## Reglas que se revisan

Set mínimo, alineado con lo que el editor del usuario marca y con el estilo ya presente en `README.md` y `CLAUDE.md`:

- **MD004 — list-style:** listas con `-`, no con `*`.
- **MD030 — list-marker-space:** un único espacio tras `-` o `1.` (no `*   ` ni `1.  `).
- **MD032 — blanks-around-lists:** una línea en blanco antes y después de cada lista.
- **MD031 — blanks-around-fences:** una línea en blanco antes y después de cada bloque ` ``` `.
- **MD036 — no-emphasis-as-heading:** `**Sección:**` en línea propia → heading real (`####`). Si la línea es la firma del documento o contenido decorativo (no es un encabezado lógico), convertir a texto plano en vez de inventar un heading.
- **MD040 — fenced-code-language:** todo bloque ` ``` ` debe declarar lenguaje (`text`, `bash`, `ts`, `json`...).
- **MD026 — no-trailing-punctuation-in-heading:** headings sin `:` ni `.` al final.
- **MD047 — single-trailing-newline:** el fichero termina con un único `\n` final.
- **MD034 — no-bare-urls:** URLs en texto deben ir en `<...>` o como link `[texto](url)`.

No se tocan:

- Contenido (typos, gramática, redacción) — solo formato. Excepción: si encuentras un typo obvio en un encabezado o una frase muy corta, repórtalo al final pero no lo arregles sin permiso.
- Longitud de línea (MD013): el repo no la fuerza.
- Estilo de heading ATX vs Setext: ya está unificado en ATX (`#`).

## Cómo proceder

1. Resuelve la lista de ficheros (`$ARGUMENTS` o barrido completo).
2. Si son más de ~5 ficheros, despacha el trabajo a subagentes en paralelo agrupando por carpeta (ver skill `dispatching-parallel-agents`). Cada subagente recibe un grupo y este mismo set de reglas.
3. Para cada fichero, lee y aplica las reglas con `Edit`. No reescribas el fichero entero con `Write` salvo que el delta sea masivo.
4. No introduzcas cambios fuera del set de reglas. No reordenes secciones, no añadas contenido.

## Formato de reporte

Tabla resumen al terminar:

```text
fichero                        cambios
-----------------------------  -------
CONTRIBUTING.md                12  (MD004, MD030, MD036, typo)
.claude/rules/code-style.md    0
.agents/skills/.../HOUSE.md    3   (MD031, MD040)
```

Si encontraste typos o problemas de contenido que no arreglaste (por estar fuera de scope), lístalos en una sección **Sugerencias** al final para que el usuario decida.

## Cuándo invocarlo

Es opcional, no hay CI que lo ejecute. Casos típicos:

- Tras editar varios `.md` seguidos y que el editor empiece a marcar avisos.
- Antes de un PR que toca documentación.
- Limpieza periódica si el repo arrastra inconsistencias.

No lo invoques de oficio.