Blueprint Authoring Standard¶

Fecha: 2026-06-10

Estado: ESTANDAR DOCUMENTAL V1

Scope: governance documental

portal_visible = yes

Fuente de verdad: docs/governance/documentation/BLUEPRINT-AUTHORING-STANDARD.md

Autoridades relacionadas:

1. Que es un blueprint¶

Un blueprint es un documento funcional estable que define un dominio de negocio antes de contratos, mappings, design, DDL, implementacion o automatizacion.

Su funcion es fijar:

lenguaje de dominio
frontera funcional
identidad conceptual
relaciones con otros dominios
reglas obligatorias
preguntas de negocio que debe responder
analytics, IA o ML que habilita
pendientes que no deben resolverse por suposicion

Un blueprint define el concepto de negocio. No define la query, la tabla, la vista, la migracion ni el pipeline.

2. Que NO es un blueprint¶

Un blueprint no es:

un SQL
un DDL
una migracion
una query
un mapping origen-destino
un contrato de datos
una fuente de autoridad
un inventario de resultados
una evidencia historica
un dashboard
una implementacion
una autorizacion para tocar runtime

Si un documento describe campos origen, correspondencias tecnicas, estructura fisica, ejecucion, resultados medidos o evidencia puntual, no debe llamarse blueprint.

3. Cuando crear un blueprint¶

Crear un blueprint solo cuando exista:

un dominio funcional claro
una frontera distinguible respecto de otros dominios
necesidad de lenguaje estable antes de diseno o implementacion
relacion trazable con sources, contracts, mappings, design o evidence
preguntas de negocio reales que el dominio debe responder
riesgo de drift si el concepto queda disperso en documentos tecnicos

Ejemplos validos:

cliente
producto
venta
ownership comercial
territorio

4. Cuando NO crear un blueprint¶

No crear un blueprint cuando:

el tema es una subtarea o una mejora tecnica
el contenido ya pertenece a source, mapping, contract, design o evidence
no hay pregunta de negocio clara
el documento solo repite definiciones ya existentes
la frontera del dominio no esta clara
se intenta justificar una implementacion todavia no aprobada
el documento seria decorativo o no tendria uso operativo

Regla de sobriedad:

no crear blueprints decorativos
no crear blueprints para aparentar madurez
no crear un blueprint si un enlace a la autoridad existente alcanza

5. Estructura minima obligatoria¶

Todo blueprint nuevo debe incluir estas secciones, en este orden o con titulos equivalentes que conserven el mismo significado:

Definicion del dominio
Que representa para OpenClaw/APV
Fuente primaria actual
Identidad y claves de negocio
Estados o clasificaciones
Relaciones con otros dominios
Reglas obligatorias
Preguntas de negocio que debe responder
Analytics / IA / ML que habilita
Diseno futuro relacionado
Que NO es este blueprint
Pendientes

Un blueprint puede agregar secciones adicionales cuando ayudan a cerrar frontera, alcance o confirmaciones, pero no debe borrar ni mezclar estas secciones minimas.

6. Relacion con sources¶

Los documentos sources/ describen fuentes, disponibilidad, limites y semantica observada.

Un blueprint puede declarar una fuente primaria actual, pero no debe copiar su inventario ni redefinir su autoridad.

Regla:

una afirmacion operacional sobre origen, cobertura, campo observado, formato, calidad o disponibilidad debe estar respaldada por source, inventory o contract

7. Relacion con mappings¶

Los mappings describen correspondencias origen-destino y reglas tecnicas de traduccion.

Un blueprint puede explicar por que un mapping sera necesario, pero no debe duplicar listas de campos ni reglas campo por campo.

Regla:

el blueprint define la frontera del dominio
el mapping define como viaja cada campo

8. Relacion con contracts¶

Los contracts definen compromisos funcionales de datos.

Un blueprint puede referenciar un contract como autoridad de reglas transversales, pero no debe reescribirlo completo.

Regla:

si una regla contractual ya existe, el blueprint debe enlazarla y aplicarla al dominio sin crear una definicion paralela

9. Relacion con design¶

Los documentos de design bajan decisiones a arquitectura, grupos de tablas, DDL documental o implementacion futura.

Un blueprint debe terminar antes del design.

Regla de autoridad:

el blueprint define el concepto de negocio
el design define la forma tecnica futura
el DDL define una estructura documental o ejecutable segun aprobacion
la implementacion real exige aprobacion explicita

10. Relacion con DDL e implementation¶

Un blueprint no habilita:

crear tablas
crear migraciones
ejecutar queries
tocar PostgreSQL
tocar runtime
tocar VPS
tocar Docker
crear codigo

Si un blueprint menciona nombres conceptuales futuros, deben leerse como referencias de diseno, no como objetos existentes ni autorizados.

11. Relacion con evidence¶

La evidencia respalda o bloquea decisiones. No redefine el dominio.

Un blueprint puede enlazar evidencia cuando una afirmacion operacional depende de datos observados, pero no debe convertirse en inventario.

Regla de evidencia:

toda afirmacion operacional debe tener respaldo en source, inventory, contract o design relacionado
si falta evidencia, declarar pendiente o pendiente de validar
no completar huecos con supuestos

12. Regla de no duplicar definiciones¶

Cada definicion oficial debe tener una sola fuente de verdad.

Antes de escribir una definicion, el autor debe revisar si ya existe autoridad en:

constitution
governance
business observer governance model
data contract
source
mapping
design
evidence
blueprint existente

Si existe autoridad, el nuevo blueprint debe enlazarla y solo explicar su aplicacion al dominio.

13. Regla de estabilidad¶

Un blueprint debe cambiar menos que source, mapping o design.

Lectura esperada:

sources cambian cuando cambia evidencia de origen
mappings cambian cuando cambia traduccion campo a campo
design cambia cuando cambia la forma tecnica
blueprint cambia solo cuando cambia el concepto de negocio, su frontera o sus reglas funcionales

14. Regla de autoridad¶

El blueprint define:

que es el dominio
que representa para negocio
que identidad funcional tiene
que preguntas debe responder
que reglas no se pueden violar

El blueprint no define:

query ejecutable
tabla fisica
migracion
vista fisica
calculo final de produccion
permisos tecnicos
performance

15. Regla de sobriedad¶

Un blueprint debe ser claro, util y accionable.

Debe evitar:

repetir texto largo de fuentes tecnicas
copiar tablas de mappings
crear glosarios paralelos
prometer implementacion
inflar alcance
documentar por decoracion

Un buen blueprint deja al equipo con menos ambiguedad y mas criterio para decidir que se puede disenar despues.

16. Criterio de aceptacion¶

Un blueprint queda aceptable cuando:

declara dominio y frontera
identifica fuente primaria actual
define identidad y claves de negocio
separa estados o clasificaciones
relaciona dominios vecinos
lista reglas obligatorias
explicita preguntas de negocio
enlaza analytics, IA o ML habilitados
separa diseno futuro de implementacion real
declara que no es
preserva pendientes
no duplica autoridad existente
no habilita runtime ni estructuras fisicas

17. Regla de visibilidad en Knowledge Portal¶

Todo blueprint nuevo o revisado debe evaluar su visibilidad en el OpenClaw Knowledge Portal usando la clasificacion definida en Document Hierarchy.

Criterio por defecto:

blueprints funcionales principales: portal_visible = yes
blueprints propuestos, incompletos o en discusion: portal_visible = pending_review
documentos que contengan runtime, seguridad, credenciales o detalle operativo sensible: portal_visible = internal_only

Un blueprint aceptado con portal_visible = yes debe quedar enlazado desde mkdocs.yml o desde un README local que ya sea navegable en el portal.

18. Confirmaciones de alcance¶

Este estandar:

no toca runtime
no toca VPS
no toca Docker
no toca PostgreSQL
no ejecuta queries
no crea codigo
no crea tablas
no crea migraciones
solo gobierna documentacion Blueprint