CitaClara Constitution

Core Principles

I. Spec First (NO NEGOCIABLE)

Todo comportamiento observable de CitaClara nace de una spec aprobada en specs/. Todo cambio de comportamiento empieza corrigiendo o creando su spec antes de tocar implementación, tests o datos.

La propiedad de cada spec vive en specs/MAPA.md: una spec tiene un único propietario. Sin propietario registrado no hay spec aprobada, y sin spec aprobada no hay implementación. En caso de conflicto entre código y spec, la spec aprobada prevalece hasta que se enmiende por el procedimiento de Governance.

Motivación: CitaClara nace greenfield con SDD y operará desde el primer mes con varias features y varios agentes en paralelo. Solo una spec aprobada por feature evita colisiones y trabajo fantasma.

II. Exactitud numérica y temporal (NO NEGOCIABLE)

Los números no admiten creatividad: todos los importes cuadran al céntimo, siempre, en cualquier suma, desglose, descuento o total que vea la clínica. Toda fecha y hora se muestra sin ambigüedad posible para una clínica española (día, mes, año, hora y minutos claros, indicando franja cuando importe). Ninguna spec que maneje dinero o tiempo se considera completa sin sus reglas de redondeo, formato de visualización y ejemplos límite.

III. Cero solapes (NO NEGOCIABLE)

El solape es el fallo capital: un profesional no puede tener dos citas a la vez, jamás. Esta garantía se mantiene incluso si dos reservas del mismo hueco llegan en el mismo instante. Toda feature que escriba en la agenda MUST incluir pruebas que intenten provocar un solape, incluido el caso concurrente, y esas pruebas MUST estar en verde para fusionar. Cualquier solape detectado, en pruebas o en producción, se trata como defecto crítico y bloquea cualquier otra prioridad hasta su resolución en spec e implementación.

IV. Simplicidad y cero alcance fantasma

Ante dos soluciones que cumplan la spec, se elige la más simple. Nada se construye ni se añade — funcionalidad, dependencia, campo, pantalla o automatismo — sin estar justificado en una spec aprobada. Lo no especificado no se implementa. La complejidad adicional MUST justificarse por escrito en su spec o plan.

V. Demostrable con datos reproducibles

El producto mantiene datos de demostración deterministas: misma semilla, misma historia. Specs, ejemplos y analítica citan números que cualquiera puede reproducir ejecutando la misma semilla. Ninguna spec puede apoyarse en datos inventados ad hoc: si un ejemplo necesita una agenda, unos importes o unos pacientes, provienen del juego de demostración versionado o definen su semilla y su historia.

VI. Los tests acompañan a la spec (NO NEGOCIABLE)

Cada regla de negocio y cada criterio de aceptación relevante tiene su test que la referencia de forma trazable (del test a la regla de la spec). La suite en verde es condición de merge: ningún cambio de comportamiento se fusiona con tests en rojo, sin tests para las reglas nuevas o sin referencia explícita a la spec que cubren.

VII. Interfaz clara y moderna

Recepción usa CitaClara sin formación y sin manual. Esto exige: nada de jerga técnica en pantalla, lenguaje de clínica pequeña (fisioterapia, nutrición, podología); contraste y tamaños de letra accesibles; y funcionamiento tanto en el portátil de recepción como en el móvil de un paciente. Este principio es calidad exigible en specs y criterios de aceptación, no una decisión de stack: la tecnología de la interfaz se decide en el plan.

VIII. Español de España en todo

Todo lo visible — interfaz, mensajes, errores, avisos, correos, documentos, specs y ejemplos — está en español de España. Se usan formulaciones, tratamientos y formatos propios de una clínica española. Cualquier texto en otro idioma o variante es un defecto.

Contexto y límites

CitaClara es un gestor de citas greenfield para clínicas y consultas pequeñas (fisioterapia, nutrición, podología). Nace con SDD y aspira a operar con varias features y varios agentes en paralelo desde el primer mes.

Esta constitución fija principios de negocio y calidad. No decide ni una decisión técnica: el stack, los formatos de intercambio, los esquemas de datos y las estructuras internas se deciden en el plan de cada feature. Ninguna spec puede invocar esta constitución para imponer una tecnología; cualquier mención técnica en una spec MUST justificarse como requisito de negocio o moverse al plan.

Flujo de trabajo y puertas de calidad

El flujo normativo es constitución → spec aprobada en specs/ con propietario en specs/MAPA.md → plan → tareas → implementación. No se salta ningún paso para cambios de comportamiento observable.

Puertas obligatorias antes de fusionar: spec aprobada y actualizada; trazabilidad spec ↔ tests; suite completa en verde, incluidas las pruebas antisolape cuando la feature escriba en la agenda; textos en español de España; y revisión de simplicidad (sin alcance fantasma). El trabajo paralelo entre agentes se coordina por propiedad de spec: un agente, una spec; quien necesite tocar spec ajena lo acuerda con su propietario y actualiza specs/MAPA.md si la propiedad cambia.

Governance

Esta constitución prevalece sobre cualquier otra práctica, plantilla o decisión no gobernada. En caso de conflicto, la constitución manda hasta que se enmiende formalmente.

Las enmiendas requieren propuesta escrita con motivación, impacto en specs vigentes y plan de migración; solo se adoptan al actualizar este fichero con nueva versión y fecha. El versionado sigue semver: MAJOR por eliminaciones o redefiniciones incompatibles de principios; MINOR por principios o secciones nuevos o ampliaciones materiales; PATCH por aclaraciones, redacción o correcciones sin cambio semántico.

Toda revisión de spec, plan y fusión MUST verificar el cumplimiento de esta constitución y dejar constancia de cualquier excepción aceptada con su justificación y su vigencia.

Version: 1.0.0 | Ratified: 2026-09-29 | Last Amended: 2026-09-29