Fase 2: 04_sanitize.py - scrubbing de secretos de skills/agentes/plans (10 secretos unicos, gate en verde)
This commit is contained in:
@@ -0,0 +1,122 @@
|
||||
## 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.
|
||||
Reference in New Issue
Block a user