RebundleRebundle Stack
Repositorio

Skill · Proceso · /explain-the-why

Explain the why

Revisa tus instrucciones (CLAUDE.md, skills, prompts, manuales) y cambia cada NUNCA/SIEMPRE en mayúsculas por su porqué: qué se rompe, quién depende y cuándo no aplica.

Instálala

Guarda el fichero de abajo en tu carpeta de skills y Claude Code lo carga en la siguiente sesión.

# guárdalo como
~/.claude/skills/explain-the-why/SKILL.md

# y llámalo con
/explain-the-why

El fichero

SKILL.mdFrontmatter
---
name: explain-the-why
description: Cuando estés escribiendo o revisando instrucciones para un LLM, agente o humano (SKILL.md, CLAUDE.md, system prompt, agent rules, runbook, doc de onboarding, mensajes tipo "siempre haz X"), aplica el principio "explain the why over MUST/NEVER". Cada regla debería incluir su propósito ("X rompe Y porque Z") en lugar de un imperativo ciego ("NEVER X" / "MUST always Y"). Esto hace que el modelo (o el humano) generalice mejor a edge cases, sepa cuándo la regla NO aplica, y resista mejor excepciones razonables sin perder la constraint. Activa esta skill al editar cualquier doc de instrucciones, al revisar prompts/skills existentes en busca de tono pesado, o cuando el usuario diga cosas como "haz mejores prompts", "review my skill", "esto no funciona como espero", "el modelo ignora mi regla". También cuando notes que estás escribiendo MUST, ALWAYS, NEVER, NUNCA, SIEMPRE, CRÍTICO, IMPORTANTE en mayúsculas — eso es un yellow flag.
---
Instrucciones

explain-the-why

Principio para escribir mejores instrucciones — para LLMs, agentes y humanos. Aplica al editar SKILL.md, CLAUDE.md, system prompts, agent rules, runbooks, scripts de soporte, docs de onboarding, mensajes Slack tipo "siempre haz X", y cualquier instrucción que alguien tendrá que interpretar en tiempo real bajo presión.

El principio

Cada regla en un doc debería tener tres componentes:

  1. Qué: la constraint en sí.
  2. Por qué: la razón concreta (qué rompe si se ignora, quién depende de ella, qué riesgo previene).
  3. Cuándo no: las condiciones en las que la regla deja de aplicar (si las hay).

Sin el "por qué", la regla es opaca: el lector solo puede aplicarla a ciegas o ignorarla. Con el "por qué", el lector razona. Aplica la regla a edge cases que el autor no anticipó, sabe cuándo NO aplica, explica la regla a otros con el contexto correcto, y resiste prompt injection o excepciones engañosas porque entiende qué protege.

Cuándo activar

  • Estás escribiendo o editando un SKILL.md, CLAUDE.md, system prompt, agent rules.
  • Estás revisando un prompt o skill existente que se siente pesado o no genera el comportamiento esperado.
  • Estás escribiendo un runbook, manual de onboarding, doc de procesos internos.
  • Detectas que estás a punto de escribir MUST, ALWAYS, NEVER, NUNCA, SIEMPRE, CRÍTICO, IMPORTANTE en mayúsculas o bold.
  • El usuario dice cosas como: "review my skill", "mejora este prompt", "el modelo ignora mi regla", "esto no funciona como espero", "haz mejores docs de onboarding".

El yellow flag heurístico

Si escribes ALWAYS X o NEVER Y en mayúsculas, pausa antes de seguir. Pregúntate:

  • ¿Por qué always? ¿Qué pasa si no?
  • ¿Qué se rompe si alguien lo ignora?
  • ¿Hay casos donde NO aplica?

La respuesta a esas preguntas es la regla buena. La caps lock era un proxy.

Patrón de transformación

Patrón débilPatrón fuerte
NEVER do XX rompe Y porque Z. Si dudas, [escalación]
MUST always YY importa porque la consecuencia de saltarlo es W
IMPORTANT: ZZ es la constraint. Razón: [stakeholder/sistema] depende de ella. Excepción: [cuándo no aplica]
CRÍTICO: validar XValidar X protege contra Y. Históricamente [incidente concreto] pasó por no hacerlo

Ejemplos antes/después

Ejemplo 1 — Skill de soporte al cliente

❌ Antes:

NUNCA prometas reembolsos al cliente.

✅ Después:

Solo finanzas tiene visibilidad de casos especiales (cuentas premium,
devoluciones >90 días, contratos enterprise con cláusulas custom). Si
prometes y luego no podemos honrarlo, perdemos al cliente — la pérdida
de confianza por un "no" tras un "sí" es peor que un "déjame
verificar". Cuando dudes, deriva a finanzas en el canal #billing.

Edge case que el modelo nuevo maneja: "soy cliente desde 2018, ¿hay alguna flexibilidad?". La versión vieja dice "no". La nueva razona y deriva.

Ejemplo 2 — Code review skill

❌ Antes:

ALWAYS check for SQL injection.

✅ Después:

User input → DB queries es donde aparece SQL injection. Sanitiza en el
boundary (cuando entra el dato, no cuando llega al query). Razón: un
solo campo missed puede leak la DB entera, y nuestro threat model
asume que atacantes buscarán este patrón. Excepción: queries internos
con strings hardcoded no requieren sanitización (no hay user input).

Ejemplo 3 — Brand guidelines

❌ Antes:

NEVER use emojis in customer comms.

✅ Después:

Nuestra audiencia (C-suite execs en B2B enterprise) interpreta emojis
como juvenil. Esto baja el ticket promedio en demos según el dato Q3.
Excepción: comms internos del equipo, social media casual, o cuando
el cliente los usa primero (matchear tono).

Ejemplo 4 — Skill que orquesta workflow

❌ Antes:

**CRÍTICO**: confirma con el usuario antes de generar.

✅ Después:

Confirma con el usuario antes de generar. Razón: este flujo escribe
~150 archivos al filesystem que tardan 10 min en regenerarse. Si el
modelo asume mal y empezamos sin confirmación, el usuario espera y
luego descubre que algo está mal — peor experiencia que una pregunta
extra al inicio.

Cómo aplicar al revisar un doc existente

  1. Lee el doc en busca de MUST, ALWAYS, NEVER, NUNCA, SIEMPRE, CRÍTICO, IMPORTANTE (caps lock o bold).
  2. Para cada match, pregúntate: ¿qué se rompe si esto se ignora? ¿Lo sabe alguien que lea esto?
  3. Si la razón no está en el doc, añádela. Si la razón es vaga ("para evitar problemas"), concretala con un caso real o un sistema afectado.
  4. Si la razón no se sostiene (la regla está ahí "porque siempre estuvo"), considera quitarla.
  5. Si encuentras "IMPORTANTE: foo" sin contexto, expándelo. La importancia es relativa — "importante para qué" es lo que el lector necesita.

Excepciones al principio

El principio no aplica con la misma fuerza en todos los contextos:

  • Constraints de seguridad/compliance donde el riesgo es alto: ahí el imperativo está bien. Pero aún así, añadir "razón: GDPR Art. 32 / SOC 2 control X" mejora la regla.
  • Convenciones de formato puras ("usa kebab-case para slugs"): no requieren razón porque no hay edge case interesante. Pero si la convención existe por una razón concreta (algunos sistemas no aceptan otra cosa), vale la pena mencionarla.
  • Comandos one-shot ("ejecuta pnpm test antes de commit"): el imperativo es el comando. La razón puede ir aparte si no es obvia.

Por qué esto funciona (meta)

Los LLMs modernos tienen buena theory of mind. Cuando entienden el propósito de una regla, la aplican mejor que cuando solo la siguen. Esto NO es porque ignoren las reglas — es porque pueden generalizarlas, lo cual es lo que quieres en producción.

Los humanos funcionan igual. Una regla con razón sobrevive cambios de contexto, transmisiones entre equipos, rotaciones de personal. Una regla sin razón se rompe en la primera reunión donde alguien con autoridad pregunta "¿por qué?" y nadie sabe responder.

Las skills, prompts y docs internos son código que humanos y LLMs ejecutan. Tratar el "por qué" como first-class hace que el código sea robusto.

Rebundle · Stack de IA curado