Files

Marcos Benítez 5ef385c4a3 actualizada politica de toma de decisión

2026-05-17 00:37:44 -03:00

12 KiB

Raw Blame History

CLAUDE.md — Contexto del Proyecto

Este archivo es leído automáticamente por Claude Code en cada sesión. Define el "norte" del proyecto y las reglas no negociables.

⚠️ Reglas de Marca — NO NEGOCIABLES (Sprint 1.5+)

Estas reglas aplican a TODO string que aparezca en código, PDFs, CSVs, tests y documentación.

1. Ortografía de "InQ" — SIEMPRE I-n-Q

✅ InQ          ← correcto
✅ InQuality    ← correcto (nombre completo)
✅ InQ ROI      ← nombre del producto

❌ INQ          ← bug
❌ Inq          ← bug
❌ inq          ← bug
❌ inQ          ← bug

Cualquier desviación es un bug que debe corregirse antes de hacer commit.

2. Nombre del producto

InQ ROI — nombre de trabajo para Sprint 1.5. Se reemplazará en Sprint 3-4. No debatir el nombre ahora.

3. Color protagonista

Primario:  #F59845  (naranja InQ)
Gradiente: #F59845 → #ED3E8F  (naranja → magenta InQ)

El gradiente se usa SOLO en KPI Hero y banners principales. NO usar morado de CONCILIA (#572FA2, #CB1889) en este producto.

4. Footer de PDFs

Tagline obligatorio: "Powered by InQuality" — en todos los footers de PDF, siempre.

5. Rol del consultor

Si aparece un nombre de consultor en algún campo, es como "consultor responsable", no como "creador" ni "founder" del producto.

Identidad del Proyecto

Nombre de trabajo: Process Cost Platform (nombre comercial por definir)

Una frase: Plataforma web para que consultores de procesos cuantifiquen costos operativos y calculen ROI de automatización a partir de archivos BPMN 2.0.

Mantra: Los procesos de negocio son activos estratégicos de las empresas y un diferencial competitivo.

Estado Actual

Fase: 1 — Sprint 1 (ROI y escenarios de automatización)
Fase anterior completada: 0 — MVP "Noche Cero" (v0.1.0-mvp, deployado en https://process-cost-platform.pages.dev)
Documento maestro: ARCHITECTURE.md (raíz del repo)
Audiencia primaria del Sprint 1: equipo de InQuality (consultora de procesos)
Caso de uso primario: pre-venta de proyectos de automatización con cálculo de ROI
Deploy: Cloudflare Pages (estático, gratis)

Reglas No Negociables — Sprint 1

✅ Lo que SÍ entra en Sprint 1

Volumetría del proceso: frecuencia anual de ejecución + horizonte de análisis (años)
Marcado de actividades automatizables con costos automatizados (tiempo + costo fijo)
Inversión en automatización como dato del proceso (un único valor agregado)
Motor de simulación dual: corre escenarios "actual" y "automatizado" sobre el mismo BPMN
Sección de ROI en el reporte: KPIs grandes, tabla comparativa, gráficos de payback y ahorros
5 KPIs de ROI: Ahorro por ejecución, Ahorro anual, Payback (meses), Ahorro acumulado a N años, ROI % anualizado
Mecanismo de transparencia: detecta valores cero o inversión cero y los expone en el reporte
Migración Dexie v1 → v2 con datos existentes preservados
Export PDF/CSV ampliado para incluir páginas/datos de ROI
Documento metodológico anexo sobre cómo calcular el costo automatizado por ejecución

❌ Lo que NO entra en Sprint 1

Múltiples escenarios (más de 2)
Escenarios como entidad separada (modelo B) — sigue siendo modelo A: dos pares de campos por actividad
VPN, TIR, tasa de descuento (cálculos financieros sofisticados)
Captura desglosada del costo de automatización (licencias, desarrollo, infra) — un único campo
Análisis de sensibilidad ("¿qué pasa si la frecuencia cae 30%?")
Distribuciones probabilísticas
Modelar bots como recursos con capacidad
Multi-tenant, login, colaboración, versionado, IA, modo oscuro, i18n, PWA

Si dudás si una feature entra: NO ENTRA. Defendé el alcance. Anotala en TODO.md.

Decisiones Arquitectónicas Adoptadas (Sprint 1)

Modelo de escenarios: Modelo A (dos campos por actividad)

Cada actividad tiene:

directCostFixed y executionTimeMinutes (escenario actual, ya existían)
automatedCostFixed y automatedTimeMinutes (nuevos, escenario automatizado)
automatable: boolean (default false)

NO se modela con dos diagramas distintos. Un BPMN, dos pares de campos por actividad. El motor recibe un parámetro scenario: 'actual' | 'automated' y aplica los campos correspondientes.

Migración a "escenarios como entidad" se evaluará en Sprint 3-4 si InQuality lo demanda.

Volumetría: multiplicador en el reporte, no en el motor

El motor sigue siendo determinístico y calcula "una ejecución". La volumetría (frecuencia anual + horizonte) es un parámetro del proceso que el reporte usa para extrapolar:

costoAnual = costoUnitario × frecuenciaAnual
costoHorizonte = costoAnual × horizonteAños

No se introduce VPN ni Monte Carlo en Sprint 1.

ROI: cálculos nominales simples

savingsPerExecution = costActual - costAutomated
annualSavings = savingsPerExecution × annualFrequency
paybackMonths = (automationInvestment / annualSavings) × 12
cumulativeSavingsHorizon = (annualSavings × horizonYears) - automationInvestment
roiAnnualPercent = (annualSavings / automationInvestment) × 100

Edge cases manejados explícitamente: inversión cero, ahorro negativo, división por cero.

Transparencia metodológica

Si se detectan valores cero (costo automatizado en cero, inversión en cero, etc.), el reporte muestra una sección visible pero discreta ("Transparencia metodológica") con la lista de valores no informados. Es feature, no bug: convierte una posible debilidad en señal de seriedad profesional para el cliente.

Stack Tecnológico (sin cambios respecto al MVP)

Capa	Tecnología
Lenguaje	TypeScript estricto
Framework	React 18 + Vite
Routing	TanStack Router
Estado	Zustand
Canvas BPMN	bpmn-js (Viewer, no Modeler)
UI	shadcn/ui sobre Tailwind CSS
Iconos	Lucide React
Gráficos	Apache ECharts (vía echarts-for-react)
Persistencia	IndexedDB vía Dexie
Validación	Zod
Export PDF	jsPDF + jsPDF-autotable + html2canvas
Export CSV	papaparse
Testing	Vitest + Playwright
Deploy	Cloudflare Pages

No introduzcas librerías fuera de esta lista sin justificación explícita.

Arquitectura de Carpetas

src/
├── main.tsx
├── App.tsx
├── router.tsx
├── domain/           ← lógica de negocio pura, sin React, testeable
│   ├── types.ts
│   ├── simulation.ts ← motor de simulación (acepta scenario)
│   ├── roi.ts        ← NUEVO en Sprint 1: cálculos puros de ROI
│   ├── bpmn-parser.ts
│   └── schemas.ts    ← Zod schemas
├── store/            ← Zustand stores
├── persistence/      ← Dexie / IndexedDB (v2 en Sprint 1)
├── features/         ← organizado por feature, no por tipo
│   ├── import/
│   ├── workspace/    ← ampliado en Sprint 1 (panel de automatización)
│   ├── simulation/   ← ampliado (dispara dual scenario)
│   └── report/       ← ampliado (tab Comparación + ROI)
├── components/ui/    ← shadcn copy-pastes
├── lib/              ← utilidades transversales (format, colors, pdf, csv)
└── styles/

Reglas de dependencia (sin cambios):

domain/ NO importa de React, ni de store/, ni de features/. Es puro.
features/ puede importar de domain/, store/, persistence/, lib/, components/.
store/ puede importar de domain/ y persistence/. Nada más.

Principios de Código

TypeScript strict activado. Nada de any salvo en bordes con librerías sin tipos.
Dominio puro: motor y cálculos de ROI son funciones puras testeables sin DOM.
Componentes tontos, hooks inteligentes: lógica en custom hooks, JSX limpio.
Sin lógica de negocio en componentes.
Convenciones de naming:
- Componentes: PascalCase.tsx
- Hooks: useCamelCase.ts
- Utilidades: kebab-case.ts
- Tipos: PascalCase, interfaces con prefijo I PROHIBIDO
Comentarios en español, código (variables, funciones) en inglés.
Errores con mensajes accionables para el usuario, nunca traces crudos en UI.
Migraciones de schema: SIEMPRE incrementar versión en Dexie, escribir función de upgrade y test que valide preservación de datos.

Diferencial Visual (sigue siendo CRÍTICO)

El reporte sigue siendo el corazón. En Sprint 1 se le agregan páginas. Reglas:

Tipografía: Inter para UI, JetBrains Mono para números/datos
Paleta heatmap: verde #10b981 → amarillo #f59e0b → rojo #ef4444
Paleta ROI:
- Ahorro positivo: verde #10b981
- Ahorro marginal o neutro: gris #64748b
- Ahorro negativo o payback fuera de horizonte: rojo #ef4444
- Advertencias de transparencia: amarillo #f59e0b (no rojo: es informativo, no error)
Cifras de dinero siempre formateadas con separadores y símbolo de moneda
KPIs de ROI más grandes que los KPIs del reporte de costos (es la sección que vende)
El export PDF debe verse igual o mejor que la pantalla
Densidad de información media-alta (audiencia: consultor profesional)

Definition of Done — Cada Feature

Antes de marcar una tarea como terminada:

Funciona en el happy path
Maneja el caso de datos vacíos sin crashear
Maneja edge cases definidos (división por cero, valores negativos, valores cero)
Persiste en IndexedDB cuando corresponde (con migración si cambió schema)
Tiene estilo consistente con el resto de la app
Si toca dominio: tiene al menos un test en Vitest
Si toca el flujo end-to-end: tiene cobertura en Playwright

Comandos del Proyecto

npm run dev              # desarrollo
npm run build            # producción
npm run test             # tests unitarios con Vitest
npm run lint             # eslint
npm run preview          # previsualizar build de producción
npx playwright test      # tests E2E (Playwright headless)

Cómo Trabajar Conmigo (el Usuario)

Cuando termines una tarea grande, resumí qué cambió y qué falta.
Si una decisión no está clara, proponé 2-3 opciones con pros/contras antes de codear.
Si encontrás que algo del documento de arquitectura está mal o falta, avisame antes de improvisar.
No agregues features no pedidas. Si algo se te ocurre, anotalo en TODO.md.
Cuando completes algo, mostrame los archivos creados/modificados, no los pegues completos en el chat salvo que te lo pida.
Validá programáticamente lo que yo no puedo ver visualmente (uso Mac + VS Code + Claude Code sin browser interactivo). Para flujos críticos: Playwright + extracción de datos del PDF/CSV generado.
Si un test revela algo raro: NO racionalices el problema, investigá la causa raíz. Los tests no mienten.

Contexto del Fundador y Equipo

Consultor de automatización de procesos basado en Paraguay
Construye esto como herramienta consultiva propia + del equipo de InQuality + para vender a colegas LATAM
Usa Claude Code Pro como único "equipo de desarrollo"
Sprint 1 es para uso interno de InQuality (no para mostrar a cliente todavía)
Casos de uso confirmados:
- Análisis de costos operativos en consultoría de procesos
- Pre-venta de proyectos de automatización con cálculo de ROI (caso estrella del Sprint 1)
Valora: claridad, robustez, pulido visual, mantenibilidad, validación rigurosa

Reglas de marca NO NEGOCIABLES

"InQ" siempre se escribe I-n-Q (mayúscula-minúscula-mayúscula)
Color protagonista: naranja #F59845
Gradiente identidad: #F59845 → #ED3E8F
NO usar morado CONCILIA (#572FA2, #CB1889)
Footer obligatorio: "Powered by InQuality"
No promover a Marcos como creador

Verificación final antes de present_files

Antes de presentar cualquier PDF al usuario, verificá que:

El header/footer dice "InQ ROI" (no "Process Cost Platform" ni otro)
El footer incluye "Powered by InQuality"
No hay caracteres rotos (símbolos sin renderizar)
La marca "InQ" se escribe siempre I-n-Q

Política de iniciativa proactiva

Cuando detectés una oportunidad de mejora fuera del scope del prompt actual:

Cambios triviales (variables internas, reordenar imports): ejecutar
Cambios visibles pero reversibles (wording, spacing, tooltips): ejecutar y reportar explícitamente al final
Cambios de marca, arquitectura o datos (paleta, dependencias, estructura, features nuevas): CONSULTAR ANTES DE PROCEDER

Ver methodology/PRINCIPLES.md sección "Política de iniciativa agéntica" para detalle completo.

12 KiB Raw Blame History Unescape Escape