La IA no arregla el pensamiento desordenado. Lo acelera.
Dale a un modelo de lenguaje grande (LLM) una idea vaga y obtendrás una respuesta vaga. Dale un documento bien estructurado, con terminología clara, problemas acotados y brechas registradas, y se convierte en el colaborador más productivo con el que hayas trabajado.
El cuello de botella en 2026 no es escribir código. La IA escribe código rápido. El cuello de botella es saber qué construir, y poder expresarlo con la claridad suficiente para que tanto las personas como la IA puedan ejecutarlo.
Este artículo presenta un marco para hacer justo eso. No trata de herramientas de IA. Trata de cómo organizas tus ideas para que cualquier problema complejo se vuelva abordable.
Dream → Concrete → Divide → Gaps → Fix → Realize → Share
↑ |
└───────────────── feedback loop ────────────────────┘Cada fase transforma tu forma de pensar. Cada una produce un artefacto. Así funcionan.
Tienes una idea. Está a medio formar, es ambiciosa y probablemente irreal tal como está ahora. No pasa nada.
Pídele a la IA lo que tengas en la cabeza, aunque sea una sola frase, y deja que genere un documento del sueño. Es aspiracional, no preciso. Lo importante es sacar la idea de tu cabeza y llevarla a un documento donde puedas verla, reaccionar a ella y empezar a darle forma.
Ejemplo de prompt:
I want to build an AI-powered medical diagnosis platform
that helps doctors catch rare diseases earlier. A patient
describes symptoms, the system triages, suggests possible
diagnoses, and routes to the right specialist.
Generate a dream document with:
- The vision (what does this look like when it's done?)
- Current landscape (what exists today and what's missing?)
- Key concepts I'll need to define
- Open questionsLo que recibes:
Un documento del sueño estructurado. Quizá de dos o tres páginas. Recoge tu intención, traza el panorama (UpToDate, Isabel Healthcare, Ada Health: qué hacen bien y dónde se quedan cortos) y plantea preguntas en las que aún no habías pensado. «¿Qué significa "detectar antes"? ¿Un triaje más rápido? ¿Un mejor diagnóstico diferencial? ¿Señalar patrones en el historial del paciente?»
No necesitabas ordenar tus ideas primero: la IA hizo el primer borrador. Ahora tienes algo ante lo que reaccionar.
El documento del sueño no es un plan. Es una brújula. Te da la dirección, no los pasos.
Artefacto: dreams/ai-diagnosis-platform.md
Ahora tomas el sueño y lo conviertes en un documento de referencia concreto. Es estructurado, preciso y acotado. Define tus términos. Dibuja tu arquitectura. Especifica qué entra y qué se queda fuera.
Aquí es donde la IA se gana el sueldo. Pásale el documento del sueño:
Here's my dream doc: [paste].
Turn this into a concrete reference document with:
- Defined terms and concepts
- Architecture sections with clear boundaries
- Scope (what this covers, what it doesn't)
- Open questions marked as [GAP] placeholdersEjemplo de resultado:
Lo que empezó como «Quiero que la IA ayude a los médicos a detectar enfermedades raras» se convierte en un documento de referencia que cubre:
Este documento es ahora tu única fuente de verdad. No el código. No el historial del chat. No la memoria de alguien. El documento.
Artefacto: docs/Diagnosis_Platform.md
Tu documento concreto se va alargando. Algunas secciones ocupan diez páginas por sí solas. Esa es la señal para dividir.
Divide el documento concreto en documentos de división enfocados, cada uno lo bastante profundo para sostenerse solo, pero conectado con el conjunto.
Here's my concrete doc: [paste].
Which sections are complex enough to deserve their own
focused document? For each, suggest a title and scope.Ejemplo:
El documento de referencia de una plataforma de diagnóstico médico se divide de forma natural en:
| Documento de división | Cubre |
|---|---|
Symptom_Engine.md | Flujo de entrada, normalización de síntomas, análisis multilingüe |
Diagnosis_Model.md | Ranking diferencial, umbrales de confianza, explicabilidad |
Specialist_Routing.md | Emparejamiento de especialidades, niveles de urgencia, flujos de derivación |
Patient_Records.md | Integración con EHR, formatos FHIR/HL7, retención de datos |
Compliance.md | Controles HIPAA, clasificación SaMD, rastro de auditoría |
Clinical_UI.md | Panel del médico, entrada del paciente, adaptación a móvil |
Estas no son solo divisiones del conocimiento: son tus módulos de código. Cada documento de división se corresponde directamente con una unidad real de código: un microservicio, un paquete en un monorepo, un módulo en un monolito o un contexto delimitado (bounded context) en el diseño dirigido por el dominio. El documento describe lo que hace el módulo y el código lo implementa.
Division Doc → Code Module
─────────────────────────────────────────────
Symptom_Engine.md → packages/symptom-engine/
Diagnosis_Model.md → packages/diagnosis-model/
Specialist_Routing.md → packages/specialist-routing/
Patient_Records.md → packages/patient-records/
Compliance.md → packages/compliance/
Clinical_UI.md → apps/clinical-dashboard/Una vez que los documentos se corresponden con el código, creas un documento índice: un único archivo que vive en la raíz de tu proyecto y asocia cada documento con su módulo de código. Piensa en él como el índice de contenidos de todo tu sistema. Cuando un agente de IA (o un miembro nuevo del equipo) necesita trabajar en la derivación, mira el índice, encuentra Specialist_Routing.md → packages/specialist-routing/ y tiene todo el contexto antes de tocar una sola línea de código.
## Project Index
| Working In | Primary Doc | Gaps |
|---|---|---|
| `packages/symptom-engine/` | [Symptom_Engine.md](docs/Symptom_Engine.md) | [Symptom_Engine_Gaps.md](docs/Symptom_Engine_Gaps.md) |
| `packages/diagnosis-model/` | [Diagnosis_Model.md](docs/Diagnosis_Model.md) | [Diagnosis_Model_Gaps.md](docs/Diagnosis_Model_Gaps.md) |
| `packages/specialist-routing/` | [Specialist_Routing.md](docs/Specialist_Routing.md) | [Specialist_Routing_Gaps.md](docs/Specialist_Routing_Gaps.md) |
| `packages/patient-records/` | [Patient_Records.md](docs/Patient_Records.md) | [Patient_Records_Gaps.md](docs/Patient_Records_Gaps.md) |
| `packages/compliance/` | [Compliance.md](docs/Compliance.md) | [Compliance_Gaps.md](docs/Compliance_Gaps.md) |
| `apps/clinical-dashboard/` | [Clinical_UI.md](docs/Clinical_UI.md) | [Clinical_UI_Gaps.md](docs/Clinical_UI_Gaps.md) |Este índice se convierte en el archivo más importante del repositorio. Es el puente entre el pensamiento organizado y el código organizado.
Artefacto: docs/DX_Symptom_Engine.md, docs/DX_Compliance.md + el índice del CLAUDE.md raíz
Aquí es donde el marco realmente funciona. Una vez que tienes los documentos concretos y los de división, puedes ver lo que falta.
Las brechas no son fracasos. Son el marco haciendo su trabajo. No puedes ver lo que falta hasta que has escrito lo que hay.
Sigue las brechas con códigos de brecha: identificadores cortos que las hacen buscables y referenciables:
### GAP-DX004: Model suggests diagnosis but doesn't explain reasoning
- **Phase**: Diagnosis output
- **Area**: Diagnosis model — result presentation layer
- **Impact**: Doctor sees "Possible: Lupus (82% confidence)"
but no explanation of which symptoms contributed or why
alternatives were ruled out. Doctor can't trust or verify
the suggestion. Useless in clinical practice.
- **Root Cause**: Model outputs a ranked list with scores
but no reasoning chain. Explainability was never specified
in the architecture — it was assumed to be a UI concern.
- **Fix**: Add an explainability module that maps each
diagnosis to contributing symptoms, relevant patient
history, and ruled-out alternatives. Display as
"evidence for / evidence against" in the clinical UI.
- **Priority**: Critical
- **Status**: OpenEl formato del código de brecha te da:
| Campo | Propósito |
|---|---|
| Código (Code) | ID buscable (GAP-DX004, GAP-C001) con prefijo de categoría |
| Fase (Phase) | En qué momento del sistema aparece |
| Área (Area) | Qué módulo o concepto se ve afectado |
| Impacto (Impact) | Lo que experimentan los usuarios cuando existe esta brecha |
| Causa raíz (Root Cause) | Por qué existe la brecha: causas, no síntomas |
| Solución (Fix) | Solución propuesta (puede ser un plan por fases) |
| Prioridad (Priority) | Crítica / Alta / Media / Baja |
| Estado (Status) | Abierta / En curso / Resuelta (con fecha) |
Los prefijos de categoría mantienen las brechas ordenadas: GAP-DX para diagnóstico, GAP-SE para el motor de síntomas, GAP-C para cumplimiento, GAP-UI para la interfaz clínica. Desarrollarás tus propias categorías a medida que crezca tu proyecto.
Artefacto: docs/DX_Diagnosis_Gaps.md
Corrige las brechas. Pero no todas a la vez.
Pide siempre un plan de implementación por fases. Las brechas tienen dependencias. Algunas son requisitos previos de otras. Intentar arreglarlo todo a la vez crea caos.
Here are my open gaps: [paste gap doc].
Here's the main concrete doc for context: [paste relevant section].
Create a phased implementation plan:
- Phase 1: Critical gaps that unblock other work
- Phase 2: High-priority gaps
- Phase 3: Medium-priority improvements
For each phase, estimate scope and list dependencies.Cuando se corrige una brecha:
Fixed (2026-02-22) y anota lo que se hizoarchive/. No los borres. Son la historia de tu pensamientoEl documento concreto evoluciona. La versión 1 tenía 20 brechas. La versión 2 cierra 15 y descubre 5 nuevas. La versión 3 cierra esas y el documento se estabiliza. Esto es convergencia: cada pasada te acerca a una descripción completa y honesta de tu sistema.
Artefacto: docs/Diagnosis_Platform.md actualizado, archive/gaps/DX_Diagnosis_Gaps_v1.md archivado
Construye cosas reales a partir de tus documentos. Los proyectos son la prueba de que el marco funciona.
Cada proyecto pone a prueba tu marco frente a la realidad. Cuando algo se rompe, la pregunta es: ¿qué documento está equivocado? El problema remite a una brecha en los documentos, no solo a un error en el código.
Ejemplo:
A partir de un mismo conjunto de documentos de la plataforma de diagnóstico, construyes despliegues piloto: uno para una clínica de urgencias (triaje rápido, mucho volumen, afecciones comunes), otro para un hospital rural (pocos especialistas in situ, derivación a telemedicina) y otro para una consulta pediátrica (interpretación de síntomas ajustada por edad, rangos de referencia distintos).
Cada despliegue pone a prueba los documentos frente a una realidad distinta. Cuando el piloto del hospital rural reveló que la derivación a especialistas suponía que los especialistas estaban en el propio centro, mientras que los hospitales rurales derivan a proveedores remotos de telemedicina con otras ventanas de disponibilidad, no te limitaste a parchear el código. Hiciste lo siguiente:
GAP-SR002 en el documento de brechas de derivaciónSpecialist_Routing.mdAhora los despliegues de urgencias y de pediatría gestionan automáticamente la derivación a telemedicina. Cada proyecto mejora los documentos. Cada mejora de los documentos hace más fiables los proyectos futuros.
Aquí es donde la división paga interés compuesto. Como cada módulo tiene su propio documento autocontenido, puedes combinar módulos entre proyectos completamente distintos. No todos los proyectos necesitan todos los módulos. Los proyectos nuevos se ensamblan eligiendo qué documentos de división incluir.
| Proyecto | Módulos usados |
|---|---|
| Quiosco de triaje de urgencias | Symptom_Engine + Clinical_UI |
| Plataforma rural de telemedicina | Symptom_Engine + Diagnosis_Model + Specialist_Routing |
| Herramienta de investigación clínica | Diagnosis_Model + Patient_Records + Compliance |
| App de autoevaluación para pacientes | Symptom_Engine + Clinical_UI (subconjunto para el paciente) |
| Auditor de cumplimiento hospitalario | Compliance + Patient_Records |
El quiosco de urgencias no necesita el modelo de diagnóstico completo: solo necesita una entrada rápida de síntomas y una interfaz limpia para pasar el caso al médico. La herramienta de investigación no necesita derivación a especialistas: necesita datos de diagnóstico profundos con acceso conforme a los registros. Cada proyecto toma los módulos que necesita y los documentos te dicen exactamente qué estás obteniendo.
Es el mismo principio que hay detrás de los paquetes de un monorepo, la composición de microservicios o incluso las tuberías de Unix: unidades pequeñas y bien documentadas que se combinan en sistemas más grandes. La diferencia es que aquí la composición empieza en el nivel de la documentación. Decides lo que necesita un proyecto leyendo documentos, no leyendo código.
Artefacto: projects/urgent-care-pilot/, projects/rural-hospital-pilot/, etc.
Escribe sobre tu proceso. Enseñar te obliga a entender lo que realmente hiciste.
Entradas de blog, README, tutoriales, documentos internos: el medio no importa. Lo que importa es que expliques tu marco a alguien que no tiene tu contexto. Eso saca a la luz suposiciones que no sabías que estabas haciendo.
Compartir también cierra el ciclo. Una entrada de blog sobre tu enfoque de explicabilidad del diagnóstico podría inspirar a un lector a sugerir una visualización en grafo de síntomas en lugar de listas planas de evidencias. Eso se convierte en un nuevo sueño. El ciclo vuelve a empezar.
Artefacto: entradas de blog, tutoriales, documentación pública
El marco es simple:
Sueña → Escríbelo → Divídelo → Encuentra lo que falta → Corrígelo → Constrúyelo → Compártelo.
En la era de la IA, el pensamiento organizado es la habilidad de mayor impacto que puedes desarrollar. No la ingeniería de prompts. No saber qué modelo usar. Sino la claridad de pensamiento: la capacidad de tomar una idea desordenada y refinarla hasta algo lo bastante preciso para que tanto las personas como la IA puedan ejecutarlo.
Una nota sobre el mantenimiento: los documentos se desfasan. El código cambia, las API se mueven, las dependencias se actualizan. Trata el desfase como una brecha más: audita periódicamente, actualiza los documentos cuando cambie el código y archiva las versiones antiguas en lugar de borrarlas. La historia de tu pensamiento vale tanto como el pensamiento mismo.