## Context

El usuario corre estas skills con varios modelos distintos (no solo Claude), en particular **qwen3.6**, tanto
como sesión madre (orquestador) como potencialmente como el modelo que corre dentro del agente-hijo en tmux.
Un modelo más débil no infiere tan bien juicio implícito, prosa ambigua, o instrucciones que compiten entre
sí (dos caminos presentados como válidos cuando solo uno lo es) — eso produce pasos saltados u olvidados.

Ya revisé el ecosistema completo: `agent-orchestrator/SKILL.md` (incluyendo el bloque `TASK.md` de FASE 3
que es lo que literalmente lee el agente-hijo), los 7 subagentes en `~/.claude/agents/*.md`
(`developer`, `code-reviewer`, `qa-validator`, `pr-shipper`, `ci-developer`, `docmost-reporter`, `mailer`),
y las otras 3 skills relacionadas (`aleleba-pr`, `docmost-context`, `web-ui-test`).

Decisión ya tomada con el usuario: **alcance = todo el ecosistema**, **estilo = reforzar sin reestructurar**
(mantener FASE 1-4 y el formato `TASK.md` tal cual, solo hacer explícito lo implícito y arreglar
inconsistencias, no reescribir la arquitectura de la skill).

## Hallazgos concretos (por qué cada cambio)

1. **Bug real de numeración** (`agent-orchestrator/SKILL.md`, bloque `TASK.md`, "PASOS OBLIGATORIOS ANTES DE
   TERMINAR", paso 2): dice *"Si tu tarea es puramente backend/CLI/librería, omite este paso y dilo
   explícitamente en el paso 4."* — pero tras insertar `ci-developer` como nuevo paso 4, el paso que
   documenta motivos de omisión (`docmost-reporter`) pasó a ser el **5**, no el 4. Una referencia cruzada
   desactualizada es exactamente el tipo de cosa que hace que un modelo más débil "confirme" en el paso
   equivocado o se confunda. **Debe decir "paso 5".**

2. **Dos caminos presentados como válidos, cuando solo uno funciona de forma confiable** (FASE 1, paso 6(b),
   creación de `settings.local.json`): el bloque describe primero un "PROCESO OBLIGATORIO DE 3 PASOS" (editar
   `~/.claude/settings.json`, crear el archivo, revertir) y **después** dice que hay un "ATAJO CONFIABLE" que
   lo reemplaza porque el proceso de 3 pasos puede quedar bloqueado por el clasificador. Presentado en ese
   orden, un modelo que sigue instrucciones literalmente y de arriba hacia abajo intentará el proceso de 3
   pasos primero (marcado "OBLIGATORIO") en vez de ir directo al atajo. Hay que invertir la prioridad: dejar
   el heredoc por Bash como **la única instrucción accionable**, y mover la descripción del proceso de 3
   pasos a TROUBLESHOOTING como contexto histórico de por qué no se usa.

3. **Juicio implícito sin regla concreta** en varios puntos:
   - TRIGGER: "o variante muy cercana" no define qué hacer ante duda — un modelo débil puede sobre-activar
     o no activar la skill de forma inconsistente.
   - FASE 1 paso 5(a): "usar el más adecuado o crear la estructura" al no encontrar space de Docmost — no
     dice cómo decidir "más adecuado".
   - `TASK.md` → "PERMISOS Y AUTONOMÍA": "SOLO pausa y notifica si hay un bloqueo real" sin ejemplos
     concretos de qué SÍ y qué NO cuenta como bloqueo — un modelo débil puede pausar por cualquier cosa
     (spam de correos) o nunca pausar (avanza a ciegas sobre ambigüedad real).
   - `developer.md`, punto 5: "toma la decisión más razonable" sin un ejemplo que calibre qué es
     "razonable" vs. una ambigüedad real que sí debería bloquear.
   - `pr-shipper.md`, punto 3: la condición de detenerse ("si detectas que sigues en una rama protegida")
     depende de que el modelo la reconozca por prosa, sin un comando explícito de verificación.

4. **Archivos que ya están bien** (se revisaron, no necesitan cambios): `ci-developer.md` (ya nació con
   pasos numerados, formato de reporte obligatorio y criterios concretos), `code-reviewer.md`,
   `qa-validator.md`, `docmost-reporter.md`, `mailer.md` (todos con reporte final obligatorio y pasos
   numerados, sin juicio implícito relevante), `aleleba-pr/SKILL.md` (ya con pasos numerados e if/else
   explícitos), `docmost-context/SKILL.md` y `web-ui-test/SKILL.md` (ya son algorítmicos/muy explícitos:
   fórmulas de score, tablas de decisión, comandos exactos). No se tocan.

## Cambios a aplicar

### `~/.claude/skills/agent-orchestrator/SKILL.md`

a) **TRIGGER**: agregar una regla explícita de desempate: *"Si dudas si la frase del usuario cuenta como
   'variante muy cercana', trátalo como que NO activa — pregúntale al usuario si quiere que actives el modo
   background en vez de asumirlo."*

b) **FASE 1, paso 5(a)**: reemplazar "usar el más adecuado" por una regla concreta: reusar el mismo criterio
   de normalización + match por contención que ya usa `docmost-context` (minúsculas, sin espacios/guiones,
   sin scope de npm), y si tras eso no hay match claro, usar `AskUserQuestion` con la lista de spaces en vez
   de adivinar.

c) **FASE 1, paso 6(b)**: reordenar — el bloque `cat > "$WT_ABS/.claude/settings.local.json" << 'ENDJSON' ...
   ENDJSON` pasa a ser **la única instrucción presentada** (sin "PASO 1/2/3" ni "ATAJO" como si fueran dos
   alternativas). Mover el "PROCESO OBLIGATORIO DE 3 PASOS" completo (con su fecha "aprendido 2026-06-24") a
   una fila nueva de la tabla TROUBLESHOOTING, como explicación de por qué NO se usa ese camino.

d) **Bloque `TASK.md` (FASE 3)**:
   - Arreglar la referencia cruzada rota: "dilo explícitamente en el paso 4" → **"paso 5"**.
   - Al inicio de "PASOS OBLIGATORIOS ANTES DE TERMINAR", agregar una línea explícita: *"Sigue estos 7 pasos
     EN ORDEN, uno a la vez. No omitas ninguno, no los reordenes, no continúes al siguiente hasta terminar
     el actual (salvo que el paso mismo te diga que lo saltes, como el paso 2 cuando no aplica)."*
   - Reescribir "PERMISOS Y AUTONOMÍA" con una lista explícita de dos columnas:
     **SÍ es bloqueo real** (te faltan credenciales/acceso que nadie más puede darte, instrucciones del
     usuario se contradicen entre sí, la tarea pide algo que viola una regla de seguridad de este documento
     —p.ej. mergear, forzar push—, o un error técnico que ya intentaste resolver 2+ veces sin éxito) vs.
     **NO es bloqueo** (elegir entre dos formas válidas de implementar algo, un lint/type error que puedes
     arreglar tú mismo, decidir nombres de variables/archivos, instalar una dependencia que falta). Mantener
     el mecanismo ya descrito (dejar la pregunta como última salida, esperar, el hook `Notification` avisa).
   - Al inicio del bloque `TASK.md` (junto a la línea `TAREA:`), agregar: *"Este archivo son tus
     instrucciones completas. Léelas y ejecútalas literalmente, en el orden en que aparecen. No asumas que
     un paso ya se cumplió o que no aplica salvo que el propio paso lo diga explícitamente."*

### `~/.claude/agents/developer.md`

En el punto 5 ("Si tienes una duda de diseño..."), agregar un ejemplo concreto de cada lado: *ejemplo de
decisión rutinaria que SÍ debes tomar tú solo (p.ej. nombre de una variable interna, orden de los
parámetros de una función nueva), vs. ejemplo de ambigüedad real que si la encuentras debes reportar como
bloqueo/duda en vez de decidir (p.ej. la tarea pide dos comportamientos mutuamente excluyentes, o requiere
tocar un archivo fuera de tu lista asignada)*.

### `~/.claude/agents/pr-shipper.md`

En el punto 3, antes de la condición en prosa, agregar el comando explícito de verificación:
```bash
git branch --show-current   # si el resultado es main/master/dev, DETENTE — no continúes
```
para que la condición de "sigues en una rama protegida" tenga un chequeo concreto en vez de depender de
que el modelo lo infiera solo.

## Fuera de alcance

- No se reestructuran las FASES 1-4 ni el formato de `TASK.md` — solo se refuerzan pasos existentes.
- `ci-developer.md`, `code-reviewer.md`, `qa-validator.md`, `docmost-reporter.md`, `mailer.md`,
  `aleleba-pr/SKILL.md`, `docmost-context/SKILL.md`, `web-ui-test/SKILL.md` — sin cambios (ya son
  suficientemente explícitos).

## Verificación

- Releer `agent-orchestrator/SKILL.md` completo después de los cambios y confirmar que la numeración de
  "PASOS OBLIGATORIOS ANTES DE TERMINAR" (1-7) y todas sus referencias cruzadas internas ("paso 5", "pasos
  5/6", etc.) son consistentes de punta a punta.
- Confirmar que el paso 6(b) de FASE 1 ya no presenta el proceso de 3 pasos como una alternativa válida —
  solo debe quedar el heredoc de Bash como instrucción, con el resto movido a TROUBLESHOOTING.
- Grep rápido de `grep -n "paso 4\|PROCESO OBLIGATORIO DE 3 PASOS" agent-orchestrator/SKILL.md` para
  confirmar que la única mención remanente del proceso de 3 pasos está en la fila de TROUBLESHOOTING, no en
  el flujo activo.