---
name: humand-features-notion
description: Documentar features de Humand en la base "Humand Features" de Notion, en bilingüe ES/EN, con audiencia Sales + CX. Recopila contexto desde Jira, Figma, Slack, Granola y Notion existente; redacta con el template oficial (Resumen, Funcionamiento, Demo, FAQs) respetando estilos (callouts gris para Resumen, callouts rojos para warnings, divisores ---, <empty-block/>, headers tipo "R E S U M E N", subsecciones ###). Si falta info crítica, pregunta antes de inventar. Usar cuando un PM de Humand pida documentar una funcionalidad, crear o actualizar una page de Humand Features, o preparar contenido de un feature para Sales/CX.
---

# Documentar features de Humand en Notion

Skill para que cualquier PM de Humand pueda crear o actualizar pages en la base **Humand Features** de Notion siguiendo el template oficial. El contenido es **bilingüe ES/EN** y está orientado a **Sales y Customer Experience (CX)**, no a perfiles técnicos.

## Audiencia y tono

El contenido se redacta para personas de **Sales y CX** que necesitan:

- Explicar funcionalidades a clientes existentes o potenciales.
- Vender nuevas features.
- Responder preguntas de clientes sobre cómo funciona algo.

**SÍ incluir**: qué hace el feature, cómo se usa, dónde se ve en el producto, FAQs de negocio, restricciones que afectan al usuario final.
**NO incluir**: endpoints, código, nombres de tablas/campos del modelo, grants, lógica de backend, criterios de aceptación técnicos, links a Jira o a Figma.

**Lenguaje**: simple, concreto, sin jerga técnica. En vez de "se modifica el modelo de datos para incluir X", decir "ahora se puede ver X en el perfil del usuario".

## Base "Humand Features" en Notion

- **Data source ID**: `4d305723-a37f-45d4-bbd6-3db7dfac4b99`
- **URL**: `https://www.notion.so/humand-co/f9e67d89d2fe44c4a957f29f0725e078`

### Propiedades a completar

| Propiedad | Tipo | Obligatorio |
|---|---|---|
| `[ES] Feature` | Título en español | Sí |
| `[EN] Feature` | Título en inglés | Sí |
| `[ES] Description` | Descripción corta ES (1-2 líneas) | Sí |
| `[EN] Description` | Descripción corta EN (1-2 líneas) | Sí |
| `Status` | Estado (Developing, Released, etc.) | Sí |
| `EQA` | Quarter (ej. 2026Q1) | Si se conoce |
| `Squad` | Squad responsable del feature | Si se conoce |
| `Mini-App` | Mini-app asociada | Si aplica |

**Formato del título**: `[Rol o vista] | [Acción que hace el feature]` (ej. "Agent | Descargar reporte consolidado…", "Admin | Configurar workflow de aprobación…").

## Estructura del template

Toda página sigue este orden exacto:

```
<table_of_contents color="gray"/>

# 🇪🇸 ES - DESCRIPCIÓN
---
**R E S U M E N**
---
<callout gris con 1-3 oraciones>
<empty-block/>
**F U N C I O N A M I E N T O**
---
### Subsección 1
... contenido ...
---
### Subsección 2
... contenido ...
<empty-block/>
**D E M O**
---
<capturas o video del producto>
<empty-block/>
**F A Q s**   ← opcional, solo si hay preguntas reales identificadas
---
1. ...
<empty-block/>
<empty-block/>

# 🇺🇸 EN - DESCRIPTION
---
**S U M M A R Y**
... espejo exacto de la versión ES ...

<empty-block/>
<empty-block/>

<details>                    ← sugerido por default; ver "Reglas de estilo → Changelog"
<summary>📝 Changelog</summary>

- **YYYY-MM-DD** — Descripción breve del cambio (lo último primero).
- **YYYY-MM-DD** — Cambio previo.

</details>
```

## Reglas de estilo (no negociables)

- **Resumen (ES) y Summary (EN)**: dentro de callout gris.
  ```
  <callout icon="/icons/light-bulb_gray.svg" color="gray">
      Texto del resumen. Usar <br> para saltos de línea cuando haga falta.
  </callout>
  ```
- **Headers de bloque** (R E S U M E N, F U N C I O N A M I E N T O, D E M O, F A Q s / S U M M A R Y, H O W  I T  W O R K S, D E M O, F A Q s): en **negrita** con **un espacio entre cada letra**. En "H O W  I T  W O R K S" hay dos espacios entre palabras. NO usar `##` ni `###` para estos headers.
- **Divisores `---`**: inmediatamente después del header de bloque y entre cada subsección de Funcionamiento.
- **Subsecciones de Funcionamiento**: con `###`. No meter todo en un único párrafo; estructurar por temas (ej. "Acceso", "Configuración inicial", "Resultado", "Diferencias por rol", "Entrega"…) separados por `---`.
- **`<empty-block/>`**: para separación visual entre el final de un bloque y el header siguiente, y antes del título de la versión EN.
- **Warnings / restricciones críticas**: callout rojo con icono de warning.
  ```
  <callout icon="/icons/warning_red.svg" color="red_bg">
      **Importante: …**
      - Punto 1
      - Punto 2
  </callout>
  ```
- **Demo**:
  - SÍ: capturas del producto en uso, videos grabados del producto (`<video src="...">`), **capturas exportadas de Figma como imagen** (`![descripción](url)`).
  - NO: links directos a Figma (Sales y CX no tienen acceso).
- **FAQs**: lista numerada (`1. 2. 3.`) o con viñetas. Sección **opcional** — incluir solo si hay preguntas reales identificadas (de CX, Sales o del equipo).
- **Listas**: indentar sub-bullets con tabs, no espacios. Listas numeradas cuando hay orden (pasos), viñetas cuando son enumeraciones.
- **Espejo ES ↔ EN**: la versión EN debe tener exactamente las mismas secciones y subsecciones que la ES, en el mismo orden.
- **Changelog (sugerido por default, opt-out a pedido del PM)**: por default, cuando la skill o un script crea o modifica la page, agregar al final (después de la versión EN) un toggle `<details>📝 Changelog</details>` con la entrada nueva al principio. Si el PM pide explícitamente no incluirlo, omitirlo y dejar constancia de esa decisión al confirmar al PM. Si hay dudas en la primera edición, **preguntar** antes de inventar.
  ```
  <details>
  <summary>📝 Changelog</summary>

  - **YYYY-MM-DD** — Resumen breve del cambio realizado (qué se agregó / cambió / sacó).
  - **YYYY-MM-DD** — Entrada anterior, sin tocar.

  </details>
  ```
  - Cuando se usa: una línea por edición, fecha en formato `YYYY-MM-DD`, descripción concreta (ej. "Se agregó FAQ sobre límite mensual" o "Se reemplazó captura de Demo por video nuevo").
  - Para la creación inicial, la primera entrada es: `**YYYY-MM-DD** — Versión inicial.`
  - Si la page existía sin changelog y se acuerda incluirlo, agregar como primera entrada `Versión inicial sin changelog histórico` + la entrada del cambio actual.
  - El toggle nace **cerrado**, así no interfiere con la lectura de Sales/CX.
  - **Regla absoluta cuando el changelog está activo**: las entradas previas no se sobrescriben ni se borran; solo se agregan nuevas arriba.

## Workflow

```
- [ ] Paso 1. Recopilar contexto del feature (Notion, Jira, Figma, Slack, Granola)
- [ ] Paso 2. Evaluar qué información falta; si es crítica, preguntar antes de redactar
- [ ] Paso 3. Confirmar si ya existe una page para el feature y decidir crear o actualizar
- [ ] Paso 4. Redactar ES + EN, incluyendo warnings críticos, Demo y FAQs (si hay)
- [ ] Paso 5. Validar contra el checklist de estilo antes de publicar (incluye verificar el toggle Changelog si está activo)
- [ ] Paso 6. Publicar en Notion, devolver el link al PM y preguntar si falta ajustar algo
```

### Paso 1: Recopilar contexto

Buscar en paralelo en las fuentes disponibles:

**1a. Notion** — verificar si la page ya existe.
```
Tool MCP: notion-search
Query: nombre del feature
Si existe page en Humand Features → usar como base para actualizar.
Si existe doc de producto/ingeniería en otro lado → extraer info de negocio.
```

**1b. Jira** — buscar cards relacionadas para entender el alcance y comportamiento.
```
Buscar por título o componente del feature.
Leer las cards relevantes (descripción + comentarios) para extraer
contexto funcional. Ignorar tareas puramente técnicas (refactors, migraciones).
```

**1c. Figma** — obtener diseños para capturas de Demo.
```
Si hay link de Figma en Jira o Notion, abrirlo y exportar capturas
representativas de la UI. NO pegar el link de Figma en la doc;
sí incrustar la captura exportada como imagen.
```

**1d. Slack** — buscar conversaciones relevantes.
```
Útil para: decisiones de producto, preguntas frecuentes que ya hizo CX,
contexto de por qué se construyó el feature así.
```

**1e. Granola** — buscar menciones en reuniones grabadas.
```
Útil para: decisiones tomadas verbalmente, contexto de stakeholders.
Si la fuente no responde, continuar sin ella.
```

### Paso 2: Evaluar qué falta

Antes de redactar, verificar que se tiene:

```
- [ ] Qué hace el feature (resumen claro de 1-3 oraciones)
- [ ] Cómo se accede (dónde aparece en el producto)
- [ ] Cómo se usa paso a paso (desde la perspectiva del usuario final)
- [ ] Quién puede usarlo (permisos, roles)
- [ ] Restricciones o límites relevantes (rangos, cuotas, condiciones)
- [ ] Diferencias por rol o tipo de usuario si aplica
- [ ] Cómo se entrega el resultado (sincrónico, async, email, descarga…)
- [ ] Capturas o video del producto para Demo
- [ ] FAQs reales (si las hay)
- [ ] Traducción al EN
```

**Si falta información crítica → PREGUNTAR antes de inventar.** Ejemplos:

- "No encontré capturas. ¿Tenés screenshots del producto o las exporto de Figma?"
- "El spec no menciona si hay restricciones de uso. ¿Hay algún límite (cantidad, frecuencia, fechas)?"
- "¿Este feature ya está released o todavía en desarrollo?"
- "¿Hay diferencias entre roles (admin, agente, coordinador, etc.)?"

### Paso 3: Crear o actualizar

**Si ya existe la page en Humand Features:**

1. Leer contenido actual con `notion-fetch`.
2. Si la page ya tiene toggle `<details>📝 Changelog</details>`, asumir que el changelog está activo. Si no existe, asumir el default (incluirlo) salvo que el PM haya pedido explícitamente saltarlo.
3. Si el contenido existente sigue siendo válido y solo hay que agregar info, hacer `notion-update-page` con cambios puntuales y, cuando el changelog está activo, sumar una entrada nueva al inicio del toggle.
4. Si se reemplaza completamente, opcionalmente preservar el contenido viejo dentro de un `<details>` toggle al final (separado del de changelog), antes de reemplazar. Cuando el changelog está activo, registrar el reemplazo como entrada nueva.

**Si no existe:**

1. Crear con `notion-create-pages`.
2. Parent: `{"data_source_id": "4d305723-a37f-45d4-bbd6-3db7dfac4b99"}`.
3. Completar propiedades obligatorias + contenido completo.
4. Por default, incluir el toggle de Changelog al final con la primera entrada: `**YYYY-MM-DD** — Versión inicial.` Omitirlo solo si el PM pidió explícitamente no tener changelog.

### Paso 4: Redactar

Reglas de redacción:

- **Lenguaje simple**: como si le explicaras a alguien de Sales/CX qué hace el feature.
- **Sin jerga técnica**: evitar "endpoint", "payload", "query", "migration", "schema", "feature flag" (en su lugar: "configuración que habilita…").
- **Concreto**: en vez de "se modifica el modelo", decir "ahora se puede ver X en Y".
- **Bilingüe completo**: siempre ES + EN. No publicar con una versión a medias.
- **FAQs útiles**: pensar qué preguntaría un cliente o alguien de CX, no inventar preguntas decorativas.
- **Resumen / Summary**: 1-3 oraciones máximo. Decir qué hace y para qué público.
- **Funcionamiento**: subsecciones cortas con `###`, no párrafos largos.

### Paso 5: Validar antes de publicar

Checklist de estilo:

- [ ] Hay `<table_of_contents color="gray"/>` al inicio.
- [ ] Existen las dos secciones: `# 🇪🇸 ES - DESCRIPCIÓN` Y `# 🇺🇸 EN - DESCRIPTION`.
- [ ] Resumen y Summary están en callout gris con icono `light-bulb_gray.svg`.
- [ ] Funcionamiento está estructurado en subsecciones `###` con divisores `---` entre ellas (no es un único bloque).
- [ ] Warnings críticos están en callout `color="red_bg"` con icono `warning_red.svg`.
- [ ] Demo no tiene links a Figma — solo capturas del producto o capturas exportadas de Figma como imagen.
- [ ] La versión EN espeja exactamente las secciones de la ES (mismo orden, mismas subsecciones).
- [ ] `<empty-block/>` se usa para separación entre bloques mayores y antes del título EN.
- [ ] Los headers de bloque están en formato `**X X X X**` (negrita con espacios entre letras), no `##` ni `###`.
- [ ] Si hay FAQs, son lista numerada o con viñetas.
- [ ] Las propiedades de la base están completas (al menos las obligatorias).
- [ ] Si el changelog está activo (default), la page tiene un toggle `📝 Changelog` al final con una **entrada nueva** (fecha de hoy + descripción) correspondiente a esta edición. Si la page se creó ahora, la entrada es "Versión inicial". Si el PM pidió opt-out, este item se omite y se deja registro en el handoff.

### Paso 6: Verificar y cerrar

Después de publicar:

1. Devolver al PM el link a la page.
2. Preguntar si falta ajustar algo.
3. Si hay capturas pendientes, indicar dónde se quedaron los placeholders.
4. Si hay más features pendientes, preguntar si seguir.

## Anti-patrones a evitar

- ❌ Meter todo Funcionamiento en un solo párrafo sin subsecciones ni divisores.
- ❌ Usar `##` o `###` para los headers de bloque (R E S U M E N, F U N C I O N A M I E N T O, etc.); deben ser `**...**` con espacios entre letras.
- ❌ Linkear a Figma en Demo (Sales y CX no tienen acceso).
- ❌ Publicar sin la versión EN o con secciones diferentes entre ES y EN.
- ❌ Usar callout gris para algo distinto del Resumen/Summary.
- ❌ Usar callout rojo para info no crítica (se reserva para warnings o restricciones que afectan al usuario).
- ❌ Publicar sin el `<table_of_contents>` inicial.
- ❌ Inventar restricciones, permisos, fechas o comportamientos cuando el spec no los menciona — preguntar primero.
- ❌ Usar jerga técnica (endpoints, payload, schema, migration, etc.).
- ❌ Si el changelog está activo (default o acordado con el PM), publicar la edición sin sumar la entry correspondiente.
- ❌ Sobrescribir o borrar entradas previas del changelog: solo se **agregan** entradas nuevas arriba, las viejas quedan tal cual.
- ❌ Saltar el changelog "porque sí" sin confirmación del PM: si hay dudas, preguntar antes de omitirlo.

## Tools de Notion MCP relevantes

| Acción | Tool |
|---|---|
| Buscar features existentes | `notion-search` |
| Leer una page | `notion-fetch` |
| Crear nueva page de feature | `notion-create-pages` |
| Actualizar page existente | `notion-update-page` |
| Duplicar template como base | `notion-duplicate-page` |

**Markdown enriquecido de Notion**: soporta `<callout>`, `<details>`, `<table>`, `<columns>`, `<empty-block/>`, `<video>`. Para la spec completa, fetch del recurso `notion://docs/enhanced-markdown-spec`.
