Temper-Skills (modo biblioteca)

¿Qué hace Temper-Skills (modo biblioteca)?

Convierte la lógica de decisión de una habilidad o prompt de agente en Python determinista — cero invocaciones de LLM en inferencia — manejando la CLI temper-skills instalada. Tú orquestas la CLI y transmites su salida; la biblioteca realiza el tempering. Nunca escribes el árbol de decisión tú mismo.

Usa esta habilidad cuando no tengas una primitiva nativa de subagente/Task para ejecutar el bucle por ti mismo. Dentro de Claude Code, prefiere la habilidad en modo subagente (se ejecuta sin clave, con un panel en vivo). Este modo, en cambio, ejecuta comandos de la CLI.

Cuándo usarlo

• Un skill .md, system prompt o playbook contiene lógica de enrutamiento/decisión (if-esto-entonces-aquello sobre entradas estructuradas) que debería ser testeable, difereciable en un PR o resiliente a actualizaciones del modelo.
• Buen ajuste: enrutamiento de tickets, reglas de clasificación, comprobaciones de elegibilidad — decisiones categóricas sobre características precomputables.
• No es adecuado para: puntuación continua, generación de texto o lógica sin documentación a la que el modelo pueda acceder.

Reglas no negociables

1. Siempre llama a la biblioteca a través de su CLI. Nunca reimplementes la lógica de decisión en lenguaje natural como sustituto de ejecutarla.
2. Nunca omitas la ratificación del esquema. El esquema que apruebas es la semilla ingenua que el bucle luego co-evoluciona (el schema_critic la expande, el guardián earn-a-branch la poda), por lo que un error silencioso de extracción en la semilla envenena todo. Usa la compuerta basada en archivos a continuación (--propose-schema), incluso cuando no haya terminal adjunta. Revisa el esquema co-evolucionado y cualquier nota de schema gaps / schema grew que la CLI imprima al final.
3. Nunca instales silenciosamente. Si la compuerta (Paso 0) informa que falta la biblioteca o un backend, pregunta al usuario antes de ejecutar pip install o cambiar su entorno.
4. Nunca afirmes que el árbol es "correcto" — solo que es determinista y auditable. La corrección es responsabilidad del usuario, establecida mediante ejemplos ratificados (validate, Paso 4).
5. Transmite textualmente las compuertas y veredictos de la CLI — veredicto de auditoría, paneles de persona, zonas grises, casos pendientes de ratificación. No los resumas.

Paso 0 — Verificar instalación + backend

Ejecuta python scripts/check_install.py y ramifica según el código de salida:

• 0 — listo, continuar.
• 10 — instalado pero sin backend de modelo. Informa al usuario: temper-skills necesita un backend — una CLI claude o opencode con sesión iniciada, o ANTHROPIC_API_KEY en el entorno. Pregunta cómo quiere proporcionarlo. No continúes hasta que exista un backend.
• 11 — no instalado. Pregunta: "temper-skills no está instalado. ¿Instalarlo ahora? (pip install temper-skills)" Instala solo tras confirmación explícita.

Paso 1 — Triage con guide (comienza aquí)

Encuentra el archivo .md o prompt que contiene la lógica de decisión (confirma la ruta con el usuario si es ambigua), luego ejecuta el recorrido de un solo comando:

temper-skills guide <ruta/al/skill.md> --json

Si el usuario señala un directorio (una biblioteca de skills), recórrelo en lugar de guiar un solo archivo — la auditoría es un informe que vale la pena transmitir:

temper-skills audit <dir> --json --report audit.md

Transmite los hallazgos ordenados (el JSON es una lista de informes por skill, primero los más accionables) y ofrece guide para la primera opción. audit.md es una versión Markdown compartible para un PR.

Siempre pasa --json. guide e ingest emiten un manifiesto legible por máquina en stdout y envían los paneles humanos Rich a stderr — lee el manifiesto, no extraigas los paneles. El manifiesto de guide es:

{ "audit": { "verdict": "...", "recommended_action": "...", ... },
  "action_taken": "temper|decompose|...",
  "status": "compiled|stopped_for_ratification|action_not_auto_run",
  "final_skill_path": "...", "artifacts": ["..."] }

guide audita el skill, luego sigue recommended_action. Transmite el veredicto de auditoría y la acción al usuario:

• temper — una decisión en forma de árbol. guide la templa (rápido); status: compiled.
• decompose — un flujo (≥2 decisiones). guide emite esquemas por decisión y se detiene; status: stopped_for_ratification.
• externalize_data / build_normalizer / delegate_prose — no son trabajos de tempering. status: action_not_auto_run; transmite la pista de acción y detente.

guide es el recorrido: ejecuta el perfil quick y acepta automáticamente el esquema inferido. Eso está bien para "muéstrame lo que hace", pero para un árbol en el que el usuario confiará, ve al Paso 2 para que el esquema sea ratificado.

Paso 2 — Producir un árbol definitivo (flujo ratificado)

2a. Redactar el esquema y DETENERSE para ratificación

temper-skills ingest <ruta/al/skill.md> --propose-schema --json

Esto escribe schema.proposed.py y se detiene — el bucle nunca se ejecuta sobre un esquema no ratificado. El JSON en stdout te da {proposed_schema_path, fn_name, features:[{name,type,description}], constraints}. Muestra al usuario las características propuestas y haz exactamente una pregunta: ¿aceptas estas características o editas la lista? Aplica sus ediciones a schema.proposed.py.

No le preguntes nada más al usuario aquí — ni sobre la amplitud de las características, ni sobre qué ramas conservar. La poda es trabajo del bucle (el crítico de sobreingeniería), no del usuario.

2b. Compilar contra el esquema ratificado

temper-skills ingest <ruta/al/skill.md> \
  --schema schema.proposed.py \
  --profile standard \
  --json

Elige el perfil con el usuario — quick | standard | audit-grade, por defecto standard; consulta references/profiles.md antes de recomendar. --json implica modo no interactivo: el bucle se ejecuta hasta convergencia (no puede pausarse para una compuerta por ronda cuando se maneja así — esa compuerta es una característica de terminal humana) y emite el manifiesto resultante en stdout. Léelo, no extraigas los paneles. (--require-fit aborta temprano con código de salida 3 si el veredicto de auditoría es skip; agrégalo para evitar desperdiciar el bucle en un mal ajuste.)

2c. Si la acción fue decompose

Primero hay que dividir un flujo; templa cada decisión por separado:

temper-skills decompose <ruta/al/skill.md> --temper-each --out-dir out/

Esto emite un esquema por decisión y se detiene para ratificación. Presenta los esquemas, deja que el usuario los edite, luego vuelve a ejecutar el mismo comando para compilar cada uno en un árbol más el skill orquestador (--yes-unratified omite la detención — evítalo a menos que el usuario lo pida).

Paso 3 — Informar los artefactos (desde el manifiesto)

El manifiesto de ingest --json es la fuente de verdad — lee estos campos, no extraigas:

{ "tree_path": "...", "tempered_skill_path": "...",
  "validation_dataset_path": "...", "validation_case_count": 0,
  "gray_zones": [{"node": 1, "condition": "...", "note": "..."}],
  "features": ["..."], "node_count": 0, "profile": "...", "cost_usd": 0.0 }

Presenta los tres artefactos al usuario:

• tree_path — el árbol de decisión: no importa nada, cero llamadas LLM en inferencia, con un encabezado generated_at + modelo y comentarios de procedencia por nodo;
• tempered_skill_path — el skill.md templado: el skill original reescrito para llamar al árbol congelado en lugar de volver a decidir. La mitad del entregable; no lo descartes;
• validation_dataset_path — el .validation.jsonl confirmado que el bucle construyó para sus zonas grises, pendiente de ratificación (validation_case_count). Las filas con "agrees": false son los desacuerdos de mayor valor para que el usuario los resuelva. Las pruebas de bloqueo de comportamiento junto a él (test_<stem>.py) permanecen verdes; solo las etiquetas ratificadas pueden volver roja una prueba.

Informa al usuario las rutas, el perfil, el cost_usd y las gray_zones. Reitera la regla 4: determinista y auditable, no "correcto."

Paso 4 (opcional) — Fijarlo en CI

Una vez que el usuario haya ratificado un conjunto etiquetado, valida el árbol contra él:

temper-skills validate decision_tree.generated.py ratified.json --min-agreement 1.0

Código de salida distinto de cero en caso de desacuerdo — esto es lo que fija el árbol en CI. Cada desacuerdo es un error del árbol o un ejemplo mal etiquetado; transfiérelos para su aprobación.

Referencia

Consulta references/profiles.md para conocer rondas / convergencia / panel de persona / costo por perfil antes de recomendar uno.

Nunca

• Nunca escribas la lógica del árbol en lenguaje natural en lugar de ejecutar la biblioteca.
• Nunca omitas la ratificación del esquema, incluso en una demostración quick (quick omite los comentarios de procedencia, no la compuerta).
• Nunca instales ni modifiques el entorno sin confirmación explícita.
• Nunca afirmes que el árbol generado es "correcto."