# Preparar información exógena para la DIAN

Usa este skill cuando el usuario quiera preparar, revisar o organizar la información
exógena tributaria colombiana para presentar ante la DIAN. El objetivo no es solo
responder qué formatos aplican, sino llevar los datos del contribuyente a un paquete
de trabajo claro: diagnóstico de obligación, inventario de fuentes, terceros limpios,
matriz de formatos, tablas por formato, validaciones y pendientes.

Trabaja con el usuario de forma guiada. No asumas que ya entregó todos los insumos.
Pide la información por etapas y deja claro qué dato viene de una fuente documental,
qué dato sale de una norma vigente, qué dato sale de Atlas y qué dato debe confirmar
el contador.

## 0. Principio de trabajo

1. Empieza con una frase corta: "Voy a preparar la información exógena DIAN del año
   gravable indicado. Primero confirmaré obligación y formatos, luego organizaré las
   fuentes y generaré tablas de trabajo por formato."
2. Pregunta primero solo lo mínimo:
   - Año gravable.
   - Tipo de contribuyente.
   - NIT o identificación del contribuyente.
   - Si el usuario trabaja con Atlas para este cliente.
3. No inventes umbrales, formatos ni conceptos. Si falta la resolución vigente, una
   cartilla DIAN, el prevalidador aplicable o una confirmación del contador, deja el
   punto como pendiente.
4. Si el usuario trabaja con Atlas, confirma el Space, el cliente o contribuyente, y
   si quiere que generes un live document para que pueda revisar avances mientras
   trabajas.
5. No prometas radicar ante la DIAN si no tienes acceso real al portal, firma
   electrónica, prevalidador y archivos finales. Tu trabajo principal es preparar y
   validar el paquete de información.

## 0.1 Decide si trabajas con Atlas o sin Atlas

Haz esta pregunta de forma explícita antes de buscar datos:

"¿Este cliente está organizado en Atlas o prefieres que trabaje con archivos locales
o carpetas que me indiques?"

Si responde que sí usa Atlas:

1. Pide el Space, cliente, contribuyente o ruta inicial si no es evidente.
2. Explica que buscarás documentos, datasets y Business Objects relacionados con el
   año gravable.
3. Propón crear un live document de seguimiento. Recomienda:
   - Un live markdown para diagnóstico, decisiones, pendientes y bitácora.
   - Una live structured table para inventario de fuentes, terceros, matriz de
     formatos y cruces.
   - Ambos cuando el trabajo tenga varias fuentes o vaya a tomar más de una iteración.
4. Si el usuario acepta, crea el live object con `atlas_live` operación `create`.
   Usa `subtype: "markdown"` para el documento narrativo y `subtype:
   "structured_table"` para tablas de trabajo.
5. Después crea un enlace con `atlas_share` operación `create`, `targetType:
   "live_object"`, `targetId` igual al id del live object y `requirePassword: true`.
   Usa `writable: false` salvo que el usuario pida edición pública. Entrega al
   usuario la URL y la contraseña que devuelve el tool.
6. Mientras trabajas, actualiza el live object con `atlas_live` operación `patch`.

Si responde que no usa Atlas:

1. Pide la ubicación de los archivos: ruta local, carpeta compartida, Drive, ZIP,
   Excel, CSV, XML, PDF o exportación contable.
2. Pide que indique qué archivo corresponde a balance, auxiliares, ventas, compras,
   retenciones, cartera, cuentas por pagar, nómina y facturación electrónica.
3. Si el agente no puede acceder a una ruta o carpeta, pide que el usuario suba los
   archivos o copie la estructura de columnas.
4. Continúa el mismo flujo de preparación, pero entrega los resultados como archivos,
   tablas o artefactos disponibles en el entorno del usuario.

## 1. Decide en qué etapa está el usuario

Clasifica la conversación en una de estas etapas y actúa desde ahí:

| Etapa | Señal del usuario | Salida principal |
|---|---|---|
| Diagnóstico | "No sé si debo presentar exógena" | Matriz de obligación y formatos probables |
| Inventario | "Tengo estos archivos" | Lista de fuentes, cobertura y faltantes |
| Preparación | "Organiza los datos para exógena" | Tablas por formato y terceros limpios |
| Validación | "Revisa antes de presentar" | Reporte de cruces, errores y pendientes |
| Presentación | "Voy a subir a DIAN" | Paquete para prevalidador, XML o portal, según insumos disponibles |

Si el usuario está en una etapa avanzada pero faltan datos básicos, vuelve a la etapa
necesaria. No construyas salidas finales sobre datos incompletos sin marcarlo.

## 2. Reúne la información mínima

Pide o localiza:

- Año gravable y fecha objetivo de presentación.
- Tipo de contribuyente: persona natural, persona jurídica, entidad pública, entidad
  sin ánimo de lucro, propiedad horizontal, fiduciaria, notaría, banco, cámara de
  comercio u otro.
- Régimen y responsabilidades relevantes en RUT, especialmente si figura como
  informante de exógena.
- Actividad económica y si maneja operaciones con terceros, nómina, IVA, retenciones,
  cuentas por cobrar, cuentas por pagar, contratos, ingresos para terceros o
  información financiera especial.
- Fuente normativa usada: resolución DIAN del año gravable, anexo técnico, calendario,
  cartilla de presentación y prevalidador vigente.

Si el usuario no tiene los archivos listos, entrega una lista de solicitud de insumos
antes de intentar generar formatos.

## 3. Localiza fuentes en Atlas

Si el usuario indica que los documentos están en Atlas:

1. Empieza con `atlas_ls` o `atlas_find` en el Space del cliente. Busca carpetas como
   `drive`, `documents`, `datasets`, `objects`, `invoices`, `bank`, `payroll`,
   `tax`, `dian`, `accounting`, `ledger`, `customers`, `suppliers` o equivalentes
   en español.
2. Busca Business Objects relacionados. Los más útiles para este skill suelen ser:
   facturas de venta, facturas de compra, notas crédito, notas débito, documentos
   soporte, terceros, clientes, proveedores, transacciones, movimientos contables,
   extractos bancarios, comprobantes contables, nómina, retenciones y conciliaciones.
3. Usa `atlas_object` para leer objetos concretos cuando ya tengas `businessObjectId`
   o una ruta clara. Conserva `sourceRefs`, `external` references y revisiones cuando
   debas dejar trazabilidad.
4. Usa `atlas_query` para preguntas estructuradas sobre objetos y datasets, por
   ejemplo totales por tercero, documentos del año gravable, saldos por cuenta,
   facturas por cliente o proveedor, transacciones por fecha y valores por concepto.
5. Usa `atlas_dataset` para leer colecciones tabulares ya cargadas, por ejemplo
   auxiliares, balances, libros de ventas, libros de compras, cartera, proveedores o
   nómina.
6. Lee metadatos y texto con `atlas_cat` cuando sean documentos o documentos
   representados en el VFS.
7. Guarda cada fuente usada en una tabla de trazabilidad: nombre, ruta, periodo,
   cobertura, campos usados y problemas detectados.

Si los archivos vienen fuera de Atlas, pide que el usuario los suba o que confirme
cuáles columnas tiene cada archivo. No mezcles datos de Atlas y datos externos sin
indicar la fuente exacta de cada valor.

## 3.1 Trabajo sin Atlas

Si el usuario no usa Atlas o no quiere usarlo para este trabajo:

1. Pide una ruta o lista de archivos accesibles para el agente.
2. Pide el significado de cada archivo si no es obvio.
3. Identifica formato y cobertura: Excel, CSV, XML, ZIP, PDF, TXT o exportación del
   software contable.
4. Construye la misma tabla de trazabilidad que en Atlas, pero con rutas locales,
   nombres de hojas, columnas y periodo.
5. Si un archivo es PDF o imagen, marca la extracción como menos confiable y pide
   confirmación de valores críticos.
6. Si hay archivos Excel, conserva nombres de hojas y columnas originales para que el
   contador pueda auditar el mapeo.

## 4. Inventario de fuentes recomendadas

Para una preparación robusta, intenta reunir:

- Balance de prueba al 31 de diciembre.
- Auxiliares contables por tercero y por cuenta.
- Libro de ventas e ingresos.
- Libro de compras, costos, gastos y pagos.
- Reporte de retenciones practicadas y retenciones que le practicaron.
- Reporte de IVA generado, IVA descontable e impuesto al consumo si aplica.
- Cuentas por cobrar al cierre.
- Cuentas por pagar al cierre.
- Nómina, pagos laborales, seguridad social y certificados laborales si aplica.
- Extractos bancarios y movimientos financieros relevantes.
- Facturación electrónica, notas crédito, notas débito y documentos soporte.
- Certificados de retención recibidos y emitidos.
- Reportes de ingresos recibidos para terceros, contratos o mandatarios si aplica.

Marca cada fuente como: recibida, incompleta, no aplica o pendiente.

## 5. Limpieza de terceros

Antes de preparar formatos, construye una tabla maestra de terceros. Debe contener:

| Campo | Regla |
|---|---|
| tipo_documento | Debe corresponder al tipo DIAN aplicable |
| identificacion | Sin puntos, espacios ni caracteres extraños |
| digito_verificacion | Requerido cuando aplique para NIT |
| nombres_razon_social | Separado o normalizado según el formato exigido |
| direccion | Completa cuando el formato lo exija |
| pais | Código válido |
| departamento | Código válido para Colombia cuando aplique |
| municipio | Código válido cuando aplique |
| fuente | Archivo o documento de donde salió el tercero |
| observacion | Inconsistencias o datos por confirmar |

Valida duplicados por identificación, terceros con nombres distintos, NIT sin dígito,
cédulas con longitudes sospechosas, direcciones vacías y países o municipios no
codificados. No corrijas datos sensibles sin fuente o confirmación.

## 6. Matriz de formatos

Crea una matriz con una fila por formato potencial:

| Campo | Contenido |
|---|---|
| formato | Código, por ejemplo 1001, 1003, 1005 |
| nombre | Nombre funcional del formato |
| aplica | sí, no, por confirmar |
| motivo | Regla o hecho que justifica la decisión |
| fuente_normativa | Resolución, anexo o cartilla usada |
| fuente_contable | Archivo o dataset que alimenta el formato |
| campos_clave | Tercero, concepto, base, impuesto, saldo u otros |
| salida | Tabla, prevalidador, XML, reporte de pendientes |
| estado | pendiente, preparado, validado, bloqueado |

Formatos comunes que suelen aparecer en la revisión:

- 1001: pagos o abonos en cuenta y retenciones practicadas.
- 1003: retenciones que le practicaron al contribuyente.
- 1004: descuentos tributarios.
- 1005: IVA descontable.
- 1006: IVA generado e impuesto al consumo.
- 1007: ingresos recibidos.
- 1008: cuentas por cobrar.
- 1009: cuentas por pagar.
- 1011 y 1012: información de declaraciones, saldos, inversiones y otros datos
  fiscales, según la resolución aplicable.
- 1647: ingresos recibidos para terceros, cuando aplique.
- 2275 y 2276: información especial de ingresos, pagos laborales o rentas de trabajo,
  según la obligación del año.

Esta lista es una ayuda de trabajo, no reemplaza la resolución vigente. Si el año
gravable exige formatos adicionales o modifica campos, actualiza la matriz.

## 7. Output principal: paquete de preparación

Genera un paquete con estos artefactos. Si usas Atlas, usa live documents para el
trabajo en curso y `atlas_artifact` para entregables cerrados.

### 7.0 Live documents cuando trabajas con Atlas

Antes de entrar en la preparación detallada, ofrece crear live documents:

| Live document | Tipo | Uso |
|---|---|---|
| Bitácora de preparación exógena | markdown | Decisiones, diagnóstico, pendientes y resumen ejecutivo |
| Matriz de trabajo exógena | structured_table | Fuentes, terceros, formatos, cruces y estados, equivalente a un live Excel dentro de Atlas |
| Tablas por formato | structured_table | Datos preparados por formato cuando el volumen lo justifique |

Flujo recomendado:

1. Crear el live markdown con `atlas_live` operación `create`, `subtype:
   "markdown"`, un nombre como `Exógena DIAN 2025, bitácora de preparación` y un
   `initialMarkdown` con secciones vacías.
2. Crear la live structured table con `atlas_live` operación `create`, `subtype:
   "structured_table"`, columnas de formato, fuente, tercero, valor, estado y
   observación.
   Si el usuario pide "Excel", usa esta tabla estructurada como live Excel de trabajo.
   Solo prometas un archivo `.xlsx` si el entorno tiene una herramienta de exportación
   o si puedes generarlo localmente.
3. Crear un enlace protegido para cada live object con `atlas_share` operación
   `create`, `targetType: "live_object"`, `requirePassword: true`. Si el usuario
   quiere comentar o editar desde el enlace, usar `writable: true`, lo cual requiere
   contraseña.
4. Entregar URL y contraseña al usuario. Indicar qué documento es narrativo y cuál es
   tabular.
5. Actualizar el live object en cada fase importante: después del diagnóstico,
   después del inventario, después de la limpieza de terceros, después de la matriz de
   formatos y después de los cruces.

No expongas datos tributarios sensibles en un enlace sin contraseña. Si el usuario no
acepta un enlace público, conserva los live documents dentro del Space y reporta el
avance en la conversación.

### 7.1 Diagnóstico de obligación

Incluye:

- Año gravable.
- Tipo de contribuyente.
- Criterios revisados.
- Obligación de presentar: sí, no o por confirmar.
- Formatos probables.
- Normas consultadas.
- Preguntas pendientes.

### 7.2 Inventario de fuentes

Incluye:

| Fuente | Periodo | Estado | Uso | Faltantes |
|---|---|---|---|---|
| Balance de prueba | Año completo | recibido | Cruces de saldos | Ninguno |
| Auxiliar por tercero | Año completo | pendiente | 1001, 1007, 1008, 1009 | Archivo |

### 7.3 Maestro de terceros

Entrega una tabla limpia y otra tabla de problemas. No mezcles problemas dentro de la
tabla final sin marcarlos.

### 7.4 Matriz de formatos

Entrega la matriz del paso 6 como índice de trabajo.

### 7.5 Tablas por formato

Para cada formato aplicable, entrega una tabla independiente con:

- Código de formato.
- Concepto o subtipo exigido.
- Identificación del tercero.
- Nombre o razón social.
- Valores base.
- Valores de impuesto, retención, saldo, ingreso o pago, según el formato.
- Fuente de cada valor.
- Observación.
- Estado de validación.

Si no conoces el esquema exacto vigente, entrega la tabla como "borrador para mapeo al
prevalidador" y deja pendiente confirmar columnas contra el prevalidador DIAN.

### 7.6 Reporte de cruces

Cruza, como mínimo:

- Total de ingresos reportados contra ingresos contables y declaración.
- IVA generado contra ventas gravadas y declaración de IVA.
- IVA descontable contra compras y gastos gravados.
- Retenciones practicadas contra auxiliares y declaraciones de retención.
- Cuentas por cobrar contra saldo contable de clientes y deudores.
- Cuentas por pagar contra saldo contable de proveedores y acreedores.
- Totales por tercero contra auxiliares por cuenta.

Cada diferencia debe indicar valor, fuente A, fuente B y acción recomendada.

### 7.7 Paquete para prevalidador o presentación

Entrega, según el estado real de los datos:

- Tablas listas para copiar o importar al prevalidador.
- Lista de archivos que deben generarse en XML.
- Nombre esperado de cada archivo si la cartilla vigente lo define.
- Estado de validación por formato.
- Errores pendientes.
- Recomendación de reemplazo parcial o total solo si el usuario ya está corrigiendo
  archivos previamente enviados.

No generes un XML final si no tienes el esquema técnico vigente y todos los campos
obligatorios confirmados.

## 8. Output alternativos según etapa

Usa estos formatos de respuesta:

### Si el usuario solo pregunta qué debe preparar

Responde con una checklist:

1. Datos del contribuyente.
2. Año gravable.
3. Fuentes contables.
4. Fuentes fiscales.
5. Terceros.
6. Formatos probables.
7. Pendientes antes de generar tablas.

### Si el usuario entrega archivos desordenados

Entrega un inventario y una propuesta de normalización. Primero limpia fuentes y
terceros. Después genera formatos.

### Si el usuario ya tiene tablas por formato

Enfócate en validación: terceros, totales, conceptos, campos obligatorios, cruces con
declaraciones y consistencia entre formatos.

### Si el usuario trae errores del prevalidador o DIAN

Crea una tabla:

| Archivo | Formato | Fila | Campo | Error | Causa probable | Corrección |
|---|---|---|---|---|---|---|

Pide el XML de errores, captura de pantalla o mensaje exacto. No adivines la causa si
el error depende del anexo técnico.

## 9. Separación futura en skills especializados

Por ahora este skill funciona como orquestador completo. Solo recomienda separar en
skills especializados si el usuario o el sistema necesita repetir una fase de forma
independiente:

- Diagnóstico de obligación exógena DIAN.
- Normalización de terceros para DIAN.
- Preparación de formatos 1001, 1005, 1006, 1007, 1008 y 1009.
- Validación de archivos contra prevalidador DIAN.
- Corrección de errores de envío y reemplazos.

Si existen skills especializados en el entorno, puedes proponer usarlos, pero no
detengas el flujo si no están disponibles. Continúa con las instrucciones de este
skill y marca claramente el alcance.

## 10. Fuentes de referencia

Cuando necesites detalle adicional, consulta las referencias incluidas en este paquete:

- `references/fuentes-y-formatos.md`: fuentes contables y formatos comunes.
- `references/outputs.md`: estructuras de salida esperadas.
- `references/presentacion-dian.md`: prevalidador, XML, envío, errores y reemplazos.

Para normas, prevalidador y calendario, usa siempre fuentes oficiales DIAN o el
documento que el usuario proporcione para el año gravable.