Tu primer requerimiento

No hace falta memorizar comandos. Se escribe lo que se quiere en el chat y kbspec decide la fase, corre los comandos y deja cada cosa escrita en el expediente: una carpeta del repositorio de documentación con un documento por fase. Lo que decide una persona —aprobar un documento, autorizar el plan, dar por buena una prueba— lo escribe ella; el agente no lo puede hacer por ella.

Antes de empezar: la máquina instalada (Instalación), la aplicación en el inventario con su ficha (El inventario y las fichas) y, si el cambio tiene pantallas, la base E2E en LISTO (Configurar las pruebas E2E).

El ejemplo

El área de Riesgo Operativo pide:

«En la bandeja de incidentes, poder exportar a Excel lo que estoy viendo, con los filtros que apliqué. Hoy copiamos a mano. Solo lo pueden exportar los analistas y los supervisores; el rol Consulta no.»

Ticket REQ-123456, aplicación OPERACIONES, módulo RO: un front Angular (OPS-RO-WEB) y su API .NET (OPS-RO-API). Tamaño M: varias tareas, dos componentes.

Fase	Documento	Quién decide
1 · Captura	`01-solicitud.md`	la persona aprueba el 01
2 · Requerimiento	`02-requerimiento.md`	la persona aprueba el 02
3 · Análisis	`03-analisis-tecnico.md`	la persona aprueba el 03
4 · Plan	`04-plan-tareas.md`	la persona autoriza el plan
5 · Implementación	código y `05-bitacora.md`	la persona revisa cada tarea
6 · Pruebas	`06-plan-pruebas.md`	la persona aprueba el plan de pruebas
7 · Validación del usuario	`07-resultados-pruebas.md`	el usuario de negocio
8 · PR y entrega	`08-entrega.md` · `09-manual-usuario.md`	el revisor del PR

1. Captura: de lo que pidió el negocio a la solicitud

En el chat (en Copilot, el agente KB; en Claude Code, /kb la primera vez):

REQ-123456 — exportar a Excel la bandeja de incidentes de OPERACIONES con los filtros aplicados. Te pego lo que mandó el área, y te adjunto el Excel que arman hoy a mano. Lo técnico que ya sé: imitá el export de la bandeja de controles, que ya existe; el archivo se genera en el servidor.

kbspec crea el expediente y abre la sesión:

kb init REQ-123456 "Exportar a Excel la bandeja de incidentes filtrada" \
    --tamano M --aplicacion OPERACIONES --modulo RO
kb insumo excel-actual.xlsx --de "Riesgo Operativo"

Qué queda en el 01: lo que pidió el negocio literal, el Excel como insumo, las «Indicaciones técnicas adelantadas» (imitar el export de controles, generar en el servidor) —el análisis las lee primero— y las preguntas abiertas. En este caso pregunta:

¿cuántas filas puede tener la bandeja en el peor caso? (decide si el archivo se arma en memoria o se pagina);
¿qué columnas lleva el Excel: las de la pantalla o las del Excel de hoy?;
¿el supervisor exporta todas las áreas o solo la suya?

Una pregunta abierta bloquea el paso de fase hasta que alguien la responde. Las respondés en el chat como hablás; quedan escritas con quién respondió. Revisás el resumen y escribís:

aprobado 01

2. Requerimiento: qué tiene que pasar, en lenguaje de negocio

kbspec comprueba que alcanza la información (kb listo --fase 2) y redacta el 02, sin nombres de clases ni tablas:

RF-01 — Exportar la bandeja filtrada. Dado que un analista filtró la bandeja por estado «Abierto» y área «Tarjetas», cuando elige «Exportar a Excel», entonces descarga un archivo con exactamente las filas que ve, en el mismo orden.
RF-02 — Solo quien puede. Dado un usuario con rol Consulta, cuando abre la bandeja, entonces no ve la opción de exportar.
RN-01 — Qué se exporta. Las filas = las que cumplen los filtros activos, sin la paginación. Ejemplo: 1.240 incidentes, filtro «Abierto» → 312 filas en pantalla en 13 páginas de 25 → el Excel trae las 312.

La tabla de Actores dice qué rol hace cada cosa; es lo que después elige con qué usuario de prueba corre cada E2E. Antes de aprobarlo, kbspec puede ofrecer un segundo pase (pre-mortem, inversión) que suele encontrar el caso que faltaba: aquí, ¿qué pasa si no hay ninguna fila? El 01 y el 02 se aprueban juntos —son el alcance— y los leés como prefieras: la vista de revisión que arma kbspec (kb revision alcance: una página con lo que requiere tu decisión primero, quién hace qué y las reglas con su origen), los documentos, o ambos. Escribís:

aprobado alcance

kbspec firma cada documento con la identidad de tu sesión —nadie escribe un nombre— y la huella de esa versión. El análisis, el plan y los casos de prueba se aprueban juntos más adelante: la solución.

3. Análisis: dónde y cómo, sobre el código real

Lo primero que corre el agente:

kb contexto OPS-RO-WEB

  ✓ arquitectura     vigente · confirmada hace 40 d  (3.100 tok)
  ✓ índice           generado del código · vigente  (1.900 tok)
  ✓ LEER — 2 ficha(s) vigente(s). No explores el repositorio.

No recorre el repositorio: lee la ficha, el índice y los estándares del tipo. Para lo que no está ahí, consulta el mapa en vez de abrir carpetas:

kb mapa buscar OPERACIONES "exportar bandeja de controles a excel"
kb mapa vecindario OPERACIONES controles-export.service.ts
kb contratos buscar OPS-RO-API incidentes bandeja

Qué queda en el 03: la matriz de impacto (qué archivos se tocan en cada componente y por qué), el modelo de datos si cambia, las decisiones (ADR-01 — el archivo se genera en el servidor: con 312 filas o con 40.000 se comporta igual y no depende del navegador) y los riesgos. Si la implementación se aparta después, el 03 se actualiza en el momento.

aprobado 03

4. Plan de tareas

El 04 divide el trabajo en tareas chicas, cada una con su componente, sus archivos y su criterio de terminado:

Tarea	Componente	Qué
T-01	OPS-RO-API	Consulta que devuelve la bandeja filtrada sin paginar
T-02	OPS-RO-API	Servicio que arma el `.xlsx` y endpoint de descarga, con el permiso
T-03	OPS-RO-WEB	Botón «Exportar a Excel», visible según el rol
T-04	OPS-RO-WEB	Pruebas unitarias del botón y del servicio

kbspec crea los work items en Azure DevOps (o issues en GitHub) y dice cuántas ramas van a existir: kb alcance → dos repositorios, dos ramas Feature/REQ-123456, creadas desde el pase de negocio. Antes de implementar:

kb listo

  ✓ LISTO — 02 y 03 aprobados, sin preguntas abiertas, plan con 4 tareas

Autorizás el plan:

aprobado 04

(o «aprobado lote 300», si querés que las tareas que no dependen entre sí corran en paralelo, con ese tope de créditos).

5. Implementación: una tarea a la vez

dale con la tarea 1

El agente arranca la tarea —la rama lista en cada repositorio, el work item en proceso— y recibe el resumen de esa tarea: su parte del 04, las secciones del 03 que la nombran, los comandos de la app y dónde va cada cosa. Para un caso nuevo, la receta en vez de leer carpetas:

kb mapa receta OPERACIONES consulta OPS-RO-API

  Se crean (imitando cada uno):
    consulta     src/Ops.Application/Incidentes/Queries/<Nombre>Query.cs
                 ↳ imitar: src/Ops.Application/Controles/Queries/GetBandejaControlesQuery.cs
    manejador    src/Ops.Application/Incidentes/Queries/<Nombre>QueryHandler.cs
  Se extienden (no se crean: el caso se engancha acá):
    controlador  src/Ops.Api/Controllers/IncidentesController.cs

Escribe el código, compila, corre las pruebas de la app, anota en la bitácora (05) qué hizo y qué decidió, y hace el commit REQ-123456 T-01: … en la rama del ticket. Revisás y seguís con la próxima. Si algo se aparta del plan, queda como desviación en el 05 y el 03 se corrige.

6. Pruebas

El plan de pruebas (06) sale del 02: un caso por condición —el camino feliz, el rol que no puede, la bandeja vacía, el ejemplo de RN-01— en lenguaje de negocio. Antes de escribir las E2E, kbspec arma el brief (qué se prueba, con qué usuario, en qué pantalla y qué se afirma) y lo aprobás. Si las pantallas son nuevas, kb pruebas grabar deja el recorrido.

kb pruebas            # compila, lint, unitarias y E2E; cada salida queda como evidencia

Las evidencias (E01 compila, E03 unitarias, E04 E2E con capturas…) quedan en el expediente con su archivo: sin archivo, la casilla del PR no se marca.

7. Validación del usuario

kb plan-uat           # una página que el usuario abre en el navegador, sin instalar nada

El analista de Riesgo Operativo prueba en staging con sus datos, marca cada caso y devuelve el archivo. kb uat importar <archivo> lo vuelca al 07, separando defectos (se corrigen en una ronda) de pedidos nuevos (van a otro requerimiento).

8. Pull Request y entrega

kb pr                 # arma el PR desde el expediente: work item, revisores, evidencias

La descripción sale del expediente y la plantilla del equipo. Los comentarios del revisor se atienden desde kbspec (kb pr hilos). Aprobado y desplegado, /kb-entrega escribe el 08 (qué se entregó) y el 09 (el manual para el usuario), y actualiza la base de conocimiento de la app —la ficha, el glosario, el índice con kb mapa construir— para que el próximo requerimiento sobre OPERACIONES arranque leyendo y no explorando.

kb publicar           # el expediente al repositorio de documentación
kb cerrar             # cierra la sesión; el expediente queda

Mientras tanto

kb estado             # en qué fase está, qué falta, preguntas abiertas, evidencias
kb abrir REQ-123456   # retomarlo otro día, en otra máquina, otra persona
kb tokens             # cuánto consumió cada fase, y dónde