jumibot/documento_fundacional

Documento fundacional

El documento fundacional presenta un proyecto, o un producto de una familia, de forma formal y compacta: qué necesidad atiende, por qué merece desarrollarse, qué es, en qué situaciones aporta valor, qué lo respalda y qué tiene que demostrar. Es la descripción de referencia del proyecto.

Se diferencia del documento de visión (skill documento_vision) en tres cosas:

• Sin historia conductora. No hay caso, escenas ni prólogo. Es una descripción ordenada, como un dossier.
• Más formal. Cada afirmación del dominio lleva su referencia, y se separa siempre lo publicado, lo que es objetivo de diseño y lo que es supuesto de cálculo.
• Para el autor y para compartir. Sirve al autor (y a Claude en sesiones futuras) como descripción compacta y sin distracciones, y se puede entregar tal cual a colaboradores, socios o financiadores.

Los dos conviven. La visión cuenta el proyecto con una historia; el fundacional lo describe. Si uno cambia, se revisa el otro.

Esta skill dice qué lleva un fundacional y cómo se escribe. El generador, los recursos y su sintaxis, los temas, las herramientas y la comprobación son los comunes de crear_documentos, que se lee junto a esta.

Dónde va

Los documentos fundacionales de un proyecto van juntos en docs/specs/vision/ (metodología de la SF, «Estructura documental común»): la visión, el fundacional y las infografías técnicas en infografias/.

• Del proyecto: docs/specs/vision/fundacional-<proyecto>.md y su .html.
• De cada producto de una familia, si lo tiene: fundacional-<producto>.md.

El .md es la fuente. El .html se genera y no se edita a mano. Si se parte de un PDF o de un HTML existente, se convierte a .md y el original se conserva junto a él o en _respaldo/.

Modelo. Si el proyecto ya tiene un fundacional que aplica bien estas reglas, se lee como ejemplo al escribir o revisar otro; lo propio de su dominio no se copia.

Secciones

Hay un núcleo que todo documento fundacional tiene y secciones opcionales que se incluyen cuando el proyecto las necesita. Se numeran en el orden en que aparecen. Los anexos van al final, con etiqueta «Anexo A · …».

Orden: primero explicar, después justificar. El lector tiene que saber qué es el producto antes de valorar los argumentos. Tras la apertura (propósito, si lo hay, y la prosa de la razón para desarrollar con la idea, la diferencia y la tesis), van las secciones que explican: el sistema o la familia, el producto y su funcionamiento, los escenarios y las alternativas. Después, las que justifican: la necesidad documentada y el coste del problema, el impacto, el dimensionamiento, los riesgos y «Qué debe demostrar». Las tarjetas de la necesidad documentada pueden ir en su propia sección, tras el producto, si la apertura ya resume la tesis.

Portada sobria. Marca, nombre y lema en letra normal (una o dos líneas). Nada más, para que la cabecera sea baja: la idea con el propósito abre la primera sección como entradilla, la versión y el estado van al pie, y no hay fila de cifras (contar fichas o evidencias es inventario, no argumento; si una cifra argumenta, va en el texto).

Avisos de alcance global (qué del documento es objetivo de diseño y qué está validado, o cualquier criterio que se aplica a todo el texto): van al principio, fuera de toda sección. Se escriben como cita > entre el # Nombre y la primera ##; el generador los pone antes de las secciones, como recuadro.

Núcleo

1. Razón para desarrollar. Empieza con una prosa inicial, antes de las tarjetas y sin subtítulos:

   • la idea con el propósito, como entradilla;
   • la diferencia frente a las alternativas existentes, en un párrafo, con su referencia y una frase por alternativa;
   • la tesis de desarrollo: qué merece financiarse o construirse ahora y con qué condición tendrá valor. Va en prosa, no en un recuadro, y se justifica: en qué hechos del documento se apoya, con su cifra y su referencia, y qué falta por saber, que es lo que debe medir el piloto.

   Después, dos o tres tarjetas con la necesidad documentada (el problema medido, la capacidad de intervenir, la consecuencia), cada una con su referencia. Esta forma, prosa que argumenta y después tarjetas justificadas, es el modelo de todas las secciones (ver «Reglas de redacción»).

2. El producto. Qué es en pocas cifras (capacidad, autonomía, alcance…), cómo funciona por subsistemas, su arquitectura, sus funciones principales, cómo evoluciona (familia, plataforma, verificar / reconfigurar / rediseñar) y qué no hace.

3. Escenarios de uso. Las situaciones en que el producto puede aportar valor, con un código cada una (S1, S2…) para citarlas en el resto del documento. En cada una: cuándo aporta valor, límite del argumento, qué medir y la base documental. Los escenarios son compatibles entre sí; no se suman como poblaciones independientes.

4. Evidencias. Primero, el método y el alcance de la búsqueda. Después, una tarjeta por evidencia: tipo (medición, piloto, guía, estudio…), qué dice con su cifra, a qué escenarios afecta y una lectura para el proyecto que diga qué respalda y qué no.

5. Qué debe demostrar. El paso del documento al piloto: fases priorizadas, cada una con su circuito, su motivo y su condición para avanzar; las validaciones necesarias (técnica, operativa, económica); las decisiones de avance (puertas); la decisión propuesta y cómo se medirá.

6. Fuentes y referencias. Todas las fuentes con código por tipo (por ejemplo E evidencias, F fichas técnicas, P precios, D economía, C clínica, M documentos del propio proyecto), su procedencia, su enlace y la fecha de revisión.

Opcionales

• Propósito y valores (misión, visión y valores), al principio, como sección propia o como tarjetas dentro de la primera. Para proyectos que buscan alinear a un equipo o a colaboradores.
• Coste del problema, cuando hay una dimensión económica: casos documentados con su cifra y su «implicación y alcance», qué se puede evitar y el modelo económico (una fórmula). Va después de la razón para desarrollar.
• Dimensionamiento del mercado o del territorio: lo que las fuentes permiten afirmar y lo que no, qué datos harían falta (denominador, exposición, economía), un escenario transparente (puede llevar una calculadora como componente propio) y cómo convertirlo en una estimación defendible. Va antes de «Qué debe demostrar».
• Anexo de comparación con una referencia existente: una tarjeta por dimensión, con dos columnas («referencia · publicado» y «proyecto · diseño») y la aportación de cada enfoque. Al final, los valores que debe conservar la comparación y cómo comprobar el valor añadido.
• Anexo de fichas por elemento (medicamentos, materiales, componentes, clientes tipo…): una ficha por elemento con sus datos y sus escenarios. El generador añade un buscador y un filtro por escenario.
• Impacto: qué cambiaría si el producto funciona, siempre condicionado a lo que demuestre el piloto. Una tarjeta por dimensión (económica, para las personas, para el territorio o el entorno) con «Qué puede cambiar» y su indicador, medible antes y después. La prosa inicial nombra la línea de base que ya existe y lo que falta medir; ninguna cifra de ahorro se atribuye al proyecto sin ese contraste. Los ODS, si se citan, con su nombre oficial y su fuente. Va después del coste del problema o de la necesidad.
• Riesgos: qué puede fallar y cómo se mitiga. Una tarjeta por riesgo, con su clase como etiqueta (técnico, operativo, económico, regulatorio), «Mitigación» y «Se comprueba en», que remite a una fase o puerta de «Qué debe demostrar». La prosa inicial dice el riesgo principal y cómo el plan lo detecta pronto. Lo que aún no se ha analizado (por ejemplo, el encaje regulatorio) se declara como riesgo abierto, con sus fuentes cuando las haya. Va justo antes de «Qué debe demostrar».
• Invitación a colaborar: qué perfiles se buscan, qué se ofrece y qué se espera. Para documentos que se comparten.

Lectura por capas. Se comunica primero lo más importante, y cada capa siguiente profundiza: quien solo lee la primera se lleva lo esencial, y quien quiere más sigue leyendo. El orden es de importancia, no el de cómo se llegó a las conclusiones. Vale para todo el documento y para cada sección, que abre con su conclusión (ver «Reglas de redacción») y deja el detalle a las tarjetas, los #### plegados y los anexos.

Si el proyecto necesita una sección que no está aquí, se propone al autor antes de escribirla. Si es útil para otros proyectos, es una mejora de esta skill, que es de la SF: no se anota en el proyecto, se dice en una línea; en la propia SF es del proyecto.

Reglas de redacción

• Solo la última decisión. El documento describe el estado actual, sin historial.
• Tres clases de afirmación, siempre separadas: hechos publicados (con referencia), objetivos de diseño del proyecto (lo que se quiere que haga) y supuestos de cálculo (marcados como ilustrativos). Un recuadro de alcance al principio lo explica, y las etiquetas «publicado» y «diseño» lo recuerdan donde se comparan.
• Toda cifra o afirmación del dominio se contrasta con fuentes antes de escribirla, nunca de memoria, y lleva su referencia en la misma frase. Para buscar en la web, pedir permiso al autor si no lo ha dado.
• Cada evidencia dice también lo que no demuestra. «Lectura para el proyecto», «Límite del argumento», «Implicación y alcance»: el documento gana credibilidad cuando marca sus propios límites.
• Compacto. Párrafos de dos o tres frases, frases de unas 20 palabras o menos, siglas explicadas la primera vez. El núcleo se lee de un tirón; el detalle extenso va a los anexos.
• Sin paja. Nada sobre el propio documento («Hay que actualizar este documento…», «Este documento no contiene…») ni obviedades: cada frase aporta algo del proyecto.
• Cada sección abre con prosa que argumenta, como la primera: unos dos o tres párrafos, antes de cualquier tarjeta y sin subtítulos, con la conclusión de la sección, los hechos que la sostienen con su cifra y su referencia, y lo que falta por saber. Una frase de presentación («Seis experiencias permiten…») no basta. La tesis o la lectura de conjunto va en esa prosa, no en un recuadro. Las tarjetas vienen después y aportan el detalle que se consulta, sin repetir el argumento.
• Frases completas, no catálogo. Dentro de cada apartado (###) se escribe con frases con verbo que explican cómo funciona algo y por qué, no enumeraciones sin verbo («Identificación, inventario, trazabilidad…»). Los apartados se titulan por la pregunta que responden («Cómo mantiene el frío»), no con el patrón «Tema: subtema», y no se trocean en #### partes de un párrafo: el #### queda para el detalle que se pliega.
• Estructura visible, sin romper la lectura: cuándo van tarjetas, prosa, apartados, recuadros, tablas o listas, la negrita, los campos repetidos y la tipografía, en crear_documentos («Cuándo usar cada recurso»). En un fundacional, las tarjetas típicas son experiencias, escenarios, evidencias, fases, puertas, dimensiones de una comparación, fichas y las cifras clave del producto; en un balance, lo que ha funcionado se cuenta en prosa y las deficiencias van en una tabla con lo que pasa y su estado.
• Sin códigos que el lector aún no conoce. Los códigos internos (S1, S2…) solo se usan después de la sección que los define y donde ayudan a cruzar referencias. Antes, y en la prosa que argumenta, se dice con palabras («el transporte al domicilio y la conservación en casa»).
• Toda afirmación clave se justifica en el mismo sitio. Una tesis o una conclusión importante dice en qué se basa (los hechos del documento, con cifra y referencia) y qué no está demostrado todavía.
• Propuestas, no imposiciones. «Se propone», «a valorar», «decide quien corresponde».
• Respeta las sensibilidades del dominio. Las reglas del dominio del proyecto están en las reglas de su identidad (las mismas que lee documento_vision).

Cómo se trabaja

1. Leer antes de proponer: la visión del proyecto, su identidad y sus reglas, la especificación si existe, el código o el gemelo si aportan cifras, y el material que traiga el autor. Inventariar todos los argumentos del proyecto. Un documento fundacional de producto recoge todos los argumentos que el proyecto tiene, y más cuando se compara con otros productos: los de los demás documentos fundacionales, la visión, la especificación y lo ya construido (un gemelo digital, un prototipo, pruebas). Antes de escribir o revisar, se hace un inventario de lo que falta, con su fuente y su clase (hecho publicado, objetivo de diseño, supuesto o avance verificado solo en simulación), y de las contradicciones entre documentos, que se preguntan al autor antes de pasar ninguna cifra afectada. Lo construido se cuenta con sus límites declarados.
2. Proponer el índice y las herramientas: preguntar si el documento es un artefacto para el proyecto o para el usuario y qué herramientas lleva (buscador, notas, «Lectura», plegado, leyenda, edición…), con la recomendación para ese destino, en una sola pregunta con opciones; anotar la respuesta en la cabecera. Proponer el índice: el núcleo, las secciones opcionales que aplican y por qué, los escenarios candidatos con su código y las cifras de portada. Dejar que el autor lo afine antes de escribir.
3. Investigar las evidencias que falten (con permiso para buscar), con su fuente exacta.
4. Escribir el .md con los recursos de abajo y generar el .html. Antes de sustituir una versión, se respalda en _respaldo/ (crear_documentos, «Respaldar»).
5. Verificar (ver «Comprobación») y entregar con un resumen: qué contiene, qué es ilustrativo, qué evidencias faltan y qué conviene que valide un experto.
6. Afinar con el autor. Cada corrección general se añade a la skill como mejora.

Comprobación

Antes de entregar, verificar:

• Núcleo completo: razón para desarrollar, producto, escenarios, evidencias, qué debe demostrar y fuentes.
• No hay historia conductora (caso, escenas, prólogo) fuera de los escenarios.
• Toda afirmación del dominio lleva referencia (publicado, diseño, supuesto).
• Cada evidencia dice lo que respalda y lo que no.
• Las fuentes están completas (código, procedencia, enlace, fecha de revisión).
• Compacto: sin paja, sin obviedades, sin frases sobre el propio documento.
• Cada sección abre con prosa argumentativa (dos o tres párrafos), no con tarjetas.
• No hay códigos sin definir (S1, S2… solo tras su sección).
• Fichero .md generado sin errores de sintaxis.
• El .html se genera correctamente (si se ha generado).
• Versión anterior respaldada (si se ha sustituido).

Si se han hecho cambios en la skill (nuevas reglas, secciones, ejemplos), se git add en las skills de la SF con un mensaje claro.