amrable/agent-skills

Mental

Explica el sistema a través de sus actores, límites y comunicación.

Contrato de salida: diagrama primero

Una explicación mental completa DEBE incluir un diagrama en la propia respuesta. Escribe una oración corta para orientar al lector, luego incluye inmediatamente:

• Un bloque mermaid delimitado usando sequenceDiagram y autonumber (el valor predeterminado).
• Una imagen D2 renderizada e incrustada, si la renderización está disponible y se solicita D2.

Luego explica el flujo y su evolución en prosa concisa. Construye el diagrama antes de escribir la explicación más larga, para que el elemento visual no se pueda omitir al final. Este contrato también se aplica a respuestas cortas y explicaciones complementarias que continúen una discusión de modelo mental invocada explícitamente. Una pregunta de aclaración por sí sola no necesita un diagrama. Si el usuario solicita explícitamente que no haya diagrama, sigue esa solicitud.

Las flechas ASCII, las listas con viñetas, las tablas, los bloques de código normales, un enlace a un diagrama, una promesa de dibujar uno más tarde y el código fuente D2 sin renderizar no cumplen con este contrato. No preguntes si el usuario quiere un diagrama. Si no hay ningún renderizador disponible, emite el código fuente Mermaid de todos modos; no lo reemplaces con texto porque el chat podría no renderizarlo. No se necesita ninguna herramienta de generación de diagramas para un bloque de código Mermaid.

Ejemplo de la forma de respuesta requerida (adapta los actores al contexto real):

El navegador le pide a la API que guarde datos; la API posee el acceso a la base de datos.

```mermaid
sequenceDiagram
    autonumber
    participant Navegador
    participant API
    participant BaseDeDatos
    Navegador->>API: Guardar datos del formulario
    API->>BaseDeDatos: Almacenar datos aceptados
    BaseDeDatos-->>API: Registro guardado
    API-->>Navegador: Respuesta de éxito
```

El formulario comienza en el navegador. Agregar una API permite guardarlo de forma remota; agregar una
base de datos permite que los datos guardados sobrevivan a una solicitud individual.

Invocación explícita

Usa esta skill solo cuando el usuario la solicite explícitamente: /mental, $mental, o una solicitud directa para usar la skill mental. Una solicitud general de una explicación no activa esta skill. Trata esto como una solicitud de explicación, no como permiso para implementar, instalar, publicar o cambiar el sistema que se explica.

Usa el tema que sigue a la invocación, o infiérelo de la conversación. Haz una sola pregunta enfocada solo si el tema no se puede inferir razonablemente.

Construye la explicación

1. Fundamenta el modelo en la conversación y la evidencia disponible. Para un código base existente, inspecciona solo los puntos de entrada o la configuración necesaria para establecer las relaciones relevantes. Distingue los hechos observados de las suposiciones. No inventes servicios, implementaciones exitosas ni comportamientos verificados.
2. Comienza con el sistema útil más pequeño: un script ejecutándose localmente, un navegador mostrando una página, o un servicio respondiendo a una solicitud. Explica lo que ya funciona antes de introducir infraestructura.
3. Progresa hacia el sistema en discusión. En cada etapa significativa, explica la nueva necesidad, el actor o la conexión agregada para satisfacerla, y cómo una acción ahora viaja a través del sistema. Estas son etapas explicativas, no afirmaciones sobre la cronología histórica. Si el usuario pregunta sobre la evolución real del proyecto, usa el historial disponible e identifica las lagunas.
4. Elige actores según el contexto: personas, procesos, servicios, almacenamiento, registros, colas o proveedores externos. Asigna a cada uno un rol concreto. Agrupa actores relacionados por máquina, proceso o límite de red cuando la ubicación afecte la comprensión.
5. Rastrea una acción concreta a través de los actores en orden, incluyendo el resultado que regresa a la persona que llama. Etiqueta lo que cruza cada límite: código fuente, archivo de paquete, solicitud HTTP, respuesta JSON, evento o datos almacenados. Separa la configuración y distribución de la comunicación en tiempo de ejecución cuando ambos sean importantes.
6. Explica las distinciones solo donde resuelvan confusión. Por ejemplo, un nombre de paquete selecciona qué buscar, un nombre de comando selecciona qué ejecutar y un argumento se convierte en entrada para ese comando. Para un ejemplo de navegador/API, distingue la entrega de código de las solicitudes posteriores a la API.

Prefiere una progresión corta con prosa conectada en lugar de un glosario o un catálogo de componentes. Si el usuario solo quiere la interacción actual, muestra ese flujo sin forzar una larga evolución. Los comandos y fragmentos deben anclar el modelo; evita los inventarios de banderas, los recorridos de implementación y las alternativas no relacionadas. Conserva los detalles que cambian el modelo, como una caché que evita una descarga o un reconocimiento asíncrono que llega antes de que termine el trabajo.

Precisión del diagrama

Cada respuesta producida con esta skill debe contener al menos un diagrama Mermaid o una imagen D2 renderizada. El valor predeterminado es un bloque mermaid delimitado: no requiere herramientas de renderizado y el código fuente sigue siendo legible cuando la renderización no está disponible.

• Prefiere un diagrama de secuencia numerado: comienza los diagramas Mermaid con sequenceDiagram seguido de autonumber. Haz que el orden de las llamadas, mensajes y respuestas sea visible. Introduce a los participantes en un orden legible de izquierda a derecha.
• Numera las respuestas así como las solicitudes para que el lector pueda seguir la interacción completa. Rastrea los pasos numerados en la prosa; mantén las referencias consistentes con el diagrama. La numeración muestra el escenario ilustrado, no una afirmación de que el trabajo concurrente siempre se ejecuta en un orden fijo. Usa par, alt u opt cuando la concurrencia, las alternativas o los pasos opcionales cambien el modelo.
• Para una evolución, usa secuencias numeradas pequeñas separadas para etapas significativas; mantén estables los nombres de los participantes y explica qué actor o mensaje se agregó.
• Usa un diagrama de flujo solo cuando la topología o la estructura sea la pregunta principal y una secuencia la oscurezca, o cuando el usuario lo solicite. Para imágenes D2 que muestren una interacción, prefiere un diseño de secuencia y numera explícitamente los mensajes.
• Usa nombres de actores concretos y flechas direccionales etiquetadas con acciones o datos. Evita las flechas sin etiquetar y los cuadros decorativos que no explican nada.
• Mantén cada diagrama enfocado en la interacción que se está explicando. Divide las diferentes fases o los sistemas abarrotados en diagramas pequeños. En los diagramas por etapas, marca qué actores y conexiones se introducen recientemente.
• Mantén las etiquetas simples y entrecomilla las etiquetas de los diagramas de flujo que contengan puntuación. Verifica las referencias a nodos, la dirección de las flechas, los subgrafos y la sintaxis delimitada antes de enviar.
• Un registro de paquetes distribuye código; no lo dibujes ejecutando la CLI del usuario. Una base de datos almacena datos; no la dibujes iniciando solicitudes de aplicación ordinarias a menos que esa sea una característica real del sistema.
• Si el usuario prefiere D2 y hay un renderizador disponible, renderiza e inspecciona el resultado, luego incrusta la imagen. El código fuente D2 por sí solo no cumple con el requisito de imagen. Si la renderización no está disponible, usa Mermaid e indica brevemente la alternativa. No instales un renderizador solo para explicar el modelo.

Sigue el diagrama con un breve recorrido de la acción concreta. Termina cuando el modelo esté claro; no agregues tareas de implementación ni resúmenes genéricos.

Antes de enviar

Inspecciona la propia respuesta: ¿contiene un bloque mermaid delimitado o una imagen D2 renderizada e incrustada? Si no está presente ninguno, la explicación está incompleta. Agrega el diagrama antes de enviar. Para un diagrama de secuencia Mermaid, verifica que autonumber esté presente. Comprueba que sus flechas coincidan con la prosa y rastreen al menos una interacción real con actores concretos y comunicación etiquetada.

Ejemplos

Lee references/examples.md cuando los ejemplos ayuden a calibrar la explicación. Incluye distribución npm, llamadas frontend/backend, llamadas servicio a servicio y trabajos asíncronos. Adapta el enfoque al contexto real en lugar de importar esos actores a cada explicación.