theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/estandares-java/SKILL.md

@@ -0,0 +1,389 @@
+---
+name: estandares-java
+description: "Estándares de código Java para servicios Spring Boot y Quarkus: nomenclatura, inmutabilidad, uso de Optional, streams, excepciones, genéricos, CDI, patrones reactivos y estructura de proyecto. Aplica automáticamente las convenciones específicas de cada framework."
+---
+
+# Estándares de código Java
+
+Estándares para código Java (17+) legible y mantenible en servicios Spring Boot y Quarkus.
+
+## Cuándo usarla
+
+- Al escribir o revisar código Java en proyectos Spring Boot o Quarkus.
+- Al aplicar convenciones de nomenclatura, inmutabilidad o manejo de excepciones.
+- Al trabajar con records, sealed classes o pattern matching (Java 17+).
+- Al revisar el uso de Optional, streams o genéricos.
+- Al estructurar paquetes y el layout del proyecto.
+- **[QUARKUS]**: al trabajar con scopes de CDI, entidades Panache o pipelines reactivos.
+
+## Cómo funciona
+
+### Detección del framework
+
+Antes de aplicar los estándares, determina el framework a partir del archivo de build:
+
+- El archivo de build contiene `quarkus` → aplica las convenciones **[QUARKUS]**
+- El archivo de build contiene `spring-boot` → aplica las convenciones **[SPRING]**
+- Ninguno detectado → aplica solo las convenciones compartidas
+
+## Principios centrales
+
+- Prefiere la claridad sobre la astucia.
+- Inmutable por defecto; minimiza el estado mutable compartido.
+- Falla rápido con excepciones con significado.
+- Nomenclatura y estructura de paquetes consistentes.
+- **[QUARKUS]**: favorece el procesamiento en tiempo de build sobre el de ejecución; evita la reflexión en runtime cuando sea posible.
+
+## Ejemplos
+
+Las secciones siguientes muestran ejemplos concretos de Spring Boot, Quarkus y Java
+compartido para nomenclatura, inmutabilidad, inyección de dependencias, código reactivo,
+excepciones, estructura de proyecto, logging, configuración y tests.
+
+## Nomenclatura
+
+```java
+// BIEN: clases/records: PascalCase
+public class MarketService {}
+public record Money(BigDecimal amount, Currency currency) {}
+
+// BIEN: métodos/campos: camelCase
+private final MarketRepository marketRepository;
+public Market findBySlug(String slug) {}
+
+// BIEN: constantes: UPPER_SNAKE_CASE
+private static final int MAX_PAGE_SIZE = 100;
+
+// BIEN: [QUARKUS] recursos JAX-RS nombrados *Resource, no *Controller
+public class MarketResource {}
+
+// BIEN: [SPRING] controladores REST nombrados *Controller
+public class MarketController {}
+```
+
+## Inmutabilidad
+
+```java
+// BIEN: favorece records y campos final
+public record MarketDto(Long id, String name, MarketStatus status) {}
+
+public class Market {
+  private final Long id;
+  private final String name;
+  // solo getters, sin setters
+}
+
+// BIEN: [QUARKUS] las entidades active-record de Panache usan campos públicos (convención de Quarkus)
+@Entity
+public class Market extends PanacheEntity {
+  public String name;
+  public MarketStatus status;
+  // Panache genera los accessors en tiempo de build; aquí los campos públicos son idiomáticos
+}
+
+// BIEN: [QUARKUS] entidades Panache para MongoDB
+@MongoEntity(collection = "markets")
+public class Market extends PanacheMongoEntity {
+  public String name;
+  public MarketStatus status;
+}
+```
+
+## Uso de Optional
+
+```java
+// BIEN: devuelve Optional desde métodos find*
+// [SPRING]
+Optional<Market> market = marketRepository.findBySlug(slug);
+
+// [QUARKUS] Panache
+Optional<Market> market = Market.find("slug", slug).firstResultOptional();
+
+// BIEN: map/flatMap en lugar de get()
+return market
+    .map(MarketResponse::from)
+    .orElseThrow(() -> new EntityNotFoundException("Market not found"));
+```
+
+## Buenas prácticas con streams
+
+```java
+// BIEN: usa streams para transformaciones y mantén los pipelines cortos
+List<String> names = markets.stream()
+    .map(Market::name)
+    .filter(Objects::nonNull)
+    .toList();
+
+// MAL: evita streams anidados complejos; prefiere bucles por claridad
+```
+
+## Inyección de dependencias
+
+```java
+// BIEN: [SPRING] inyección por constructor (preferible a @Autowired en campos)
+@Service
+public class MarketService {
+  private final MarketRepository marketRepository;
+
+  public MarketService(MarketRepository marketRepository) {
+    this.marketRepository = marketRepository;
+  }
+}
+
+// BIEN: [QUARKUS] inyección por constructor
+@ApplicationScoped
+public class MarketService {
+  private final MarketRepository marketRepository;
+
+  @Inject
+  public MarketService(MarketRepository marketRepository) {
+    this.marketRepository = marketRepository;
+  }
+}
+
+// BIEN: [QUARKUS] inyección en campo package-private (aceptable en Quarkus — evita problemas de proxies)
+@ApplicationScoped
+public class MarketService {
+  @Inject
+  MarketRepository marketRepository;
+}
+
+// MAL: [SPRING] inyección en campo con @Autowired
+@Autowired
+private MarketRepository marketRepository; // usa inyección por constructor
+
+// MAL: [QUARKUS] @Singleton cuando se necesita intercepción o inicialización perezosa
+@Singleton // no proxificable — usa @ApplicationScoped en su lugar
+public class MarketService {}
+```
+
+## Patrones reactivos [QUARKUS]
+
+```java
+// BIEN: devuelve Uni/Multi desde endpoints reactivos
+@GET
+@Path("/{slug}")
+public Uni<Market> findBySlug(@PathParam("slug") String slug) {
+  return Market.find("slug", slug)
+      .<Market>firstResult()
+      .onItem().ifNull().failWith(() -> new MarketNotFoundException(slug));
+}
+
+// BIEN: composición de pipelines no bloqueantes
+public Uni<OrderConfirmation> placeOrder(OrderRequest req) {
+  return validateOrder(req)
+      .chain(valid -> persistOrder(valid))
+      .chain(order -> notifyFulfillment(order));
+}
+
+// MAL: llamada bloqueante dentro de un pipeline Uni/Multi
+public Uni<Market> find(String slug) {
+  Market m = Market.find("slug", slug).firstResult(); // BLOQUEANTE — rompe el event loop
+  return Uni.createFrom().item(m);
+}
+
+// MAL: suscribirse más de una vez a un Uni compartido
+Uni<Market> shared = fetchMarket(slug);
+shared.subscribe().with(m -> log(m));
+shared.subscribe().with(m -> cache(m)); // doble suscripción — usa Uni.memoize()
+```
+
+## Excepciones
+
+- Usa excepciones no comprobadas (unchecked) para errores de dominio; envuelve las excepciones técnicas con contexto.
+- Crea excepciones específicas del dominio (p. ej., `MarketNotFoundException`).
+- Evita el `catch (Exception ex)` amplio salvo que relances o registres de forma centralizada.
+
+```java
+throw new MarketNotFoundException(slug);
+```
+
+### Manejo centralizado de excepciones
+
+```java
+// [SPRING]
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+  @ExceptionHandler(MarketNotFoundException.class)
+  public ResponseEntity<ErrorResponse> handle(MarketNotFoundException ex) {
+    return ResponseEntity.status(404).body(ErrorResponse.from(ex));
+  }
+}
+
+// [QUARKUS] Opción A: ExceptionMapper
+@Provider
+public class MarketNotFoundMapper implements ExceptionMapper<MarketNotFoundException> {
+  @Override
+  public Response toResponse(MarketNotFoundException ex) {
+    return Response.status(404).entity(ErrorResponse.from(ex)).build();
+  }
+}
+
+// [QUARKUS] Opción B: @ServerExceptionMapper (RESTEasy Reactive)
+@ServerExceptionMapper
+public RestResponse<ErrorResponse> handle(MarketNotFoundException ex) {
+  return RestResponse.status(Status.NOT_FOUND, ErrorResponse.from(ex));
+}
+```
+
+## Genéricos y seguridad de tipos
+
+- Evita los raw types; declara los parámetros genéricos.
+- Prefiere genéricos acotados (bounded) para utilidades reutilizables.
+
+```java
+public <T extends Identifiable> Map<Long, T> indexById(Collection<T> items) { ... }
+```
+
+## Estructura de proyecto
+
+### [SPRING] Maven/Gradle
+
+```
+src/main/java/com/example/app/
+  config/
+  controller/
+  service/
+  repository/
+  domain/
+  dto/
+  util/
+src/main/resources/
+  application.yml
+src/test/java/... (espeja main)
+```
+
+### [QUARKUS] Maven/Gradle
+
+```
+src/main/java/com/example/app/
+  config/              # beans @ConfigMapping, @ConfigProperty, Producers
+  resource/            # recursos JAX-RS (no "controller")
+  service/
+  repository/          # implementaciones PanacheRepository (si no se usa active record)
+  domain/              # entidades JPA/Panache, entidades MongoDB
+  dto/
+  util/
+  mapper/              # mappers MapStruct (si se usan)
+src/main/resources/
+  application.properties   # convención de Quarkus (YAML soportado con quarkus-config-yaml)
+  import.sql               # auto-import de Hibernate para dev/test
+src/test/java/... (espeja main)
+```
+
+## Formato y estilo
+
+- Usa 2 o 4 espacios de forma consistente (estándar del proyecto).
+- Un solo tipo público de nivel superior por archivo.
+- Mantén los métodos cortos y enfocados; extrae helpers.
+- Ordena los miembros: constantes, campos, constructores, métodos públicos, protegidos, privados.
+
+## Malos olores de código a evitar
+
+- Listas de parámetros largas → usa DTOs/builders.
+- Anidamiento profundo → retornos tempranos.
+- Números mágicos → constantes con nombre.
+- Estado mutable estático → prefiere inyección de dependencias.
+- Bloques catch silenciosos → registra y actúa, o relanza.
+- **[QUARKUS]**: `@Singleton` donde se pretendía `@ApplicationScoped` — rompe los proxies y la intercepción.
+- **[QUARKUS]**: mezclar `quarkus-resteasy-reactive` y `quarkus-resteasy` (clásico) — elige un solo stack.
+- **[QUARKUS]**: Panache active-record + patrón repository en el mismo bounded context — elige uno.
+
+## Logging
+
+```java
+// [SPRING] SLF4J
+private static final Logger log = LoggerFactory.getLogger(MarketService.class);
+log.info("fetch_market slug={}", slug);
+log.error("failed_fetch_market slug={}", slug, ex);
+
+// [QUARKUS] JBoss Logging (por defecto, costo cero en tiempo de build)
+private static final Logger log = Logger.getLogger(MarketService.class);
+log.infof("fetch_market slug=%s", slug);
+log.errorf(ex, "failed_fetch_market slug=%s", slug);
+
+// [QUARKUS] Alternativa: logging simplificado con @Inject
+@Inject
+Logger log; // inyectado por CDI, con alcance de la clase declarante
+```
+
+## Manejo de nulos
+
+- Acepta `@Nullable` solo cuando sea inevitable; en el resto de casos usa `@NonNull`.
+- Usa Bean Validation (`@NotNull`, `@NotBlank`) en las entradas.
+- **[QUARKUS]**: aplica `@Valid` en parámetros `@BeanParam`, `@RestForm` y en el cuerpo de la petición.
+
+## Configuración
+
+```java
+// [SPRING] @ConfigurationProperties
+@ConfigurationProperties(prefix = "market")
+public record MarketProperties(int maxPageSize, Duration cacheTtl) {}
+
+// [QUARKUS] @ConfigMapping (con tipos seguros, validado en tiempo de build)
+@ConfigMapping(prefix = "market")
+public interface MarketConfig {
+  int maxPageSize();
+  Duration cacheTtl();
+}
+
+// [QUARKUS] Valores simples con @ConfigProperty
+@ConfigProperty(name = "market.max-page-size", defaultValue = "100")
+int maxPageSize;
+```
+
+## Expectativas de testing
+
+### Compartido
+- JUnit 5 + AssertJ para aserciones fluidas.
+- Mockito para mocks; evita los mocks parciales cuando sea posible.
+- Favorece tests deterministas; sin sleeps ocultos.
+
+### [SPRING]
+- `@WebMvcTest` para slices de controladores, `@DataJpaTest` para slices de repositorios.
+- `@SpringBootTest` reservado para tests de integración completos.
+- `@MockBean` para sustituir beans en el contexto de Spring.
+
+### [QUARKUS]
+- JUnit 5 plano + Mockito para tests unitarios (sin `@QuarkusTest`).
+- `@QuarkusTest` reservado para tests de integración con CDI.
+- `@InjectMock` para sustituir beans CDI en tests de integración.
+- Dev Services para base de datos/Kafka/Redis — evita configurar Testcontainers a mano cuando Dev Services bastan.
+- `@QuarkusTestResource` para el ciclo de vida de servicios externos personalizados.
+
+```java
+// [SPRING] Test de controlador
+@WebMvcTest(MarketController.class)
+class MarketControllerTest {
+  @Autowired MockMvc mockMvc;
+  @MockBean MarketService marketService;
+}
+
+// [QUARKUS] Test de integración
+@QuarkusTest
+class MarketResourceTest {
+  @InjectMock
+  MarketService marketService;
+
+  @Test
+  void should_return_404_when_market_not_found() {
+    given().when().get("/markets/unknown").then().statusCode(404);
+  }
+}
+
+// [QUARKUS] Test unitario (sin CDI, sin @QuarkusTest)
+@ExtendWith(MockitoExtension.class)
+class MarketServiceTest {
+  @Mock MarketRepository marketRepository;
+  @InjectMocks MarketService marketService;
+}
+```
+
+**Recuerda**: mantén el código intencional, tipado y observable. Optimiza para la mantenibilidad por encima de las micro-optimizaciones salvo que se demuestren necesarias.
+
+## Skills relacionadas
+
+- `patrones-springboot`
+- `patrones-quarkus`
+- `tdd-springboot`
+- `tdd-quarkus`

package/vendor/theus-arsenal/skills/estilo-legado/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: estilo-legado
+description: Skill de herencia de estilo para proyectos legados. Úsala cuando el usuario escriba /estilo-legado, o al incorporar un agente de programación de IA a un proyecto legado escrito a mano y necesites prevenir la "deriva de estilo" (que el modelo imponga sus idiomas mainstream preentrenados sobre el proyecto). Agnóstica de lenguaje y framework — alinea solo la meta-arquitectura, no la sintaxis. Una vez ejecutada, se convierte en una restricción de comportamiento para todas las tareas de código posteriores. NO usar para investigación pura ni preguntas puntuales no relacionadas con la alineación de estilo de código.
+allowed-tools: Read, Glob, Grep, Bash, Edit, Write, AskUserQuestion
+---
+
+# Heredar Estilo Legado
+
+Previene la deriva de estilo del código generado por IA en proyectos legados escaneando la base de código en busca de convenciones implícitas en 4 dimensiones de meta-arquitectura, resolviendo los conflictos con el usuario de uno en uno, y cristalizando el consenso en un `.ai-style-rules.md` exigible. Totalmente agnóstica de lenguaje y framework.
+
+## Cuándo activarla
+
+- El usuario escribe `/estilo-legado`
+- El usuario menciona la incorporación de IA a un proyecto legado escrito a mano
+- El usuario está preocupado porque el código generado por IA "derive" de las convenciones existentes del proyecto
+- El usuario quiere extraer y codificar las reglas de codificación implícitas de su proyecto
+
+## Cuándo usarla
+
+Usa esta skill cuando necesites preservar el estilo de un proyecto legado y prevenir la deriva de estilo generada por IA. Consulta **Cuándo activarla** arriba para las condiciones de disparo.
+
+## Prerrequisitos
+
+- Git (recomendado; los proyectos sin Git recurren a las marcas de tiempo de archivos para el modo incremental)
+- Acceso de lectura/escritura a la raíz del proyecto (genera `.ai-style-rules.md` y opcionalmente `THEUS.md`)
+
+## Flujo de trabajo
+
+### Paso 0 — Autodetectar el modo
+
+Comprueba en silencio si existe `.ai-style-rules.md` en la raíz del proyecto:
+
+| ¿Existe el archivo? | Modo |
+|---|---|
+| No | **Rama A — Escaneo completo inicial** |
+| Sí | **Rama B — Sondeo incremental** |
+
+Anuncia el modo en una línea y continúa — nunca pidas al usuario que elija.
+
+### Rama A — Escaneo completo inicial
+
+**1. Mide la escala y elige un nivel de escaneo**
+
+```bash
+git ls-files | grep -cE '\.(js|ts|jsx|tsx|vue|py|go|rs|java|kt|rb|php|cs|swift|c|cpp|h)$'
+```
+
+| Nivel | Archivos fuente | Estrategia |
+|---|---|---|
+| Pequeño | ≲ 50 | Lectura minuciosa completa de cada fuente |
+| Mediano | 50–500 | Capa de infraestructura = lectura completa; capa de negocio = muestrear 2–3 por dimensión |
+| Grande | ≳ 500 | Muestreo estricto + tope de presupuesto; primero resumen `--stat`, luego lecturas dirigidas |
+
+**2. Escanea a lo largo de 4 dimensiones**
+
+1. **Anatomía de archivo** — orden de declaración dentro del archivo (imports → tipos → lógica principal → helpers → export)
+2. **Estado y flujo de control** — convenciones de nombres para estado asíncrono, paginación, flags
+3. **Infraestructura** — dónde viven las utilidades transversales (interceptores, formateadores, middleware)
+4. **Manejo de errores** — try/catch vs interceptor global vs retorno Result; hábitos de comprobación de null
+
+**3. Aplica reducción de ruido por umbral de señal**
+
+Antes de interrumpir al usuario, evalúa la fuerza de la señal:
+
+- **Señal débil** → suprimir automáticamente: minoría <5% Y conteo <10 → gana la mayoría, la minoría va a los DONTs
+- **Señal fuerte** → interrogar: división casi pareja, o bifurcación semántica en una dimensión central
+- **Excepción de proyecto pequeño**: fuentes ≲50, un "3 vs 2" NO es mayoría → interrógalo
+
+**4. Resuelve los conflictos de uno en uno (Protocolo de interrogatorio)**
+
+Para cada conflicto de señal fuerte, presenta exactamente UNA pregunta con 4 opciones:
+
+> Evidencia: `rutaA` usa el estilo X, `rutaB` usa el estilo Y
+> ADVERTENCIA: Riesgo: mezclar ambos fractura el estilo del proyecto
+> Elige: `1` seguir X  `2` seguir Y  `3` esto es evolución, actualiza las reglas  `4` tengo una regla nueva
+
+Suspende hasta que el usuario responda, luego pasa al siguiente conflicto. Nunca acumules preguntas.
+
+**5. Genera `.ai-style-rules.md`** con tres secciones obligatorias:
+- **[Golden Files]** — rutas de archivos ejemplares reales anotadas con lo que demuestran
+- **[Reglas de nombres y estado-control]** — convenciones concretas y verificables
+- **[DONTs]** — antipatrones que no deben propagarse
+
+**6. Instala el hook persistente**
+
+Pregunta al usuario por la fuerza de aplicación (usa `AskUserQuestion`):
+
+| Opción | Mecanismo |
+|---|---|
+| **1** Hook suave (recomendado) | Escribir la referencia `@.ai-style-rules.md` en el `THEUS.md` del proyecto |
+| **2** Hook duro | Hook suave + hook `PreToolUse[Write\|Edit\|MultiEdit]` en `settings.json` |
+| **3** Sin hook | Conservar el archivo de reglas; el usuario lo referencia manualmente |
+
+### Rama B — Sondeo incremental
+
+1. Lee el `.ai-style-rules.md` existente; si tiene una huella de commit, `git diff <last_hash> HEAD --stat` para localizar el delta
+2. Lee los cambios recientes de Git (`git log -3 --stat` → inspecciona archivos sospechosos bajo demanda)
+3. Para diffs sobredimensionados (>cientos de archivos): solo resumen `--stat` + muestrear los cambios más grandes
+4. Compara el código nuevo con las reglas registradas → los conflictos pasan por el Protocolo de interrogatorio
+5. Añade un registro de evolución al final de `.ai-style-rules.md` (nunca sobrescribas reglas antiguas)
+
+### Aplicación por turno
+
+Cuando `.ai-style-rules.md` está en contexto (cargado vía THEUS.md), toda tarea de escritura de código debe abrir con una **declaración de cumplimiento** en la cadena de razonamiento, nombrando el ejemplar que se sigue y los DONTs que se evitan.
+
+## Cómo funciona
+
+Esta skill autodetecta si es una ejecución inicial o incremental según la presencia de `.ai-style-rules.md`:
+
+- **Inicial (Rama A)** — Mide la escala del proyecto, escanea la base de código en 4 dimensiones de meta-arquitectura (Anatomía de archivo, Estado y flujo de control, Infraestructura, Manejo de errores), aplica reducción de ruido por umbral de señal para suprimir conflictos débiles, resuelve los conflictos de señal fuerte de uno en uno con el usuario, genera `.ai-style-rules.md` con Golden Files / Reglas de nombres / DONTs, y ofrece hooks de aplicación opcionales.
+- **Incremental (Rama B)** — Lee las reglas existentes, revisa los diffs recientes de Git en busca de patrones nuevos o conflictivos, ejecuta el mismo protocolo de interrogatorio de uno en uno para los conflictos encontrados, y añade registros de evolución sin sobrescribir las reglas existentes.
+- **Aplicación por turno** — Cuando está enganchada vía `THEUS.md`, cada tarea de escritura de código abre con una declaración de cumplimiento que nombra el ejemplar seguido y los DONTs evitados.
+
+## Especificación de salida
+
+- `.ai-style-rules.md` en la raíz del proyecto (con huella de commit + nivel de escala en el encabezado)
+- Opcionalmente `THEUS.md` con la referencia `@.ai-style-rules.md`
+- Registros de evolución añadidos como entradas `### [YYYY-MM-DD] Registro de evolución de estilo`
+
+## Antipatrones
+
+- FALLO: NO te saltes el paso de medición de escala — muestrear un proyecto de 30 archivos lo "deja en hambruna"; escanear completo un repo de 5.000 archivos lo hace explotar
+- FALLO: NO acumules varias preguntas de conflicto a la vez — el interrogatorio es estrictamente de uno en uno
+- FALLO: NO sobrescribas reglas antiguas en modo incremental — añade siempre registros de evolución
+- FALLO: NO impongas el "hook duro" por defecto sin preguntar — la fuerza de aplicación la decide el usuario
+- FALLO: NO juzgues la calidad de la sintaxis ni del stack tecnológico — esta skill alinea solo la meta-arquitectura
+- FALLO: NO copies bugs de los archivos ejemplares — reutiliza la estructura, señala los defectos
+
+## Buenas prácticas
+
+- Anuncia el modo detectado (inicial vs incremental) y el nivel de escala en una línea antes de escanear
+- Para proyectos grandes, lee primero los resúmenes `--stat` y luego haz `Read` dirigido sobre los archivos sospechosos
+- Deja que el umbral de señal maneje el ruido — una división de nombres de 843 contra 8 debe autoresolverse sin interrumpir al usuario
+- Ante la duda sobre la fuerza de la señal, inclínate por preguntar
+- El hook suave en THEUS.md (`@.ai-style-rules.md`) suele ser suficiente; hook duro solo si el usuario quiere aplicación mecánica
+
+## Ejemplos
+
+1. **Incorporación inicial**
+   - Usuario: "Ayúdame a incorporar la IA a esta base de código antigua sin cambiar su estilo."
+   - Acción: Ejecutar el escaneo completo de la Rama A → medir escala → escanear las 4 dimensiones → interrogar conflictos → generar `.ai-style-rules.md` → ofrecer fuerza de hook (suave/duro/ninguno).
+
+2. **Actualización incremental tras cambios del equipo**
+   - Usuario: "Añadimos un módulo nuevo; mantén intactas las reglas de estilo existentes."
+   - Acción: Ejecutar el sondeo incremental de la Rama B → comparar los deltas de Git con las reglas registradas → interrogar conflictos nuevos → añadir registro de evolución sin sobrescribir.
+
+3. **Aplicar los DONTs vía THEUS.md**
+   - Usuario: "Asegúrate de que todo el código nuevo se mantenga consistente con las reglas del proyecto."
+   - Acción: Hook suave instalado → `.ai-style-rules.md` se carga automáticamente en cada sesión → cada tarea de escritura de código abre con la declaración de cumplimiento, reutilizando los patrones ejemplares y evitando los DONTs.

package/vendor/theus-arsenal/skills/estructura-informes-competencia/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: estructura-informes-competencia
+description: Úsala después de que metodologia-benchmarks haya producido las fichas de competidores puntuadas. Ensambla los hallazgos en un informe apto para decidir — mapa del paisaje, perfiles de competidores, matriz de benchmarking, análisis de espacio en blanco, recomendaciones estratégicas y preguntas detonantes para alinear al equipo. Paso final del pipeline competitivo de tres skills.
+---
+
+# Estructura de informes de competencia
+
+Usa esta skill para ensamblar las fichas de competidores puntuadas en un informe apto para decidir. El informe debe responder tres preguntas para el cliente: **con quién competimos, cómo competimos y dónde está nuestro espacio en blanco defendible.** Cada sección se gana su lugar acercando esas respuestas — recorta todo lo que no lo haga.
+
+## Cuándo activarla
+
+- Todas las fichas de competidor de `metodologia-benchmarks` están completas y listas para ensamblar.
+- Hay que presentar los hallazgos competitivos a una persona fundadora, un equipo directivo o un consejo.
+- El informe debe impulsar decisiones (con quién competir, cómo, dónde está el foso) — no solo documentar el paisaje.
+- Se prepara un entregable de cliente que debe ser auditable y defendible.
+
+## Brief de posicionamiento del cliente (establécelo primero)
+
+Antes de ensamblar el informe, establece el brief de posicionamiento del cliente. Aporta:
+
+- **Tensión estratégica** — el par de ejes (p. ej., memorabilidad × contratabilidad) que define el espacio en blanco objetivo. Todos los mapas y la síntesis se resuelven contra esta tensión.
+- **Balance de marca** — la mezcla proporcional intencional de los énfasis estratégicos del cliente (p. ej., 60 % estrategia/evidencia, 25 % distintividad, 15 % oficio). Toda recomendación se contrasta contra este balance; señala las que lo desplazarían.
+- **Diferenciador** — el principio de encuadre para el resumen ejecutivo y la sección de espacio en blanco.
+- **Cuadrante objetivo** — dónde pretende situarse el cliente en el mapa de tensión; confirmar si ese cuadrante está genuinamente libre es la pregunta empírica central del informe.
+
+## Principio de encuadre
+
+Todo el informe se organiza en torno a la tensión estratégica del cliente y las recomendaciones se resuelven contra su balance de marca deliberado. Las recomendaciones que romperían ese balance deben señalarse explícitamente — "este movimiento desplaza el balance de X/Y/Z hacia A/B/C; confirma la intención."
+
+## Secciones del informe
+
+### 1. Resumen ejecutivo
+3–5 conclusiones, decisión primero. Enuncia los hallazgos más importantes en lenguaje llano: dónde es fuerte el cliente, dónde está expuesto, quién ocupa su espacio en blanco objetivo y los 2–3 movimientos principales. Escrito para que una persona fundadora o de producto lea solo esto y sepa qué hacer. Sin metodología aquí.
+
+### 2. Paisaje de mercado y encuadre de categoría
+Define la categoría y mapéala. Usa un **mapa multieje** — como mínimo un 2×2 (p. ej., *guiado por marca <-> guiado por capacidad* × *boutique <-> escala enterprise*), e idealmente el **plot de tensión del cliente** de `metodologia-benchmarks` como mapa de cabecera. Coloca a cada competidor perfilado y al cliente. El mapa debe hacer visualmente obvia la posición pretendida del cliente y mostrar cuán poblada (o vacía) está.
+
+### 3. Tiers de competidores
+Organiza el conjunto en **Directo / Adyacente / Aspiracional** (de `analisis-plataformas-competencia`). Un párrafo corto por tier explicando quién está y por qué importa al cliente. Esto fija las expectativas del lector antes del detalle.
+
+### 4. Matriz de benchmarking
+La tabla completa **competidores × dimensiones** — la espina cuantitativa. Filas = competidores (agrupados por tier), columnas = las nueve dimensiones de benchmark (nota: la dimensión 9 — tensión estratégica — tiene dos polos (p. ej., Memorabilidad y Contratabilidad para un cliente estudio de marca; sustituye por el par de ejes propio del cliente); represéntalos como dos subcolumnas separadas, sin promediarlos). Incluye la autoevaluación honesta del cliente como fila de contraste. Usa un **heatmap** (escala de color o de símbolos) para que los patrones de fuerza/debilidad se escaneen de un vistazo. **No** añadas una columna de total combinado — reporta las dimensiones por separado (según los controles de sesgo). Señala las columnas donde el cliente lidera y donde va rezagado.
+
+### 5. Análisis en profundidad
+Los 3–5 competidores más instructivos en forma narrativa (a partir de sus fichas). Elígelos por instrucción, no por ranking: el mejor ejemplar de la tensión objetivo (alto en ambos polos), el caso de advertencia "un solo polo", el arquetipo "competente pero olvidable" contra el que el cliente se define, más cualquier amenaza directa. Cada análisis: qué hacen, qué debe aprender el cliente, qué debe evitar.
+
+### 6. Espacio en blanco y amenazas
+El corazón estratégico. Dos partes:
+
+- **Espacio en blanco:** la posición que el cliente puede apropiarse y los rivales no ocupan — argumentada desde los mapas y la matriz, no asertada. Confirma si el cuadrante objetivo (del brief de posicionamiento) está genuinamente libre.
+- **Amenazas:** quién o qué presiona al cliente — un rival cerrando la brecha, sustitutos (herramientas no-code/IA, equipos internos, freelancers generalistas) o giros de categoría. Sé honesto sobre los riesgos propios del cliente (p. ej., una identidad atrevida que lea como poco seria para compradores adversos al riesgo).
+
+### 7. Recomendaciones estratégicas
+Movimientos concretos y priorizados: con quién compite el cliente, cómo se diferencia y dónde invertir (empaquetado de oferta, evidencia/casos de estudio, liderazgo de pensamiento, afilado de marca). **Ata cada recomendación al balance de marca del brief de posicionamiento** y señala las que lo desplazarían. Secuencia por impacto × esfuerzo.
+
+### 8. Apéndice de fuentes / metodología
+Las dimensiones, pesos, rúbricas, el conjunto delimitado con sus tiers, enlaces a fuentes por competidor y notas de verificación (afirmado vs probado). Esto es lo que hace el informe auditable y defendible — mantén la disciplina de citación adversarial hasta el final.
+
+## Cómo presentar los datos
+
+- **Mapas 2×2 / de posicionamiento** — para el paisaje y el plot de tensión. Ábrelos tú; llevan el argumento más rápido que la prosa.
+- **Matriz heatmap** — para la comparación competidores × dimensiones (sección 4).
+- **Fichas de perfil** — la unidad fuente que alimenta los análisis en profundidad (sección 5).
+- **Llamados por cuadrante** — nombra explícitamente quién ocupa cada cuadrante, sobre todo el objetivo del cliente.
+- Mantén las tablas escaneables; empuja la evidencia cruda y los enlaces al apéndice.
+
+## Marco de decisión (el informe debe resolverlo)
+
+- **¿Con quién competimos?** — Nombra el tier Directo en concreto; esa es la pelea real.
+- **¿Cómo competimos?** — Enuncia el diferenciador del cliente en una frase, anclado en la matriz (qué dimensiones domina el cliente).
+- **¿Dónde son defendibles nuestros diferenciadores?** — Identifica las dimensiones/el cuadrante que los rivales no pueden copiar fácilmente (el foso), frente a lo que es apuesta de mesa.
+
+## Preguntas detonantes para la sesión de alineación del equipo
+
+Cierra con preguntas que fuercen decisiones, no admiración por el análisis:
+
+- ¿El cuadrante objetivo está de verdad libre, o un rival ya se está moviendo hacia él?
+- ¿Qué competidor Directo es la amenaza más afilada en los próximos 12 meses, y cuál es la respuesta?
+- ¿Se sostiene el balance de marca dado el paisaje — debería moverse algún énfasis?
+- ¿Qué dimensión rezagada vale la pena cerrar, y cuál conceder deliberadamente?
+- ¿Cuál es el movimiento único que más amplía la distintividad *sin* costar contratabilidad / credibilidad?
+
+## Antipatrones
+
+- **Abrir con metodología.** El resumen ejecutivo abre con el hallazgo más importante, no con una explicación de cómo se corrió el benchmark. La metodología va al apéndice.
+- **Presentar puntuaciones sin el plot de tensión.** El mapa de tensión 2×2 es el artefacto de cabecera. Una tabla de números sin el mapa entierra el insight estratégico.
+- **Omitir el marco de decisión.** El informe debe resolver las tres preguntas (con quién competir, cómo, dónde está el foso). Dejarlas sin respuesta lo convierte en una revisión bibliográfica.
+- **Empezar antes de completar todas las fichas.** `metodologia-benchmarks` debe terminar antes de ensamblar. Los datos parciales producen huecos que socavan el heatmap y el análisis de espacio en blanco.
+- **Añadir una columna de total combinado a la matriz.** Excluida explícitamente — crea un compuesto falso que oculta la asimetría sobre la que el cliente debe actuar.
+
+## Skills relacionadas
+
+- `metodologia-benchmarks` — el prerrequisito; produce las fichas de competidores puntuadas que esta skill ensambla.
+- `analisis-plataformas-competencia` — aporta la estructura de tiers (Directo / Adyacente / Aspiracional) usada en la sección 3.
+- `descubrimiento-marca` — úsala para establecer el brief de posicionamiento del cliente si aún no está definido.