create-quiver 0.17.1 → 0.17.2

package/auditoria-ux-ui-performance-documentacion.md

@@ -0,0 +1,705 @@
+# Auditoría del Proyecto Quiver
+
+> Fecha de auditoría: 2026-06-01  
+> Versión analizada: 0.15.4  
+> Tipo de producto: CLI framework (Node.js)  
+> Alcance: estructura de repositorio, comandos, documentación, tests, scripts, dependencias
+
+---
+
+## 1. Resumen Ejecutivo
+
+Quiver es un framework CLI técnicamente sólido, con una propuesta de valor clara (ordenar el trabajo asistido por IA con WDD + SDD), una arquitectura modular bien pensada, tests extensos (38 archivos en `tests/commands/`, más cobertura en `tests/lib/`), y una documentación considerablemente más madura que la mayoría de proyectos OSS equivalentes.
+
+El producto está activamente desarrollado: pasó de v0.10 a v0.15 en menos de dos semanas de mayo de 2026, con dogfooding real y hardening iterativo. Esto es un punto muy favorable.
+
+**Principales fortalezas:**
+- Huella de dependencias mínima (solo `@clack/prompts` y `zod`)
+- Documentación multi-idioma (EN/ES) y multi-plataforma (macOS, Linux, Windows)
+- Arquitectura modular con separación clara entre comandos y servicios
+- Smoke tests y CI scripts bien estructurados
+- Flujo de workflow WDD + SDD completo y bien articulado
+
+**Principales hallazgos de la auditoría:**
+
+1. **UX/DX del CLI:** Problemas de experiencia detectables en feedback visual, mensajes de error (mezcla de i18n e inglés hardcodeado), y complejidad del namespace que aumenta la curva de aprendizaje.
+2. **Documentación:** El `CONTRIBUTING.md` es críticamente escaso. El `ROADMAP.md` mezcla información interna con pública. Errores de encoding en `CLI_UX_GUIDE.md`. Falta `ARCHITECTURE.md`.
+3. **Performance:** Arquitectura síncrona en toda la capa de I/O. El archivo `commands/ai.js` de 3438 líneas no impacta runtime pero sí el tiempo de carga del módulo.
+4. **Automatización:** Sin CI/CD declarativo (GitHub Actions/similar). El changelog y la referencia de comandos son manuales.
+5. **Modernización:** Parser manual de 1100+ líneas en lugar de Commander.js/yargs. Sin TypeScript. Sin shell completion scripts.
+
+---
+
+## 2. Problemas Detectados de UX/UI
+
+> Nota: Quiver es un CLI, por lo que "UX/UI" se refiere a experiencia en terminal, legibilidad de output, mensajes, flujos y documentación de usuario.
+
+---
+
+### 2.1 Mensajes de error no localizados en múltiples comandos
+
+**Problema detectado:**
+Varios comandos tienen una función `formatError()` local que emite strings hardcodeados en inglés, ignorando el sistema i18n del proyecto. Afecta a: `commands/config.js`, `commands/evidence.js`, `commands/spec.js`, `commands/graph.js`, `commands/prepare.js` (en `buildNextSteps()`), y `commands/ai.js`.
+
+**Archivo relacionado:** `src/create-quiver/commands/config.js`, `evidence.js`, `spec.js`, `graph.js`, `prepare.js`, `ai.js`
+
+**Impacto:** Un usuario que configura `--lang es` recibe mensajes de error en inglés. Rompe la promesa de soporte completo EN/ES anunciada en el README y la `CLI_UX_GUIDE.md`.
+
+**Recomendación:** Auditar todos los `formatError()` locales y reemplazarlos con `createTranslator(options.language).t(key)` usando keys del catálogo i18n. Agregar un test de contrato que verifique que ningún mensaje de error de nivel de usuario quede fuera del sistema i18n.
+
+**Prioridad:** Alta
+
+---
+
+### 2.2 Namespace plano con 8 comandos de dominio slice/handoff en el root
+
+**Problema detectado:**
+Los comandos `start-slice`, `check-slice`, `check-pr`, `check-scope`, `cleanup-slice`, `refresh-active-slices`, `check-handoff` y `new-handoff` viven en el namespace root junto a comandos de nivel completamente distinto como `init`, `analyze` o `version`. Ejecutar `quiver --help` muestra 23+ entradas sin jerarquía clara.
+
+**Archivo relacionado:** `src/create-quiver/index.js` (SUPPORTED_COMMAND_MODES)
+
+**Impacto:** Alta carga cognitiva para usuarios nuevos. Percepción del CLI como colección de scripts ad-hoc en lugar de framework estructurado. El TAB completion (cuando esté disponible) será difícil de usar.
+
+**Recomendación:** Introducir namespaces `slice` y `handoff` (ya están definidos como canónicos en `docs/CLI_UX_GUIDE.md` sección "Namespaces y aliases") con aliases de compatibilidad deprecated para los comandos legacy. El `CLI_UX_GUIDE.md` ya documenta este contrato — falta completar la implementación.
+
+**Prioridad:** Alta
+
+---
+
+### 2.3 Ausencia de feedback visual de progreso en `init` y `analyze`
+
+**Problema detectado:**
+Los comandos `init` (que escribe múltiples archivos y puede llamar a npm install) y `analyze` (que escanea todo el proyecto) no muestran progreso durante la ejecución. El usuario ve un cursor parpadeando sin saber si el proceso está funcionando.
+
+**Archivo relacionado:** `src/create-quiver/index.js` (runAnalyze, lógica de init)
+
+**Impacto:** Percepción de que el CLI no responde. Peor en proyectos grandes o conexiones lentas donde npm install puede tardar varios segundos.
+
+**Recomendación:** Agregar spinner de `@clack/prompts` (ya está como dependencia) durante las fases lentas. Al finalizar, mostrar un resumen: "Creados N archivos. Próximo paso: `quiver flow`."
+
+**Prioridad:** Alta
+
+---
+
+### 2.4 `--auto-start` en `next` mezcla consulta con acción sin advertencia clara
+
+**Problema detectado:**
+El flag `--auto-start` convierte un comando de solo lectura (`next`) en un comando que ejecuta `start-slice`. La confirmación usa un `[y/N]` de readline propio que no pasa por el sistema i18n ni por `lib/cli/selectors.js`.
+
+**Archivo relacionado:** `src/create-quiver/commands/next.js` (líneas 85-104)
+
+**Impacto:** Sorpresa para el usuario que no espera que un comando de consulta ejecute acciones. La confirmación en inglés fijo rompe la experiencia en modo `--lang es`.
+
+**Recomendación:** Mover `promptConfirm` para que use `promptText` de `lib/cli/selectors.js`. Documentar claramente en el help que `--auto-start` ejecuta `slice start` tras confirmación.
+
+**Prioridad:** Media
+
+---
+
+### 2.5 `--section` en `dashboard` sin validación ni lista de valores válidos en el help
+
+**Problema detectado:**
+El flag `--section <name>` acepta cualquier string. Si se pasa un valor inválido, el comportamiento no está documentado. El help genérico dice "Show one human dashboard section" sin listar las secciones disponibles. La referencia de comandos sí las lista (`specs`, `slices`, `blockers`, `warnings`, `agents`, `approvals`, `runs`, `active-slice`, `next-steps`) pero esa información no está en el help inline.
+
+**Archivo relacionado:** `src/create-quiver/commands/dashboard.js`
+
+**Impacto:** Experiencia confusa cuando el usuario prueba un nombre de sección incorrecto.
+
+**Recomendación:** Agregar validación de `--section` con mensaje accionable: "Sección desconocida 'X'. Secciones disponibles: specs, slices, blockers, warnings, agents, approvals, runs, active-slice, next-steps."
+
+**Prioridad:** Media
+
+---
+
+### 2.6 `plan` no avisa cuando faltan `estimated_hours` en los slices
+
+**Problema detectado:**
+La ruta crítica se calcula a partir de `estimated_hours` en `slice.json`. Si ese campo falta o es 0, la ruta crítica aparece como `-` sin ninguna explicación de por qué.
+
+**Archivo relacionado:** `src/create-quiver/commands/plan.js` (línea 8, `toHourCount`)
+
+**Impacto:** El usuario no sabe que puede mejorar la utilidad del comando completando el campo `estimated_hours`.
+
+**Recomendación:** Si ningún slice tiene `estimated_hours > 0`, agregar al output: "Nota: agregá `estimated_hours` a tus archivos `slice.json` para activar el cálculo de ruta crítica."
+
+**Prioridad:** Baja
+
+---
+
+### 2.7 `graph --level <n>` devuelve output vacío sin mensaje explicativo
+
+**Problema detectado:**
+Si `--level` filtra a un nivel sin slices (por ejemplo, el nivel solicitado excede la profundidad del grafo), el output es vacío sin ningún mensaje.
+
+**Archivo relacionado:** `src/create-quiver/commands/graph.js`
+
+**Impacto:** El usuario no sabe si el comando funcionó o si hay un problema.
+
+**Recomendación:** Si el nivel filtrado no contiene slices, mostrar: "No hay slices en el nivel N. Ejecutá `graph` sin `--level` para ver todos los niveles."
+
+**Prioridad:** Baja
+
+---
+
+### 2.8 Relación entre `--json` y `--format` en `graph` no está documentada
+
+**Problema detectado:**
+`--json` emite la estructura de datos del grafo. `--format tree|mermaid|dot` cambia el renderizado human-readable. Si se combinan `--json --format mermaid`, el resultado no está documentado y podría confundir.
+
+**Archivo relacionado:** `src/create-quiver/commands/graph.js`
+
+**Impacto:** Comportamiento impredecible para usuarios avanzados.
+
+**Recomendación:** Documentar explícitamente en el help: "`--json` emite datos estructurados independientemente de `--format`. Los dos flags son ortogonales."
+
+**Prioridad:** Baja
+
+---
+
+### 2.9 `migrate` puede modificar archivos sin confirmación previa
+
+**Problema detectado:**
+`migrate` sin `--dry-run` aplica cambios a archivos existentes sin mostrar una advertencia previa. No exige revisión antes de ejecutar operaciones potencialmente destructivas.
+
+**Archivo relacionado:** `src/create-quiver/index.js` (runMigrate / updateStateForMigrate)
+
+**Impacto:** Riesgo de pérdida de datos o modificaciones inesperadas en proyectos con estructura legacy.
+
+**Recomendación:** Mostrar advertencia antes de ejecutar: "Esto modificará archivos existentes. Ejecutá con `--dry-run` primero para previsualizar." Idealmente, requerir confirmación explícita en TTY o `--yes` en modo no interactivo.
+
+**Prioridad:** Alta
+
+---
+
+### 2.10 `demo create spec-viewer` tiene tres niveles de profundidad para un único caso
+
+**Problema detectado:**
+La estructura `demo create spec-viewer` tiene tres niveles de anidamiento para un único caso de uso con un único valor posible (`spec-viewer`).
+
+**Archivo relacionado:** `src/create-quiver/commands/demo.js`
+
+**Impacto:** Fricción innecesaria. El usuario debe recordar exactamente los tres niveles del comando.
+
+**Recomendación:** Simplificar a `demo spec-viewer [--dry-run]`. El nivel `create` puede mantenerse como alias de compatibilidad. La `README_FOR_AI.md` ya documenta `demo spec-viewer` como la forma canónica.
+
+**Prioridad:** Baja
+
+---
+
+## 3. Oportunidades de Mejora UX/UI
+
+### 3.1 Agregar un comando `status` de nivel superior
+
+La `docs/reference/commands.md` ya documenta `status` y `README_FOR_AI.md` lo menciona como canónico. Si el comando ya existe, hay que asegurarse de que esté en `SUPPORTED_COMMAND_MODES` y en el `--help`. Si no está completamente implementado, completarlo. Un `quiver status` que muestra el estado más relevante en contexto (slice activo si hay uno, o el próximo paso del flow si no) sería el análogo CLI de `git status`: el comando que cualquier usuario ejecuta cuando no sabe qué hacer.
+
+### 3.2 Resumen post-ejecución en `init`
+
+Al finalizar `init`, mostrar un resumen accionable: "Archivos creados: N. Próximo paso recomendado: `quiver flow`." Esto reduce la desorientación de usuarios nuevos que no saben qué hacer después de inicializar.
+
+### 3.3 Agregar campo `next_command` al output JSON de `flow`
+
+El comando `flow` es el punto de entrada de orientación para automatizaciones y agentes. Agregar un campo `next_command` con el comando exacto a ejecutar (string) permite que un script o agente lo ejecute directamente sin parsear texto humano.
+
+### 3.4 Expandir `evidence` con `list` y `show`
+
+`evidence run` genera archivos de evidencia pero no hay forma de listarlos o visualizarlos desde el CLI. Agregar `evidence list` (lista los archivos generados en `.quiver/evidence/`) y `evidence show <path>` (muestra el contenido de un archivo de evidencia) cierra el loop del flujo de validación. La `README_FOR_AI.md` ya los documenta como comandos canónicos.
+
+### 3.5 Detectar rama principal automáticamente en `spec close`
+
+En lugar de defaultear a `main` para `--base <branch>`, detectar la rama principal del remote via `git remote show origin`. Muchos proyectos usan `master`, `develop` u otras ramas base.
+
+### 3.6 Indicador de ruta crítica en la tabla de `plan`
+
+Agregar una columna o marcador visual (por ejemplo `*`) en la tabla de `plan` para identificar qué slices están en la ruta crítica. Actualmente la ruta crítica solo aparece como una línea de texto al inicio, desconectada de la tabla.
+
+### 3.7 Autocompletado de shell (bash/zsh/fish)
+
+Generar scripts de completion para bash, zsh y fish mejoraría significativamente la ergonomía del CLI para usuarios avanzados. Commander.js y yargs los generan automáticamente. En el parser manual actual, se podría agregar un comando `completion` que emite el script de shell correspondiente.
+
+### 3.8 Consistencia de verbos en mensajes de confirmación
+
+Los mensajes de confirmación que usan readline manual (`[y/N]`) deberían pasar por `lib/cli/selectors.js` para garantizar consistencia visual, localización y que respeten `--no-color`.
+
+---
+
+## 4. Oportunidades de Modernización
+
+### 4.1 Migración a Commander.js o yargs
+
+**Estado actual:** Parser manual de 1100+ líneas en `src/create-quiver/index.js`.
+
+**Por qué modernizar:**
+- Definición declarativa de comandos y flags (en lugar de condicionales manuales)
+- Help automático y contextual por subcomando
+- Autocompletado de shell generado automáticamente
+- Validación de tipos de argumentos built-in
+- Menor superficie de bugs de parsing
+
+**Costo estimado:** Alto (migración completa). Puede hacerse iterativamente: Commander en comandos nuevos, aliases para los existentes.
+
+---
+
+### 4.2 TypeScript para el código fuente
+
+**Estado actual:** JavaScript puro sin tipos.
+
+**Por qué modernizar:**
+- Mejora la experiencia de desarrollo en IDEs
+- Detecta errores de tipos en tiempo de compilación (especialmente importante en un proyecto con muchos módulos interconectados)
+- Facilita contribuciones externas (autocompletado e inferencia)
+
+**Costo estimado:** Alto. Puede comenzarse con los módulos `lib/` más críticos y expandirse incrementalmente.
+
+---
+
+### 4.3 JSON Schema publicado para `slice.json`
+
+**Estado actual:** `slice.json` tiene una estructura bien definida internamente pero no hay un schema JSON publicado.
+
+**Por qué modernizar:**
+- Validación en IDEs con Language Server Protocol (VSCode, JetBrains)
+- Reducción de errores de edición manual
+- Documentación implícita de la estructura
+
+**Costo:** Bajo. Generar el schema a partir de los objetos Zod existentes en el código.
+
+---
+
+### 4.4 GitHub Actions para CI declarativo
+
+**Estado actual:** Los tests y smokes se ejecutan mediante scripts bash en `scripts/ci/`. No hay configuración de CI declarativa visible en el repositorio (no se encontró `.github/workflows/`).
+
+**Por qué modernizar:**
+- CI automático en cada PR sin depender de que el mantenedor lo ejecute manualmente
+- Matrix de SO (macOS, Linux, Windows) automatizada
+- Integración con status checks de GitHub
+- Reducción de errores de regresión por cambios no testeados
+
+**Costo:** Medio. Traducir los scripts existentes de `scripts/ci/` a un workflow de GitHub Actions.
+
+---
+
+### 4.5 Scripts `package.json` mixtos (bash y Node)
+
+**Estado actual:** Los scripts de `package.json` mezclan invocaciones bash (`bash tools/scripts/check-slice-readiness.sh`) con comandos Node (`node bin/create-quiver.js plan`). Los scripts bash no funcionan nativamente en Windows PowerShell.
+
+**Por qué modernizar:** Usar el CLI Node para todos los scripts del `package.json` mejora la portabilidad cross-platform, que es uno de los objetivos declarados del proyecto.
+
+**Costo:** Bajo. Reemplazar scripts bash con sus equivalentes `npx create-quiver <command>`.
+
+---
+
+### 4.6 Fragmentación de `commands/ai.js`
+
+**Estado actual:** Archivo de 3438 líneas con 23 subcomandos.
+
+**Por qué modernizar:** Impacta directamente el tiempo de require y la mantenibilidad. Fragmentar en módulos por dominio (`lifecycle.js`, `planner.js`, `agents.js`, `execution.js`, `inspection.js`) mantiene el mismo comportamiento externo con mejor estructura interna.
+
+**Costo:** Medio. Refactor sin cambios de API.
+
+---
+
+## 5. Oportunidades de Automatización
+
+### 5.1 Generación automática de `docs/reference/commands.md`
+
+**Estado actual:** La referencia de comandos se mantiene manualmente y puede quedar desactualizada respecto a la implementación real.
+
+**Propuesta:** Crear un script que genere `docs/reference/commands.md` a partir del output de `quiver --help` (o de una fuente declarativa en el código). Ejecutar como parte del proceso de release.
+
+**Valor:** Garantiza que la documentación siempre refleje la implementación real.
+
+---
+
+### 5.2 Generación automática del `CHANGELOG.md`
+
+**Estado actual:** El changelog se mantiene manualmente. La sección `[Unreleased]` acumula cambios sin formatear.
+
+**Propuesta:** Adoptar [Conventional Commits](https://www.conventionalcommits.org/) y usar `standard-version` o `release-please` para generar automáticamente el changelog desde los mensajes de commit.
+
+**Valor:** Reduce el esfuerzo manual de releases y garantiza consistencia en el formato.
+
+---
+
+### 5.3 CI automático en PRs con GitHub Actions
+
+**Estado actual:** Los smoke tests y la suite de tests se ejecutan manualmente.
+
+**Propuesta:** Workflow de GitHub Actions que ejecute automáticamente `node --test tests/**/*.test.js`, `npm run smoke:create-quiver`, `npm run smoke:doctor-fixtures` y `npm run smoke:guided-workflow` en cada PR, con matriz de SO (ubuntu, macos, windows).
+
+**Valor:** Detecta regresiones antes de merge sin intervención manual.
+
+---
+
+### 5.4 Lint de documentación (links rotos, acentos faltantes)
+
+**Estado actual:** El `CLI_UX_GUIDE.md` tiene palabras sin acentos ("estandar", "Ningun", "solo", "canonico"). No hay validación automática de links en la documentación.
+
+**Propuesta:** Agregar `markdownlint` y `markdown-link-check` como devDependencies. Ejecutar en CI en cada PR.
+
+**Valor:** Previene regresiones de calidad en documentación.
+
+---
+
+### 5.5 Publicación automática a npm en releases
+
+**Estado actual:** El proceso de release usa `scripts/release-quiver.sh`. No está claro si el publish a npm es manual o automatizado.
+
+**Propuesta:** Agregar un workflow de GitHub Actions que publique automáticamente a npm cuando se crea un tag `v*.*.*` en el repositorio.
+
+**Valor:** Elimina pasos manuales propensos a errores en el proceso de release.
+
+---
+
+### 5.6 Verificación de versión mínima de Node.js
+
+**Estado actual:** El `package.json` no declara `engines` con la versión mínima de Node.js requerida.
+
+**Propuesta:** Agregar `"engines": { "node": ">=18.0.0" }` (o la versión mínima que efectivamente se soporta) y validarlo en CI.
+
+**Valor:** Evita reportes de bugs por incompatibilidades de runtime.
+
+---
+
+### 5.7 Smoke test de instalación desde npm pack
+
+**Estado actual:** `npm run smoke:tiered-pack` existe pero no está claro si se ejecuta en CI automáticamente.
+
+**Propuesta:** Incluir el smoke de `npm pack --dry-run` y validación del tarball en el workflow de CI para cada release candidate.
+
+**Valor:** Garantiza que el paquete publicado en npm es válido antes de publicarlo.
+
+---
+
+## 6. Problemas de Performance
+
+### 6.1 I/O síncrono en toda la capa de lectura de archivos
+
+**Problema detectado:** Todos los módulos usan `fs.readFileSync`, `fs.readdirSync` y similares. En proyectos con muchos specs y slices, esto puede acumular latencia sincrónica.
+
+**Posible causa:** Decisión de simplicidad en un CLI que no necesita concurrencia. Sin embargo, comandos como `analyze` o `doctor` hacen múltiples lecturas secuenciales.
+
+**Impacto:** En proyectos pequeños, imperceptible. En monorepos con decenas de specs y cientos de slices, el tiempo de respuesta puede crecer linealmente.
+
+**Recomendación:** Para los comandos de lectura masiva (`analyze`, `plan`, `graph`), evaluar el uso de `fs.promises` con `Promise.all()` para lecturas paralelas donde el orden no importe.
+
+**Prioridad:** Baja (no es un problema actualmente, pero conviene prevenir)
+
+---
+
+### 6.2 Carga completa de `commands/ai.js` en cada invocación del CLI
+
+**Problema detectado:** El archivo `commands/ai.js` tiene 3438 líneas y requiere (via `require`) toda su cadena de dependencias en cada invocación del CLI, aunque el usuario esté ejecutando `quiver flow` o `quiver plan`.
+
+**Posible causa:** Node.js carga y parsea todos los `require()` en el entrypoint de forma síncrona.
+
+**Impacto:** Pequeño overhead de startup. En Node.js moderno es menos de 100ms en la mayoría de casos, pero es un overhead evitable.
+
+**Recomendación:** Lazy-require de `commands/ai.js` y otros módulos pesados. Cargarlos solo cuando el comando correspondiente sea el que se invoca.
+
+**Prioridad:** Baja
+
+---
+
+### 6.3 `evidence run` usa `spawnSync` (bloqueante)
+
+**Problema detectado:** La ejecución de comandos en `evidence run` usa `spawnSync`, que bloquea el event loop durante toda la ejecución del comando.
+
+**Posible causa:** Simplicidad de implementación para capturar output completo.
+
+**Impacto:** Para comandos de evidencia cortos (segundos), el impacto es mínimo. Para comandos largos (suites de tests de varios minutos), el proceso CLI queda bloqueado sin posibilidad de manejar señales.
+
+**Recomendación:** Migrar a `spawn` async con acumulación de output en streams. Agregar manejo de `SIGINT` para poder interrumpir la ejecución.
+
+**Prioridad:** Media
+
+---
+
+### 6.4 Escaneo de proyecto sin límite de profundidad declarado
+
+**Problema detectado:** El análisis del proyecto en `analyze` usa lectura recursiva de directorios. Si no hay límite de profundidad configurado, en monorepos muy grandes puede leer miles de archivos innecesarios.
+
+**Posible causa:** No se pudo verificar el comportamiento exacto de `lib/project-scan.js` — es un supuesto basado en el patrón observado en `commands/spec.js` (`findSliceJsonFiles`).
+
+**Impacto:** Potencial lentitud en el primer `analyze` de proyectos grandes.
+
+**Recomendación:** Verificar si `lib/project-scan.js` respeta archivos `.gitignore` y límites de profundidad. Si no, agregar soporte para ignorar `node_modules`, `.git`, `dist`, y otras carpetas pesadas.
+
+**Prioridad:** Media
+
+---
+
+## 7. Mejoras de Performance Recomendadas
+
+### 7.1 Implementar lazy-require para módulos pesados
+
+```js
+// En lugar de en el top del archivo:
+const { runXxx } = require('./commands/ai');
+
+// Dentro del bloque que lo necesita:
+if (mode === 'ai') {
+  const { runXxx } = require('./commands/ai');
+  // ...
+}
+```
+
+Esto reduce el tiempo de startup cuando el usuario ejecuta comandos simples como `quiver flow` o `quiver version`.
+
+### 7.2 Caché de estado de proyecto durante la sesión
+
+Comandos como `flow`, `dashboard`, `plan` y `next` todos llaman a `resolveProjectState()`. Si se ejecutan en el mismo proceso (por ejemplo, en automatizaciones que encadenan comandos), no hay caché entre llamadas. Implementar un módulo de caché en memoria con TTL corto (1-2 segundos) reduciría el I/O redundante.
+
+### 7.3 Agregar campo `engines` en `package.json`
+
+```json
+"engines": {
+  "node": ">=18.0.0"
+}
+```
+
+Permite que npm advierta al usuario si está usando una versión de Node.js incompatible, evitando bugs de runtime difíciles de diagnosticar.
+
+### 7.4 Lazy-load de dependencias opcionales
+
+`@clack/prompts` solo se necesita en comandos interactivos (TTY). Si el CLI detecta que está en modo JSON o no-TTY, no necesita cargar esa dependencia. Cargarla lazy reduce el overhead de startup en pipelines de CI.
+
+### 7.5 Paralelización de lecturas en `analyze`
+
+En `analyze`, las lecturas de archivos de configuración, detección de frameworks y generación de mapa de proyecto pueden paralelizarse con `Promise.all()`. Esto puede reducir el tiempo de análisis en proyectos medianos de 2-4 segundos a menos de 1 segundo.
+
+---
+
+## 8. Errores o Debilidades en la Documentación
+
+### 8.1 `CONTRIBUTING.md` críticamente escaso
+
+**Problema:** El `CONTRIBUTING.md` tiene 16 líneas totales. Describe el proceso a muy alto nivel pero omite completamente:
+- Cómo configurar el entorno de desarrollo
+- Cómo ejecutar los tests
+- Guías de estilo de código
+- Proceso de revisión de PRs
+- Convenciones de nombres de branches
+- Cómo reportar bugs vs. proponer features
+
+**Impacto:** Un contribuidor externo no puede empezar sin leer el README y deducir los pasos de desarrollo.
+
+---
+
+### 8.2 Errores de encoding en `CLI_UX_GUIDE.md`
+
+**Problema:** El archivo `docs/CLI_UX_GUIDE.md` tiene múltiples palabras sin acentos:
+- "estandar" → "estándar"
+- "Ningun" → "Ningún"
+- "solo" → "sólo" (en contexto de restricción)
+- "canonico" → "canónico"
+- "Mas" → "Más"
+- "Tambien" → "También"
+
+**Archivo relacionado:** `docs/CLI_UX_GUIDE.md`
+
+**Impacto:** Reduce la percepción de calidad y profesionalismo del proyecto, especialmente en un CLI que tiene soporte oficial de español.
+
+---
+
+### 8.3 `ROADMAP.md` mezcla información interna con pública
+
+**Problema:** El ROADMAP usa referencias internas de specs (`v27`, `v28`, etc.), menciona entradas `[Unreleased]` del changelog, y tiene secciones de "Post-Checkpoint Plan" con notas internas que no aportan valor a un contribuidor o usuario externo.
+
+**Impacto:** Un usuario externo que lee el ROADMAP no puede distinguir qué está planeado, qué ya está implementado y qué es una nota interna de mantenimiento.
+
+---
+
+### 8.4 `SECURITY.md` sin método de contacto
+
+**Problema:** La política de seguridad dice "Report the issue privately to the maintainers" sin especificar un email, formulario o proceso concreto.
+
+**Archivo relacionado:** `SECURITY.md`
+
+**Impacto:** Un investigador de seguridad que encuentra una vulnerabilidad no tiene forma clara de reportarla de manera responsable.
+
+---
+
+### 8.5 `[Unreleased]` en `CHANGELOG.md` sin formalizar
+
+**Problema:** La sección `[Unreleased]` del changelog describe cambios de v30 y v31 (que el ROADMAP marca como "release-ready, pending package publication") pero no tienen fecha ni número de versión final asignado.
+
+**Impacto:** Un usuario que lee el changelog no puede saber qué versión del CLI incluye los cambios de esa sección.
+
+---
+
+### 8.6 Falta `ARCHITECTURE.md`
+
+**Problema:** No existe un documento que explique la arquitectura del proyecto: estructura de módulos, responsabilidades de cada capa (`commands/`, `lib/`, `lib/ai/`, `lib/cli/`, `lib/i18n/`, `lib/renderers/`), flujo de datos, y decisiones de diseño.
+
+**Impacto:** Un nuevo contribuidor debe leer el código fuente completo para entender cómo encajan las piezas.
+
+---
+
+### 8.7 Referencia a "v47" en `CLI_UX_GUIDE.md` y `reference/commands.md`
+
+**Problema:** El `CLI_UX_GUIDE.md` menciona "En v47 la superficie canónica de configuración sigue siendo `config language show|set`". El proyecto está en v0.15. "v47" es un número de spec interno que no tiene ningún significado para un lector externo.
+
+**Archivo relacionado:** `docs/CLI_UX_GUIDE.md`, `docs/reference/commands.md`
+
+**Impacto:** Confusión sobre la versión a la que aplica la documentación.
+
+---
+
+### 8.8 `separator.md` sin propósito documentado
+
+**Problema:** Existe un archivo `separator.md` en la raíz del proyecto sin contenido explicativo de su propósito. No está referenciado en el README ni en la guía de contribución.
+
+**Impacto:** Confusión para contribuidores que no saben si es un archivo de configuración, un artefacto de proceso o un error.
+
+---
+
+### 8.9 Archivos `.template` en la raíz del repositorio sin explicación
+
+**Problema:** Archivos como `TEMPLATE.md`, `AGENTS.md.template`, `AGENTS.md.es.template`, `package.template.json` en la raíz no están explicados en el README ni en el `CONTRIBUTING.md`.
+
+**Impacto:** Un contribuidor no sabe qué son estos archivos, si debe editarlos o si son generados automáticamente.
+
+---
+
+### 8.10 `docs/TROUBLESHOOTING.md.template` existe como template pero la instancia del proyecto vive en `docs/TROUBLESHOOTING.md`
+
+**Problema:** Existe tanto `docs/TROUBLESHOOTING.md.template` (template para proyectos generados por Quiver) como `docs/TROUBLESHOOTING.md` (para el propio repositorio de Quiver). La distinción no está clara sin leer los archivos.
+
+---
+
+### 8.11 Ejemplos en `examples/` sin enlace prominente desde el README
+
+**Problema:** El directorio `examples/01-basic-slice/` existe pero no está enlazado ni mencionado en el README principal. Es un recurso valioso para usuarios nuevos que no tiene visibilidad.
+
+---
+
+## 9. Oportunidades de Mejora en Documentación
+
+### 9.1 Expandir `CONTRIBUTING.md`
+
+Agregar como mínimo:
+- **Setup de desarrollo:** `git clone`, `npm install`, `node bin/create-quiver.js --help`
+- **Cómo ejecutar tests:** `node --test tests/**/*.test.js`
+- **Cómo ejecutar smoke tests:** los 4 scripts disponibles
+- **Convenciones de commits:** si hay convención (Conventional Commits u otra)
+- **Proceso de PR:** qué se espera en el body, qué checks deben pasar
+- **Arquitectura del proyecto:** referencia a `ARCHITECTURE.md` (a crear)
+
+### 9.2 Crear `ARCHITECTURE.md`
+
+Un documento de 1-2 páginas que explique:
+- Entrypoints (`bin/`, `src/create-quiver/index.js`)
+- Responsabilidades de `commands/` vs `lib/`
+- Subdirectorios clave: `lib/ai/`, `lib/cli/`, `lib/i18n/`, `lib/renderers/`
+- Cómo se registra un nuevo comando
+- Cómo funciona el sistema i18n
+- Cómo se ejecutan los tests
+
+### 9.3 Corregir acentos en `CLI_UX_GUIDE.md`
+
+Pasada de revisión para corregir todos los acentos faltantes. Agregar un linter de markdown (`markdownlint`) para prevenir regresiones.
+
+### 9.4 Simplificar `ROADMAP.md` para audiencia pública
+
+Separar en dos secciones:
+- **Público:** qué funcionalidades están planeadas, en qué orden, sin referencias a specs internas
+- **Interno:** (o mover a un archivo separado) referencias a specs v27-v31, notas de dogfooding, etc.
+
+### 9.5 Agregar contacto a `SECURITY.md`
+
+Agregar un email de contacto o un formulario (por ejemplo, un issue privado de GitHub con la plantilla de seguridad). GitHub tiene soporte nativo para reportes de vulnerabilidades privados vía `Settings > Code security > Private vulnerability reporting`.
+
+### 9.6 Enlazar `examples/` desde el README
+
+Agregar una sección "Ejemplos" en el README que enlace al directorio `examples/01-basic-slice/` y explique brevemente qué muestra cada ejemplo.
+
+### 9.7 Eliminar referencias a versiones internas de specs en documentación pública
+
+Reemplazar referencias como "En v47" por "En la versión actual" o simplemente omitirlas. Los números de spec son artefactos de proceso interno sin significado externo.
+
+### 9.8 Documentar el propósito de archivos en la raíz
+
+En el `CONTRIBUTING.md` o en un `README` de la raíz, explicar para qué sirven `separator.md`, `TEMPLATE.md`, `package.template.json`, y los archivos `.template`.
+
+### 9.9 Agregar campo `engines` al `package.json` y documentarlo
+
+```json
+"engines": {
+  "node": ">=18.0.0"
+}
+```
+
+Y documentar en el README / guías de instalación qué versión de Node.js es la mínima requerida.
+
+### 9.10 Formalizar la sección `[Unreleased]` del CHANGELOG antes de cada release
+
+Agregar el proceso de formalización del changelog como un paso documentado en `scripts/release-quiver.sh` o en el CONTRIBUTING.
+
+---
+
+## 10. Priorización General
+
+| Prioridad | Área | Hallazgo | Acción Recomendada | Impacto Esperado |
+|---|---|---|---|---|
+| Alta | UX/CLI | Mensajes de error no localizados (6 comandos) | Reemplazar `formatError()` locales con i18n | Experiencia consistente para usuarios de `--lang es` |
+| Alta | UX/CLI | `migrate` modifica archivos sin confirmación | Agregar advertencia y paso de preview obligatorio | Prevenir pérdida de datos en migración |
+| Alta | UX/CLI | Namespace plano con 8 comandos de slice/handoff | Completar implementación de `slice` y `handoff` namespaces (ya en CLI_UX_GUIDE) | Reducir carga cognitiva, CLI más coherente |
+| Alta | Docs | `CONTRIBUTING.md` de 16 líneas | Expandir con setup, tests, convenciones, arquitectura | Facilita contribuciones externas |
+| Alta | Automatización | Sin CI declarativo (GitHub Actions) | Crear workflow que ejecute tests y smokes en cada PR | Detecta regresiones antes de merge |
+| Alta | UX/CLI | Sin feedback de progreso en `init` y `analyze` | Agregar spinner de `@clack/prompts` | Percepción de CLI responsivo |
+| Media | Performance | `evidence run` usa `spawnSync` | Migrar a `spawn` async con manejo de señales | Permite interrumpir evidencias largas |
+| Media | UX/CLI | `--auto-start` en `next` no usa sistema i18n | Reemplazar readline manual con `lib/cli/selectors.js` | Consistencia de UX y localización |
+| Media | Docs | Acentos faltantes en `CLI_UX_GUIDE.md` | Corrección manual + agregar `markdownlint` | Calidad y profesionalismo de docs |
+| Media | Docs | `SECURITY.md` sin método de contacto | Agregar email o activar private vulnerability reporting | Proceso de seguridad responsable |
+| Media | Modernización | Scripts bash en `package.json` no portables | Reemplazar con comandos Node CLI | Portabilidad Windows |
+| Media | Automatización | Changelog manual | Adoptar Conventional Commits + release-please | Releases más ágiles y consistentes |
+| Media | Docs | Referencias a "v47" en docs públicas | Eliminar referencias a versiones de spec internas | Claridad para contribuidores externos |
+| Baja | Performance | I/O síncrono en toda la capa de lecturas | Evaluar paralelización en `analyze` con `Promise.all` | Mejora en proyectos grandes |
+| Baja | Modernización | Sin TypeScript | Migración incremental desde módulos `lib/` | Mejor DX para contribuidores |
+| Baja | Modernización | Sin JSON Schema para `slice.json` | Generar desde Zod, publicar en SchemaStore | Validación en IDE para usuarios |
+| Baja | Modernización | Sin shell completion | Implementar comando `completion` | Ergonomía para usuarios avanzados |
+| Baja | UX/CLI | `plan` no avisa de `estimated_hours` faltante | Agregar nota informativa en el output | Mejor guía para usuarios nuevos |
+| Baja | UX/CLI | `graph --level` vacío sin mensaje | Agregar mensaje explicativo | Evita confusión sobre si funcionó |
+| Baja | Docs | `examples/` no enlazado desde README | Agregar sección Ejemplos en README | Mejor onboarding de usuarios nuevos |
+
+---
+
+## 11. Roadmap de Mejoras Sugerido
+
+### Corto plazo (próximas 2-4 semanas)
+
+- Localizar todos los `formatError()` hardcodeados en inglés en los 6 comandos afectados.
+- Agregar advertencia de preview obligatoria en `migrate` antes de ejecutar.
+- Completar la implementación de los namespaces `slice` y `handoff` (ya documentados en `CLI_UX_GUIDE.md` como canónicos).
+- Agregar spinner de progreso en `init` y `analyze`.
+- Expandir `CONTRIBUTING.md` con setup, tests y convenciones.
+- Corregir acentos faltantes en `CLI_UX_GUIDE.md`.
+- Agregar `"engines"` al `package.json`.
+- Agregar método de contacto a `SECURITY.md` (activar private vulnerability reporting en GitHub).
+- Agregar `next_command` al JSON output de `flow`.
+- Agregar validación de `--section` en `dashboard` con lista de valores válidos.
+
+### Mediano plazo (próximos 1-3 meses)
+
+- Crear workflow de GitHub Actions para CI (tests + smokes en ubuntu, macos, windows).
+- Crear `ARCHITECTURE.md` con descripción de capas, módulos y flujo de datos.
+- Implementar `evidence list` y `evidence show` (ya documentados en `README_FOR_AI.md`).
+- Migrar `evidence run` de `spawnSync` a `spawn` async.
+- Fragmentar `commands/ai.js` en módulos por dominio.
+- Simplificar `demo create spec-viewer` a `demo spec-viewer`.
+- Reemplazar scripts bash en `package.json` con equivalentes Node CLI.
+- Adoptar Conventional Commits y automatizar generación de changelog.
+- Simplificar `ROADMAP.md` para separar información pública de interna.
+- Generar JSON Schema para `slice.json` desde Zod.
+- Agregar `markdownlint` y `markdown-link-check` al proceso de CI.
+
+### Largo plazo (próximos 3-6 meses)
+
+- Migrar el parser manual a Commander.js o yargs (lazy-loading para mantener startup rápido).
+- Implementar lazy-require para módulos pesados (especialmente `commands/ai.js`).
+- Agregar scripts de shell completion (bash, zsh, fish).
+- Migración incremental a TypeScript (comenzar por `lib/`).
+- Automatización completa de releases con GitHub Actions (tag → npm publish).
+- Publicar JSON Schema de `slice.json` en SchemaStore.
+- Implementar paralelización de lecturas en `analyze` con `Promise.all`.