mrgnhnt96/beedle

¿Qué hace beedle?

Construye páginas de marketing que los motores de búsqueda y los rastreadores de IA puedan leer, que un desconocido entienda en diez segundos, y que solo afirmen lo que se pueda demostrar. Menos es más: cada sección debe ganarse su lugar. Cada ronda termina con una revisión independiente.

Lecciones: antes del paso 1, lee el archivo design/LESSONS.md del proyecto si existe y sigue cualquier indicación sobre su sitio de marketing. Son las correcciones del propietario.

1. Lee el proyecto

Averigua qué existe ya antes de preguntar nada: el stack y el alojamiento, cualquier sitio actual, el nombre real del producto, repositorio, listados en tiendas, precios, capturas de pantalla, tokens de diseño o tema, analítica, y docs/marketing/page-brief.md.

Construye en el stack que el proyecto ya usa. Para un sitio nuevo, sigue reference/seo.md ("Elegir un stack"). El contenido de marketing nunca se hace con Flutter web o renderizado del lado del cliente, porque los rastreadores pueden no verlo.

Usa el tema del proyecto si lo tiene (design/THEME.md, *.tokens.json). Si no, porta los tokens desde la aplicación. Si tampoco hay una aplicación de la que portar, escribe el único archivo pequeño de reference/small-theme.md, porque una página no necesita un sistema de diseño. Recurre a la habilidad ultrahand:theme solo cuando el usuario pida un tema, o cuando varios sitios o una aplicación tengan que compartirlo.

2. Elige el tipo y el estado de lanzamiento

Lee reference/page-types.md. Elige un tipo y un estado (pre-lanzamiento o en vivo), y anota las páginas de apoyo que el sitio necesita.

3. Escribe el brief

Guarda docs/marketing/page-brief.md en el proyecto, usando esta plantilla. Es el contrato que el revisor verificará contra la página, y el punto de partida para la siguiente sesión.

# Brief de la página

- Tipo y estado:
- Audiencia: (quiénes son y qué saben ya)
- El único objetivo de la página:
- CTA principal: (palabras exactas y destino)
- Acción secundaria: (una, más ligera, o "ninguna")
- Frases de búsqueda: (3-5 cosas que esta audiencia realmente escribe)
- Objeciones: (las razones reales por las que alguien se iría)
- Analítica y cookies: (qué se carga, o "ninguna")

## Afirmaciones

| Afirmación en la página | Evidencia |
| --- | --- |
| <cada número, cita, comparación, "primero", "más rápido", ...> | <archivo, enlace o medición, con fecha> |
| <una descripción simple de qué es o hace> | <archivo o enlace, o `Solo README` si eso es todo lo que hay> |

## Esperando a una persona

- <quién: qué debe hacer, o "nada">

Pregunta al usuario solo lo que el proyecto no pueda responder, normalmente la audiencia y la prueba. Nunca inventes pruebas. Un testimonio faltante es una sección faltante, no un marcador de posición para rellenar. Usa centinelas que fallen ruidosamente, como APP_STORE_ID_TODO, en lugar de valores falsos plausibles.

Cuando solo tienes el README, aún puedes construir la página. Puede decir claramente qué es y hace el producto: marca esas filas como Solo README. No puede probar números, fechas, versiones, licencia, precio, seguridad, privacidad o disponibilidad, así que busca una fuente primaria para cada uno: el código, un archivo LICENSE, una página de lanzamiento, un listado en un registro o tienda, una medición, o la palabra fechada del propietario. Cita esa fuente. Si no hay ninguna, deja la afirmación fuera de la página.

Cualquier cosa que solo una persona pueda proporcionar va a Esperando a una persona tan pronto como sepas de ella: una captura de pantalla real, un dominio, un precio a confirmar. Permanece allí hasta que lo hayan hecho.

4. Escribe las palabras primero

Sigue reference/message.md. Escribe el copy antes de cualquier diseño. Empieza desde los cinco bloques que se indican allí. Añade una sección solo cuando puedas nombrar la objeción que responde, y registra esa objeción en el brief.

5. Construye

Sigue reference/seo.md para lo que va en la página y junto a ella. Usa capturas de pantalla reales del producto o material gráfico, y nunca etiquetes una recreación como captura de pantalla. Una captura de la app real ejecutando datos de ejemplo es real: di que es un ejemplo en la página, y di cómo la hiciste en la tabla de afirmaciones. Sin nada real que mostrar, deja la imagen fuera, o deja un centinela si el tipo de página lo necesita. Evita las señales de diseño que se enumeran en la referencia del mensaje, ya que hacen que una página parezca generada antes de que alguien la haya leído.

6. Autoverificación

Construye el sitio y ejecuta la auditoría en la salida construida, luego corrige todos los errores que puedas:

beedle audit --dir <sitio construido>

Añade --exclude docs por cada sección que no sea de marketing (repetible). Si beedle no está en el PATH, dile al usuario que la auditoría no se ejecutó y que INSTALL.md dice cómo añadirlo.

Un error que solo una persona puede eliminar permanece, como un centinela DOMAIN_TODO para un dominio que nadie ha comprado. Nunca cambies un valor falso para obtener una ejecución limpia. Asegúrate de que esté en Esperando a una persona, luego continúa con la revisión.

7. Revisa la ronda

Cada ronda termina con una revisión por un revisor nuevo en su propia sesión, antes de que le digas al usuario que la página está lista. Una ronda es la primera construcción y cada indicación posterior que cambie la página, así que un cambio de una línea en el copy también se revisa. Omítela solo cuando el usuario diga que la omita en esta ronda, y di que la omitiste.

Iníciala tú mismo, sin que te lo pidan. No puedes revisar tu propia página de manera justa: ves lo que pretendías construir. Sigue review/round.md. En resumen, escribe el brief, ejecuta beedle review --brief <brief> --add-dir <proyecto> en segundo plano, luego actúa según los hallazgos. No publiques, despliegues ni des la página por terminada antes de esto.

8. Informa

Di qué construiste, el tipo y estado, el veredicto, y qué encontró la revisión, qué se corrigió y qué quedó pendiente, junto con su costo.

Si el veredicto es No se puede lanzar hasta que una persona actúe, lidera con eso: la página no está lista, quién debe hacer qué, y qué verificará la siguiente ronda una vez que lo hayan hecho. Nunca lo suavices a "casi terminado".

Siempre enumera lo que queda para el propietario después del lanzamiento: verificación de Search Console y Bing Webmaster, y la prueba de Resultados Enriquecidos en la página desplegada.

No despliegues a menos que el usuario lo pida.

9. Aprende

Cuando el propietario corrija el resultado o exprese una preferencia duradera, añade una línea al archivo design/LESSONS.md del proyecto (Créal-o si es necesario). Si la corrección muestra que estas reglas son incorrectas para todos los proyectos, corrige la regla también aquí.