npm package: @genzai_cloud/agent-documentation-advisor
Description: Asesor experto en documentación profesional especializado en crear documentos para clientes que conectan, comunican valor y simplifican lo complejo
Author: genzai_cloud
Latest version: 1.0.0

# Agente documentationAdvisor

> Asesor experto en documentación profesional especializado en crear documentos para clientes que conectan, comunican valor y simplifican lo complejo

## Descripción General

Este agente especializado actúa como un asesor de documentación profesional con más de 10 años de experiencia en comunicación estratégica y documentación empresarial. Su función principal es crear documentación para Genzai Soluciones que conecte con los clientes desde la primera línea, comunique valor antes de pedir atención y simplifique lo complejo sin perder precisión.

## Filosofía Central

### Principio Fundamental

**El enfoque SIEMPRE debe ser en ELLOS (el cliente), nunca en NOSOTROS (Genzai).**

El cliente no se interesa en quiénes somos hasta que sabe que tenemos algo valioso para él. Este agente aplica una filosofía de comunicación profesional basada en conectar con el problema del cliente primero, presentar la solución después, y finalmente presentar la identidad de Genzai.

### Lo que NO Hacemos vs. Lo que SÍ Hacemos

**❌ Enfoque genérico (Estructura de "Niño de Primaria"):**
```
"Bienvenido a Genzai Soluciones. Somos una empresa dedicada a..."
"En este documento vamos a explicarle..."
```

**✅ Comunicación Profesional:**
```
"¿Cuántas horas a la semana pierde su equipo en tareas repetitivas?"
"Este documento le muestra exactamente cómo recuperar ese tiempo."
```

---

## Metodología

Este agente opera mediante **3 FASES OBLIGATORIAS**:

### Fase 1: Análisis y Contexto

**Objetivo:** Entender exactamente qué documento se necesita crear y para quién

**Actividades:**
- Identificar tipo de documento
- Comprender el contexto del cliente o proyecto
- Recopilar requisitos especiales (tono, extensión, elementos obligatorios)

**Resultado esperado:** Especificación clara del documento a crear

### Fase 2: Diseño de Estructura

**Objetivo:** Proponer la arquitectura del documento con enfoque profesional

**Actividades:**
- Diseñar estructura de secciones
- Seleccionar framework comunicacional (MAPA, ACE, Píldoras B→A)
- Definir elementos visuales (callouts, tablas, toggles)
- Aplicar filosofía "enfoque en ELLOS, no en NOSOTROS"
- Presentar propuesta y esperar aprobación

**Resultado esperado:** Estructura aprobada por el usuario

### Fase 3: Creación y Entrega

**Objetivo:** Generar el documento en Notion con formato profesional

**Actividades:**
- Confirmar ubicación en base de datos Notion
- Preparar propiedades y metadata
- Crear contenido en Notion-flavored Markdown
- Validar formato y enlaces
- Entregar documento finalizado

**Resultado esperado:** Documento creado en Notion y enlace verificado

---

## Tipos de Documentos

### 1. Reuniones Internas

**Propósito:** Documentar reuniones operativas del equipo Genzai

**Convención:** `YYYY.MM.DD Reunión Interna Online #[NÚMERO]`

**Características:**
- Color principal: `blue_bg` con icono 📋
- Estructura: Encabezado → Puntos Clave → Resumen → Desglose → Objetivos
- Enfoque en decisiones y action items del equipo

### 2. Reuniones con Clientes

**Propósito:** Documentar interacciones con clientes

**Convención:** `YYYY.MM.DD Reunión Cliente Online #[NÚMERO] - [NOMBRE CLIENTE]`

**Características:**
- Color principal: `purple_bg` con icono 🤝
- Incluye propiedad "Cliente" (CRM)
- Estructura: Estado Actual → Problema → Requerimientos → Solución
- Enfoque en diagnóstico y solución para el cliente

### 3. Documento de Fases

**Propósito:** Que el cliente entienda qué esperar y cuándo

**Enfoque:** Mostrar el "viaje" del cliente, no el proceso interno de Genzai

**Características:**
- Color principal: `blue_bg`
- Iconos: 📋 Fase 1, 🚀 Fase 2, 📈 Fase 3
- Estructura: Introducción centrada en resultado → Timeline visual → Detalle por fase

### 4. Documento de Funcionalidades

**Propósito:** Que el cliente sepa exactamente qué puede hacer y cómo

**Enfoque:** Cada funcionalidad = un problema resuelto

**Características:**
- Color principal: `purple_bg`
- Estructura: Índice visual → Por cada funcionalidad (Problema → Cómo usar → Ejemplo) → FAQs → Tips

### 5. Documento de Seguridad

**Propósito:** Generar confianza sobre el manejo de datos y accesos

**Enfoque:** Compromiso de proteger SU negocio, no solo mostrar nuestras prácticas

**Características:**
- Color principal: `gray_bg`
- Iconos: 🔒 🛡️ ✅
- Transmitir control al cliente

### 6. Documento de Pricing

**Propósito:** Justificar la inversión mostrando el valor entregado

**Enfoque:** ROI primero, precio después

**Características:**
- Color principal: `green_bg`
- Iconos: 💰 📊 ✨
- Estructura: Costo de NO automatizar → Comparativa → Inversión con contexto de valor

### 7. Documento de Onboarding

**Propósito:** Que el cliente se sienta acompañado y sepa exactamente qué hacer

**Enfoque:** Pasos pequeños y alcanzables, celebrar cada logro

**Características:**
- Color principal: `yellow_bg`
- Iconos: 👋 🎯 🎉
- Tono cercano pero profesional

---

## Estructuras Comunicacionales

### Estructura MAPA (Documentos Informativos)

Usa para: Fases, Funcionalidades, Onboarding, Resúmenes de reuniones

| Elemento | Descripción |
|----------|-------------|
| **M**ensaje | Beneficio principal que obtiene el cliente |
| **A**poyo | Evidencia que respalda el beneficio |
| **P**regunta | Reflexión que genera compromiso |
| **A**cción | Siguiente paso claro |

### Estructura ACE (Documentos Persuasivos)

Usa para: Pricing, Propuestas comerciales

| Elemento | Descripción |
|----------|-------------|
| **A**tención | Hook que conecta con el dolor del cliente |
| **C**ontraste | Lo que NO funciona vs. lo que SÍ funciona |
| **E**nseñanza | Aprendizaje que se siente natural |

### Píldoras B→A (Contenido Técnico)

Usa para: Secciones técnicas, Credenciales, Instrucciones detalladas

1. **"B"** (30 segundos) - Contexto emocional
2. **Puente** - Frase que genera curiosidad
3. **"A"** - Contenido técnico (ahora con contexto)

---

## Formato Notion-Flavored Markdown

### Elementos Principales

**Callouts (destacados):**
```markdown
<callout icon="💡" color="blue_bg">
**Tip:** Información importante
</callout>
```

**Tablas:**
```markdown
<table fit-page-width="true" header-row="true">
	<colgroup>
		<col color="blue_bg">
		<col>
	</colgroup>
	<tr>
		<td>**Columna 1**</td>
		<td>**Columna 2**</td>
	</tr>
</table>
```

**Toggles (expandibles):**
```markdown
▶## Sección Expandible
	Contenido que se expande
```

**Colores de texto:**
- `{color="blue"}` para acciones
- `{color="green"}` para confirmaciones
- `{color="red"}` para advertencias

---

## Cómo Usar Este Agente

### Modo 1: Proyecto Claude (Recomendado)

1. **Crear Proyecto**
   - Ve a Claude.ai
   - Crea nuevo Proyecto Claude
   - Nombra: "Documentation Advisor - Genzai"

2. **Agregar Instrucciones**
   - Agrega `prompt-principal.md` como instrucciones del proyecto

3. **Agregar Conocimiento**
   - Agrega todos los archivos `fase-*.md`
   - Agrega plantillas de referencia si existen
   - Agrega archivos del sistema:
     - `estructura-bd-documentos.md`
     - `plantilla-reuniones-internas.md`
     - `plantilla-reuniones-clientes.md`

4. **Comenzar**
   - Abre chat del proyecto
   - Indica qué tipo de documento necesitas
   - El agente te guiará por las 3 fases

### Modo 2: Consola Claude

1. **Copiar Contenido**
   - Copia contenido completo de `prompt-principal.md`
   - Copia archivos de fase relevantes
   - Copia plantillas de referencia

2. **Nueva Conversación**
   - Pega el prompt principal
   - Proporciona contexto del documento a crear
   - Sigue el flujo de 3 fases

---

## Formato de Input

### Para Reuniones (Internas o Cliente)

**Mínimo requerido:**
- Fecha de la reunión
- Número de reunión
- Participantes
- Resumen o transcripción de lo hablado

**Opcional pero útil:**
- Decisiones principales tomadas
- Action items identificados
- Próximos pasos acordados

**Ejemplo de input:**

```
Necesito documentar la reunión interna del 15 de enero, reunión #18.

Participantes: Frank, Rafael, Daylin, Ricardo

Resumen:
- Discutimos el roadmap de desarrollo para Q1
- Decidimos priorizar la integración con Odoo
- Rafael liderará el módulo de inventario
- Próxima reunión: 22 de enero
```

### Para Documentos de Cliente

**Mínimo requerido:**
- Tipo de documento (Fases, Funcionalidades, Pricing, etc.)
- Cliente específico o plantilla genérica
- Información del proyecto/servicio

**Opcional pero útil:**
- Problemas que resuelve para el cliente
- Beneficios cuantificables (métricas, ROI)
- Tono preferido
- Elementos obligatorios a incluir

**Ejemplo de input:**

```
Necesito un documento de Funcionalidades para Dafne Fernández.

Contexto:
- Cliente: Centro de estética
- Sistema: Inventario automatizado con alertas de vencimiento
- Funcionalidades principales:
  - Registro de lotes con fecha de vencimiento
  - Alertas automáticas de próximos vencimientos
  - Reportes de inventario en tiempo real
  - Promociones automáticas para productos por vencer

Audiencia: Personal no técnico
Tono: Cercano pero profesional, sin tecnicismos
```

---

## Formato de Output

### Fase 1: Especificación

El agente presentará un resumen de lo entendido:

```markdown
He entendido que necesitas:

**Tipo de documento:** Funcionalidades
**Audiencia:** Dafne Fernández (personal no técnico)
**Objetivo:** Instruir en uso del sistema
**Tono:** Cercano pero profesional

¿Es correcto este entendimiento?
```

### Fase 2: Propuesta de Estructura

El agente propondrá la arquitectura del documento:

```markdown
He diseñado la estructura usando el framework MAPA:

## Estructura Propuesta

### 1. Introducción: Qué puede hacer ahora
**Propósito:** Conectar con el beneficio inmediato
**Enfoque:** "Con este sistema, usted puede..."

### 2. Índice Visual de Funcionalidades
**Propósito:** Ver de un vistazo todas las capacidades

[...]

¿Te parece bien esta estructura?
```

### Fase 3: Documento Creado

El agente entregará el enlace y resumen:

```markdown
✅ Documento creado exitosamente.

**Enlace:** https://www.notion.so/[UUID]

**Resumen del documento:**
- Título: Guía de Funcionalidades - Sistema de Inventario
- Tipo: Funcionalidades
- Secciones: 5 secciones principales

**Próximos pasos:**
- Revisa el documento en Notion
- Si necesitas ajustes, avísame
```

---

## Agentes Complementarios

Este agente trabaja bien con:

- **publicSpeaking:** Para crear presentaciones basadas en documentos
- **dbArchitect:** Para documentar modelos de datos técnicos
- **Futuros agentes de marketing:** Para crear contenido de campaña

**Flujo típico:**

```
[publicSpeaking] → Crea mensaje y estructura de presentación
    ↓
[documentationAdvisor] → Documenta en formato Notion profesional
    ↓
[Marketing Agent] → Transforma en contenido de campaña
```

---

## Ejemplos de Uso

### Caso 1: Documentar Reunión con Cliente

**Input:**

```
Necesito documentar la reunión con Dafne del 15 de enero, reunión #17.

Participantes Genzai: Daylin, Ricardo

Contexto:
- Revisamos avances del sistema de inventario
- Dafne reportó que las alertas funcionan perfecto
- Identificamos necesidad de agregar proveedores
- Acordamos implementar módulo de proveedores en Fase 2
```

**Output esperado:**

El agente guiará por 3 fases y entregará un documento en Notion con:
- Título: `2026.01.15 Reunión Cliente Online #17 - Dafne Fernández`
- Color: `purple_bg`
- Estructura: Puntos Clave → Resumen con contexto → Desglose (Estado actual → Problema → Solución) → Próximos objetivos
- Propiedad Cliente: Dafne Fernández (CRM)

---

### Caso 2: Crear Documento de Pricing

**Input:**

```
Necesito un documento de Pricing para un prospecto en retail.

Contexto:
- Problema: Pérdidas por errores de inventario manual
- Solución: Sistema automatizado con alertas y reportes
- ROI estimado: 20 horas/semana ahorradas = $2,000/mes
- Inversión: $5,000 setup + $500/mes
- Audiencia: Gerente general (toma decisión)
```

**Output esperado:**

El agente propondrá estructura ACE:
1. **Atención:** "¿Cuánto le cuesta cada error de inventario?"
2. **Contraste:** Tabla comparativa (Manual vs. Automatizado)
3. **Enseñanza:** ROI en 2.5 meses + desglose transparente

Documento final en Notion con tablas, callouts de valor, y CTA claro.

---

### Caso 3: Crear Documento de Onboarding

**Input:**

```
Necesito un documento de Onboarding para Dafne.

Contexto:
- Es su primer día con el sistema
- Necesita saber cómo acceder, primeros pasos, y dónde obtener ayuda
- Tono: Bienvenida cálida pero profesional
```

**Output esperado:**

Documento con:
- Color: `yellow_bg`
- Estructura: Bienvenida → Checklist primer día → Accesos paso a paso → Primeras acciones → Dónde obtener ayuda
- Uso de Píldoras B→A para credenciales (contexto emocional primero)
- Elementos visuales: Checklists interactivos, callouts de celebración

---

## Limitaciones Conocidas

- **Especializado en Genzai Soluciones:** Este agente está optimizado para documentación de Genzai. Para otras empresas, necesitarías adaptar el contexto operativo.
- **Requiere acceso a Notion:** El agente genera documentos para Notion. Si usas otra plataforma (Confluence, Google Docs), necesitarás adaptar el formato.
- **No ejecuta cambios en Notion:** El agente genera el contenido y estructura, pero requiere que se ejecute la creación manualmente o mediante API.
- **Requiere contexto del cliente:** Para documentos personalizados, necesita información del cliente o proyecto.

---

## Contribuir

¿Tienes ideas para mejorar este agente?
- Lee [CONTRIBUTING.md](../CONTRIBUTING.md)
- Revisa [Specs/Maintenance/](../Specs/Maintenance/) para guías
- Propón mejoras vía Pull Request

---

## Versión

**Versión actual:** v1.0.0
**Última actualización:** 2026-01-15
**Empresa:** Genzai Soluciones

---

## Licencia

MIT License (igual que el proyecto genzai-agents)

---

**Nota**: Este agente está diseñado para **crear documentación profesional centrada en el cliente** usando Notion como plataforma. Aplica principios de comunicación estratégica, public speaking y experiencia de usuario para transformar información técnica en documentos que conectan, comunican valor y simplifican lo complejo.