Contextualizar negocio (brownfield)

Goal

Responder, en lenguaje de negocio y con evidencia, qué hace hoy el sistema, bajo qué reglas y cómo se llama cada cosa. En un brownfield no hay PRD ni backlog: lo que el sistema hace está en el código, y muchas de sus reglas no están escritas en ningún otro lado.

Esta skill cubre el contexto funcional (capas 3 y 4). El contexto técnico lo produce el ARCH con contextualizar-repo.

Esta skill no modifica código ni propone funcionalidades nuevas. Levanta información, documenta, pregunta y se detiene.

Principios

1. Lenguaje de negocio. Cada capacidad y cada regla se escribe para que la entienda un PO; la evidencia técnica va al lado, no en lugar de la explicación.
2. Nada sin evidencia. Cada capacidad y cada regla lleva de dónde sale (endpoint, pantalla, prueba o archivo:línea), o queda NO VERIFICADO.
3. Lo que el código hace no es necesariamente lo que el negocio quiere. Si una regla parece un error o es ambigua, no se corrige ni se interpreta: se convierte en pregunta para el negocio.

Input

• docs/contexto/ARQUITECTURA.md del ARCH (o el aviso CONTEXTO TÉCNICO LISTO): dice dónde mirar. Si no existe, preguntar si el ARCH va a correr primero; seguir sin él solo si el humano lo confirma, y avisar que el levantamiento será más lento y menos preciso.
• Documentación de usuario existente, si la hay.
• Opcional: la aplicación corriendo, para recorrer pantallas.

Workflow

1. Fuentes

Recorrer, en este orden, lo que describe el comportamiento del sistema:

1. La interfaz pública: endpoints de la API, pantallas, comandos.
2. Las pruebas existentes: describen comportamiento esperado con ejemplos concretos.
3. La configuración: opciones y flags que cambian el comportamiento para el usuario.
4. La documentación de usuario.
5. El código, para confirmar y para encontrar lo que no aparece en las anteriores.

2. Mapa de capacidades (capa 3)

Agrupar por capacidad de negocio, no por archivo ni por endpoint. Por cada capacidad:

• qué permite hacer, en una frase de negocio;
• quién la usa (actor);
• evidencia (endpoint, pantalla, prueba o archivo:línea);
• estado: activa · detrás de una opción de configuración · obsoleta.

Usar assets/capacidades-template.md.

3. Reglas de negocio escondidas (capa 3)

Buscar en el código validaciones, límites, transformaciones, permisos y valores por defecto que afectan lo que el usuario puede hacer. Por cada regla:

• enunciado en lenguaje de negocio ("un documento no puede nacer con más de 100.000 caracteres");
• evidencia archivo:línea;
• si está documentada en algún otro lugar (sí / no);
• si es ambigua o parece un error: pregunta para el negocio, sin resolverla.

4. Glosario (capa 4)

Construir docs/contexto/GLOSARIO.md con assets/glosario-template.md:

1. Juntar los términos del dominio que aparecen en la interfaz, la API y el código.
2. Por cada término: definición de negocio, sinónimos y el nombre que usa el código si es distinto, y el formato de su identificador si tiene uno.
3. La columna "Dónde vive" la completa el ARCH: enviarle GLOSARIO: TÉRMINOS NUEVOS: <ruta> — <cantidad de términos>. Si no hay ARCH en la sesión, completarla con evidencia y marcarla pendiente de revisión técnica.
4. Si un mismo término significa cosas distintas en lugares distintos, se registra como conflicto, no se elige una definición.

5. Escribir

Si AGENTS.md ya apunta a estos archivos (lo deja el ARCH), no se toca. Si no, se propone agregar el enlace.

6. Autovalidación

• Volver a abrir cada evidencia citada y confirmar que respalda lo que se afirma.
• Confirmar que ninguna capacidad ni regla está escrita como si fuera nueva o propuesta.
• Confirmar que cada término del glosario tiene definición de negocio.

7. Gate humano

Presentar el resumen y las preguntas para el negocio, idealmente a un PO. Esperar aprobación explícita antes de dar el contexto funcional por cerrado.

Coordinación con el ARCH

• Esperar CONTEXTO TÉCNICO LISTO antes de empezar (salvo que el humano diga lo contrario).
• Enviar GLOSARIO: TÉRMINOS NUEVOS cuando haya términos sin ubicación en el código.
• Al recibir GLOSARIO COMPLETO, revisar que cada ubicación corresponda a la definición de negocio; si no, devolver la diferencia concreta.
• Máximo dos vueltas por el mismo desacuerdo; después decide el humano.

Constraints

• No modifica código ni documentación técnica del ARCH.
• No propone funcionalidades nuevas: documenta las existentes.
• No resuelve reglas ambiguas: las pregunta.
• No da el contexto funcional por cerrado sin aprobación humana.