diff --git a/Propuesta/devtrail-design-principles.md b/Propuesta/devtrail-design-principles.md index 9dd9f59..71b686d 100644 --- a/Propuesta/devtrail-design-principles.md +++ b/Propuesta/devtrail-design-principles.md @@ -1,7 +1,7 @@ # DevTrail — Principios de diseño -**Versión:** 0.2.1 (anotaciones empíricas tras el experimento `/plan-audit` en Sentinel; rename Plan → Charter en vocabulario going-forward) -**Fecha:** 30 de abril de 2026 +**Versión:** 0.2.2 (anotaciones empíricas + pase editorial para legibilidad pública: las referencias internas a artefactos de Sentinel se generalizan; rename Plan → Charter en vocabulario going-forward) +**Fecha:** 2 de mayo de 2026 **Autor:** Jose Villaseñor Montfort — StrangeDaysTech **Propósito:** Articular la filosofía del producto en forma compacta, para servir como referencia frente a decisiones de diseño y como criterio para decir no a features que no encajan. **Documentos relacionados:** `devtrail-thesis-validation.md` (cuerpo de evidencia que motivó las anotaciones de v0.2). @@ -16,7 +16,7 @@ Este documento existe para que DevTrail tenga un ancla explícita. Las decisione Los principios están ordenados por jerarquía: cuando dos entran en conflicto, gana el que viene antes. -**Versión 0.2 — anotaciones empíricas.** Esta versión incorpora aprendizajes del primer experimento que estresa los principios contra evidencia: Sentinel `/plan-audit` durante 6 ciclos (PLAN-01..06), tres iteraciones de formato (v1 → v2 → v3) y dos auditorías externas duales por ciclo. Las anotaciones por principio referencian ese cuerpo de evidencia y se concentran en los principios que el experimento ejercitó directamente (#6, #9, #12). La jerarquía y la redacción de los doce principios no cambian. +**Versión 0.2 — anotaciones empíricas.** Esta versión incorpora aprendizajes del primer experimento que estresa los principios contra evidencia: seis ciclos de ejecución sobre un proyecto adoptante real (Sentinel — un sistema Go backend), con tres iteraciones del formato del Charter (v1 → v2 → v3) y dos auditorías externas duales por ciclo. Las anotaciones por principio se concentran en los tres que el experimento ejercitó directamente (#6, #9, #12); la jerarquía y la redacción de los doce principios no cambian. La evidencia detallada vive en `devtrail-thesis-validation.md`. --- @@ -56,7 +56,7 @@ DevTrail no compite con herramientas que prometen *"haz código 10x más rápido Esto significa que features que añaden fricción justificada (validaciones, gates, requerimientos de documentación, pre-trabajo antes de planning) son aceptables y a veces deseables. Features que prometen quitar fricción a costa de la calidad del razonamiento del agente son sospechosas por defecto. -**Anotación v0.2 — distinción virtud vs ceremonia.** Sentinel reveló que no toda fricción del flujo DevTrail tiene el mismo carácter. La fricción es *virtuosa* cuando externaliza signal pública: nombrar `R (nuevo, no en Plan)` permite que auditores externos heterogéneos lo capturen (`AILOG-020` §Additional Notes); `check-plan-drift.sh` ejecutado al cierre detecta drifts archivos-declarados-vs-modificados con cero falsos positivos en 2/2 tests empíricos (`AILOG-022` §Summary); la auditoría dual Copilot+Gemini calibra cross-modelo y captura gaps que un solo auditor pierde (`PLAN-05.telemetry.yaml`). La fricción es *ceremonia atacable* cuando solo genera triage manual o prescribe sin reflexividad: el TEMPLATE prescribiendo una firma arquitectónica que choca con la convención del módulo destino (F2 en PLAN-05) o el drift script alertando sobre R ya documentados en AILOG (`AILOG-022` R2). La primera se mantiene; la segunda es bug del formato, no virtud del principio. Ver `devtrail-thesis-validation.md` §5 para el desarrollo y los criterios accionables. +**Anotación v0.2 — distinción virtud vs ceremonia.** La evidencia empírica reveló que no toda fricción del flujo tiene el mismo carácter. La fricción es *virtuosa* cuando externaliza señal pública verificable por terceros: nombrar formalmente los riesgos emergentes durante ejecución hace que auditores externos heterogéneos los capturen; un drift-check ejecutado al cierre del trabajo detecta archivos declarados-vs-modificados con cero falsos positivos en validación empírica; la auditoría dual con dos modelos heterogéneos calibra cross-modelo y captura gaps que un solo auditor pierde. La fricción es *ceremonia atacable* cuando solo genera triage manual o prescribe sin permitir adaptación al contexto: una plantilla rígida que choca con la convención del módulo destino, o un drift-check alertando sobre divergencias ya documentadas en otra parte, son los dos casos observados. La primera se mantiene; la segunda es bug del formato, no virtud del principio. La evidencia detallada y los criterios accionables viven en `devtrail-thesis-validation.md` §5. ## 7. Local-first, Cloud como amplificador @@ -76,7 +76,7 @@ Cuando dos diseños cumplen el mismo objetivo, gana el más simple. Cuando una f Esto se aplica tanto al producto como al lenguaje del producto. Los nombres de comandos, tipos de documento y conceptos del framework se eligen para ser inmediatamente comprensibles, no para sonar técnicamente sofisticados. Si un concepto requiere explicación larga para un usuario nuevo, probablemente está mal diseñado. -**Anotación v0.2 — bash antes que framework cuando bash basta.** Sentinel demostró que `scripts/check-plan-drift.sh` (~145 líneas bash con awk + grep + git) cubre el caso "drift de archivos declarados vs modificados" con cero falsos positivos sobre dos tests empíricos. La decisión consciente de no implementarlo en Go inicialmente está documentada en `AILOG-022` §Decision: "Bash es zero-build, sin dependencies, inspeccionable in situ; el costo de mantenimiento es bajo". Cuando se porte al CLI Rust en fase 2 del roadmap (`devtrail-cli-roadmap.md`), preservar la simplicidad bash en lo posible — invocar el shell desde Rust o reimplementar con cuidado de no inflar la lógica. La complejidad solo se cristaliza cuando el patrón de uso lo demande, no por defecto. +**Anotación v0.2 — bash antes que framework cuando bash basta.** La evidencia empírica demostró que un script bash de ~145 líneas (awk + grep + git) cubre el caso "drift de archivos declarados vs modificados" con cero falsos positivos sobre dos tests. La decisión consciente de no implementarlo inicialmente en el lenguaje del CLI (Rust) se justifica así: bash es zero-build, sin dependencies adicionales, inspeccionable in situ; el costo de mantenimiento es bajo. Cuando se porte al CLI en la fase 2 del roadmap (`devtrail-cli-roadmap.md`), preservar la simplicidad bash en lo posible — invocar el shell desde Rust o reimplementar con cuidado de no inflar la lógica. La complejidad solo se cristaliza cuando el patrón de uso lo demande, no por defecto. ## 10. Honestidad sobre lo que la herramienta no hace @@ -96,11 +96,11 @@ DevTrail no debe avanzar más rápido de lo que aprendemos sobre cómo se usa re Esto se traduce en una preferencia explícita por: prototipos antes que features, observación antes que cristalización, schemas estables sobre features cambiantes, y evolución incremental sobre rewrites grandes. -**Anotación v0.2 — el espíritu del N≥3 frente a Sentinel.** Sentinel es un solo proyecto, un solo dominio (Go backend), un solo autor. Aplicado literalmente, el principio bloquearía cualquier cristalización a partir de su evidencia. Aplicado al espíritu — observación rigurosa antes que cristalización, evolución incremental con datos reales — Sentinel cubre tres ejes de diversidad estructural: (a) escala variable (XS, S, M en cinco ciclos), (b) iteración del formato bajo presión empírica (v1 → v2 → v3, cada una derivada del ciclo anterior), (c) calibración cross-modelo de auditores (Copilot + Gemini convergiendo a 9.25/9.5 en PLAN-05). Estos seis ciclos × tres formatos × tres escalas son evidencia equivalente al N≥3 que el principio busca proteger. +**Anotación v0.2 — el espíritu del N≥3 frente a evidencia inicial limitada.** La evidencia empírica disponible al momento de escribir esta versión proviene de un solo proyecto adoptante, en un solo dominio (Go backend), con un solo autor. Aplicado literalmente, el principio bloquearía cualquier cristalización a partir de esa evidencia. Aplicado al espíritu — observación rigurosa antes que cristalización, evolución incremental con datos reales — la evidencia disponible cubre tres ejes de diversidad estructural: (a) escala variable de las unidades de trabajo (XS, S, M en cinco ciclos), (b) iteración del formato bajo presión empírica (v1 → v2 → v3, cada una derivada del ciclo anterior), (c) calibración cross-modelo de auditores (dos modelos heterogéneos convergiendo a scores similares en el ciclo más estresado). Estos seis ciclos × tres formatos × tres escalas son evidencia equivalente al N≥3 que el principio busca proteger. -Lo que sigue sin diversificar es el dominio. Para preservar el principio en su forma operacional: cualquier schema que se cristalice a partir de Sentinel se publica como `v0.json` con marca *experimental*. La transición a `v1.0` estable requiere validación con un segundo proyecto en otro dominio (frontend, ML pipeline, infra-as-code). Cualquier feature que dependa de un supuesto sin evidencia (como el #4 "aprobaciones rara vez binarias", que Sentinel no ejercitó) queda explícitamente bloqueada hasta tener un proyecto multi-actor. Ver `devtrail-thesis-validation.md` §6 y §8 para el desarrollo del argumento y la lista de gaps específicos por supuesto. +Lo que sigue sin diversificar es el dominio. Para preservar el principio en su forma operacional: cualquier schema que se cristalice a partir de esa evidencia se publica como `v0.json` con marca *experimental*. La transición a `v1.0` estable requiere validación con un segundo proyecto en otro dominio (frontend, ML pipeline, infra-as-code). Cualquier feature que dependa de un supuesto sin evidencia — como el supuesto de aprobaciones condicionales, que requiere flujo multi-actor y la evidencia disponible no lo ejercitó — queda explícitamente bloqueada hasta tener un proyecto que sí lo ejerza. Ver `devtrail-thesis-validation.md` §6 y §8 para el desarrollo del argumento y la lista de gaps específicos por supuesto. -**Patrón meta-meta detectado en Sentinel — auto-evolución del formato.** El experimento reveló que el formato se mejora a sí mismo: cada Plan ejecutado en Sentinel (y, going-forward en DevTrail, cada Charter ejecutado) genera datos que refinan el formato del próximo (`AILOG-022` §Additional Notes). Esto sugiere ampliar el principio en futuras versiones: la herramienta evoluciona consigo misma; cada uso es input para la próxima versión. Por ahora se documenta como observación, no como principio adicional, hasta que un segundo proyecto confirme el patrón. +**Patrón meta-meta detectado — auto-evolución del formato.** La evidencia empírica reveló que el formato se mejora a sí mismo: cada Charter (Plan en terminología histórica) ejecutado genera datos que refinan el formato del próximo. Esto sugiere ampliar el principio en futuras versiones: la herramienta evoluciona consigo misma; cada uso es input para la próxima versión. Por ahora se documenta como observación, no como principio adicional, hasta que un segundo proyecto confirme el patrón. ---