Caprini Dev

014-editorial-intelligence/spec.md

SPEC-014 — Editorial Intelligence & Social Amplification

[TASK]: SDD - SPEC-014 EDITORIAL INTELLIGENCE

Project ID: 014
Título: SPEC-014 — Editorial Intelligence & Social Amplification
Id: projects/014-editorial-intelligence/spec
Punto de integración (futuro): scripts/create-episode.mjs (flujo npm run content:new)

1. CONTEXT

  • Estamos entrando en Fase 6: dejar de operar con un “becario redactor” y pasar a un Editor Jefe IA con criterio.
  • Objetivo inmediato: añadir inteligencia al flujo scripts/create-episode.mjs (comando npm run content:new) sin tocar la publicación automática en redes (seguimos en Web Intent + revisión humana).

2. OVERVIEW — Por qué necesitamos un AI Editor

Hoy el sistema puede generar episodios, pero no los certifica:

  • Puede colar tono corporativo (“sinergias”, “estrategia”, “best-in-class”) que mata el latido.
  • Puede romper la estructura narrativa que hace que el log sea un arma:
    Promesa / Síntoma / Autopsia / Corrección / Lección.
  • Puede cerrar el flujo sin dejar el contenido listo para difusión (texto social, URL canónica, mención).

Misión operativa de la Fase 6:

Que ninguna línea de código mal narrada llegue al radar público.

3. VALIDATION LOGIC — Skill: Tone Guard (El Guardián del Tono)

3.1. Objetivo del Tone Guard

Analizar el Markdown recién creado/actualizado y decidir si el episodio es CERTIFICABLE.

  • Si es certificable: el flujo puede continuar hacia la amplificación (Auto‑Amplifier).
  • Si no es certificable: el flujo debe fallar con mensaje explícito y guiar la corrección.

3.2. Entradas / salidas

  • Entrada: contenido completo del episodio en .md (texto + frontmatter).
  • Salida:
    • Resultado: PASS o FAIL.
    • Reporte: lista de hallazgos (estructura faltante, palabras prohibidas, señales corporativas).

3.3. Reglas de estructura (obligatorias)

El episodio debe contener, en este orden, los cinco bloques. Se considera válido solo si cada bloque existe como encabezado Markdown H2 (##):

  1. Promesa
  2. Síntoma
  3. Autopsia
  4. Corrección
  5. Lección

Criterio de fallo:

  • Falta cualquiera de los cinco encabezados.
  • Aparecen fuera de orden.
  • Cualquiera de los cinco aparece con un nivel distinto de H2 (por ejemplo ### Promesa): alarma de jerarquía inconsistente → FAIL.

Criterio de calidad mínima (no bloqueante en MVP, pero reportable):

  • Cada sección debería tener al menos 2–3 frases.
  • La Corrección debe incluir cambios concretos (archivo/s, comando/s, o decisión técnica verificable).
  • La Lección debe ser reutilizable (no solo “aprendí X”, sino “si ves Y, aplica Z”).

3.4. Reglas de tono (prohibiciones y alarmas)

3.4.1. Palabras prohibidas (bloqueantes)

El Tone Guard debe fallar si detecta vocabulario típicamente corporativo, en minúsculas o mayúsculas, incluyendo variantes básicas (plural/sufijos). Lista inicial (extensible):

  • sinergia / sinergias
  • stakeholders
  • roadmap
  • alineamiento
  • value proposition / propuesta de valor
  • best in class / best-in-class
  • leverage / apalancar / apalancamiento
  • escalabilidad (cuando se use como humo, sin métrica ni contexto)
  • optimización (cuando se use como humo, sin evidencia ni medición)
  • solución / soluciones (siempre)
  • problema / problemas (siempre)

Nota: “estrategia” no está prohibida por defecto, pero debe saltar como alarma si aparece sin sustancia técnica.

3.4.2. Señales corporativas (no bloqueantes en MVP, reportables)

El Tone Guard debe reportar advertencias cuando detecte patrones como:

  • Abuso de voz pasiva (“se procedió a…”, “fue implementado…”).
  • Autocelebración vacía (“increíble”, “revolucionario”) sin evidencia o constraint.
  • Cierre sin “autopsia” (se cuenta el final, pero no el diagnóstico).

3.5. Forzado de formato (estrategia)

En MVP, el Tone Guard es validator (falla/pasa) y no reescribe el episodio automáticamente.

En fases posteriores (no en este scope), se permite añadir un modo “repair” que:

  • Inserta encabezados faltantes como placeholders.
  • Propone reescrituras puntuales de frases corporativas.

4. SOCIAL FLOW — Skill: Auto-Amplifier (El Altavoz)

4.1. Objetivo del Auto-Amplifier

Al finalizar npm run content:new, el sistema debe generar un X Web Intent (sin credenciales) para que el humano publique con un clic.

4.2. Integración obligatoria

  • El Auto‑Amplifier se integra dentro de npm run content:new.
  • Solo se ejecuta si el Tone Guard devuelve PASS.

4.3. Formato del X Web Intent (MVP)

El Intent debe incluir:

  • Texto del hito: una frase breve que capture el “qué” + “por qué” (sin humo).
  • URL canónica: enlace a la URL pública del episodio (según el origen configurado del sitio).
  • Mención: debe incluir el string “Hacker Capybara” (literal), como firma pública del flujo.

Plantilla mínima sugerida (castellano, ajustable):

  • Texto: Hito: <frase>. Autopsia completa: <URL>. — Hacker Capybara

4.4. Fuente de datos para el texto social

MVP (sin inventar metadata nueva):

  • Priorizar seoTitle como titular social si existe; si no, title.
  • Usar metaDescription si existe; si no, description.

Regla anti‑relleno:

  • El texto social debe estar por debajo del límite de X considerando que la URL se acorta (t.co). Si excede, truncar solo la descripción con elipsis.

5. SAFETY RULES — No permitir episodios inválidos

5.1. Validación de contexto antes de crear

El flujo content:new debe impedir crear episodios si no existe contexto mínimo:

  • project_id válido: debe ser numérico y existir como carpeta bajo src/content/docs/projects/ cuando se trate de un episodio asociado a un proyecto.
  • series válido: si se está creando contenido de serie (colección series), debe existir el contexto de saga/serie correspondiente (no adivinar).

MVP: si el comando no puede demostrar el contexto, debe abortar y explicar qué falta.

5.2. Seguridad operacional

  • No se debe escribir ni exponer secretos en el contenido generado.
  • La amplificación es por Web Intent (no API de X), manteniendo el principio de: automatización asistida, no automatización ciega.
  • Doble guardado seguro (sagas): si se usa --saga o CAPRINI_ACTIVE_SAGA, el script debe verificar que el destino src/content/docs/sagas/<sagaSlug>/ es un repositorio Git válido (p. ej. worktree con .git archivo gitdir: o un .git/ directorio). Si no lo es, el flujo debe abortar antes de escribir para evitar archivos huérfanos.

6. PIPELINE INTEGRATION — “Contenido certificado”

6.1. Comportamiento requerido (salida de terminal)

El comando npm run content:new no solo crea el archivo: debe mostrar una salida con estética de log de sistema (escaneo) y finalizar imprimiendo exactamente:

CONTENIDO CERTIFICADO POR CAPRINI_AI. LISTO PARA DIFUSIÓN.

Formato de escaneo requerido (ejemplos):

  • [CHECKING_STRUCTURE]... [FAILED]
  • [CHECKING_FORBIDDEN_WORDS]... [FAILED]
  • [CHECKING_TONE]... [CERTIFIED]

Si falla un check, el proceso debe abortar (exit code ≠ 0) y listar los hallazgos en rojo neón. Si pasa con warnings, imprimirlos en amarillo neón y continuar.

6.2. Condición para imprimir el sello

Solo debe imprimirse si:

  • Tone Guard: PASS
  • Auto‑Amplifier: Intent generado (o al menos la URL del Intent construida y presentada)

Si falla cualquiera de los dos:

  • No se imprime el sello.
  • El comando termina con estado de error (exit code ≠ 0) y reporte de fallos.

7. CRITERIOS DE ACEPTACIÓN (para la implementación futura)

  • Un episodio creado con content:new que cumpla estructura y tono pasa el Tone Guard.
  • content:new genera un X Web Intent que contiene:
    • texto del hito,
    • URL canónica,
    • la mención “Hacker Capybara”.
  • El comando termina con el sello exacto:
    CONTENIDO CERTIFICADO POR CAPRINI_AI. LISTO PARA DIFUSIÓN.
  • Si falta project_id/series válido, el comando aborta con mensaje claro.

8. REFERENCIAS CRUZADAS

  • Router normativo: src/content/docs/system/DOC_ROUTER.md
  • Estándares SEO (frontmatter): .cursor/rules/10-seo-standards.mdc
  • Amplificación asistida previa: src/content/docs/projects/003-blog-sharer/spec.md (X Web Intent, sin API)