Especificaciones — MVP 1

Estado: Borrador · Última actualización: 2026-08-24 Deriva de: casos de uso, reglas de negocio, requerimientos funcionales · Decisiones: DEC-059 (resuelve PA-002)

1. Qué es esta carpeta

Las especificaciones de desarrollo del MVP 1, agrupadas por historias de usuario (HU-###). Cada HU aterriza un caso de uso o un comportamiento transversal en algo construible por un developer: enunciado, alcance, comportamiento, reglas, permisos, datos funcionales y criterios de aceptación verificables (CA-###, estilo Gherkin).

Lo que estas specs NO incluyen (fuera de alcance por decisión, no por olvido):

Diseño técnico: modelo de datos, esquema de tablas, contratos de API, arquitectura.
Plan / backlog priorizado: orden, estimación y secuencia de construcción.
Contratos de integración detallados: las integraciones con sistemas externos

(Argos Operaciones, JWT de Flagare, notifications.flagare/SSE, S3, Bedrock/IA, GitLab) quedan documentadas a nivel funcional —qué se toca y cuándo—, no diseñadas. El developer sabe implementarlas; el contrato fino se cierra cuando se respondan las preguntas abiertas correspondientes.

2. Cómo leer una HU

Cada historia sigue esta plantilla. Las secciones que no apliquen se omiten.

Sección	Qué contiene
Cabecera de trazabilidad	Épica · Deriva de (CU o Transversal) · Cubre (RF) · Reglas (RN) · Decisiones (DEC) · Estado
Historia	`Como <rol>, quiero <capacidad>, para <valor>`
Objetivo / valor	Por qué existe, en una o dos líneas
Alcance	Qué entra y qué queda fuera de esta HU
Actores y permisos	Qué puede hacer cada rol involucrado
Precondiciones	Estado necesario antes de ejecutar
Comportamiento funcional	Flujo principal, alternativos y de error, en prosa concisa
Datos y campos	Campos funcionales (qué se captura / precarga), sin esquema
Reglas de negocio aplicables	Las RN que gobiernan, reenunciadas en su efecto
Estados y transiciones	Referencia a la máquina de estados cuando aplica
Integraciones	Sistemas externos que se tocan, a nivel funcional (documentado, no diseñado)
Eventos que emite	Eventos de dominio disparados
Criterios de aceptación	`CA-###` en Gherkin `Dado / Cuando / Entonces`, verificables
Dependencias y bloqueos	`PA-###` que la condicionan y otras `HU-###` relacionadas
Casos borde / notas	Lo que no cabe arriba y no debe perderse

3. Convenciones de identificadores

Prefijo	Artefacto	Ejemplo
`HU-###`	Historia de usuario (lleva su especificación)	`HU-016`
`CA-###`	Criterio de aceptación	`CA-138`

Los IDs son estables: no se reutilizan ni se renumeran. Los CA-### se numeran por bandas de épica; que haya saltos entre bandas es esperado, no un hueco.

4. Épicas = sprints

Las épicas se organizan como sprints entregables: cada sprint es una rebanada vertical que deja el producto usable de punta a punta hasta esa fase de la cadena de valor (DEC-062). El plan de negocio derivado está en ../04-plan/plan-al-negocio.md y el desglose técnico en tareas en ../04-plan/backlog-desarrollo.md.

El bloque funcional A–M de los requerimientos funcionales no se pierde: se conserva como etiqueta en la cabecera de cada HU, para no romper la trazabilidad hacia los RF (que se agrupan por bloque).

Sprint · Épica	Archivo	Demo al cierre	Historias	Bloques
S1 · Plataforma y proyectos	s1-plataforma-y-proyectos.md	Entrar con cuenta Flagare, importar un proyecto de Operaciones, administrar equipo y ciclo de vida, todo auditado	HU-001–005, HU-027	A, B, M
S2 · AI Workspace — casos de uso	s2-ai-workspace-casos-de-uso.md	Pegar requerimiento → IA propone casos → crear/editar a mano → revisar → congelar y versionar	HU-006–011, HU-026	C, D, L
S3 · Plan de pruebas y ambientes	s3-plan-y-ambientes.md	Generar plan y escenarios con criterios, aprobarlo, registrar y preparar el ambiente, notificaciones activas	HU-012–014, HU-025	E, F, K
S4 · Ejecución guiada y evidencia	s4-ejecucion-y-evidencia.md	Abrir ciclo, ejecutar escenarios paso a paso (Pass/Fail/Blocked), capturar evidencia	HU-015–017, HU-019	G, H
S5 · Cierre: bugs, reportes y portal cliente	s5-cierre-bugs-reportes-cliente.md	Bug hacia Operaciones, bloqueos, reejecución, cierre con reporte, dashboard y vista del Client	HU-018, HU-020–024	G, I, J

Los IDs de HU no se renumeran: HU-018 (reejecución) vive en S5 porque depende de que exista el flujo de bugs/corrección, aunque su bloque funcional de origen sea el G.

5. Inventario de historias y trazabilidad

Cada CU del MVP tiene al menos una HU; los bloques transversales (sin CU de actor) también quedan cubiertos.

Ordenado por HU (los IDs no se renumeran). La columna Sprint dice cuándo se construye; la columna Bloque conserva el bloque funcional A–M de origen.

HU	Título	Sprint	Bloque	Deriva de	Cubre RF	Reglas RN
HU-001	Autenticarse con el JWT de Flagare	S1	A	Transversal	RF-001–003	RN-008
HU-002	Gestionar miembros y roles del proyecto	S1	A	CU-002	RF-004–008, RF-018	RN-001–007
HU-003	Importar un proyecto desde Argos Operaciones	S1	B	CU-001	RF-009–012, RF-017	RN-014, RN-015
HU-004	Sincronizar y degradar con Argos Operaciones	S1	B	Transversal	RF-013, RF-014	RN-016, RN-017
HU-005	Archivar y reactivar un proyecto	S1	B	Transversal	RF-016, RF-138, RF-141	RN-005
HU-006	Cargar un requerimiento	S2	C	CU-003	RF-019–024	RN-018, RN-019
HU-007	Analizar un requerimiento con IA	S2	D	CU-004	RF-025–028, RF-124, RF-126, RF-127, RF-130	RN-064, RN-066, RN-068
HU-008	Generar casos de uso con IA	S2	D	CU-005	RF-029, RF-031, RF-032, RF-124, RF-126	RN-020, RN-021, RN-064
HU-009	Crear un caso de uso manualmente	S2	D	CU-006	RF-030–032	RN-020, RN-021, RN-065
HU-010	Revisar y congelar un caso de uso	S2	D	CU-007	RF-033–037, RF-041, RF-042	RN-009, RN-022, RN-025
HU-011	Crear una versión nueva de un caso congelado	S2	D	CU-008	RF-038–040, RF-042	RN-023, RN-024, RN-037
HU-012	Generar el plan de pruebas y sus escenarios	S3	E	CU-009	RF-043–050, RF-054–056, RF-139	RN-031, RN-032, RN-036
HU-013	Aprobar el plan de pruebas	S3	E	CU-010	RF-051–053	RN-033–035
HU-014	Registrar y preparar un ambiente de prueba	S3	F	CU-011	RF-057–067	RN-012, RN-026–030
HU-015	Abrir un ciclo de QA	S4	G	CU-012	RF-066–069	RN-028, RN-029
HU-016	Ejecutar un escenario de forma guiada	S4	G	CU-013	RF-070–076, RF-079, RF-083–088	RN-013, RN-038, RN-040, RN-042, RN-043, RN-046, RN-047
HU-017	Ejecutar un escenario fuera de ciclo	S4	G	CU-013 (A1)	RF-070, RF-071	RN-038, RN-062, RN-080
HU-018	Reejecutar tras una corrección	S5	G	CU-016	RF-079, RF-080, RF-098, RF-099	RN-040, RN-041, RN-044, RN-055
HU-019	Capturar y conservar evidencia	S4	H	Transversal	RF-089–091	RN-010, RN-046–050
HU-020	Registrar un bug desde un fallo	S5	I	CU-014	RF-077, RF-092–100	RN-051–054, RN-056, RN-083
HU-021	Registrar y resolver un bloqueo	S5	I	CU-015	RF-078, RF-101–105, RF-140	RN-039, RN-057, RN-058
HU-022	Cerrar el ciclo y emitir el reporte de calidad	S5	J	CU-017	RF-081, RF-082, RF-106–113	RN-045, RN-059, RN-060, RN-062, RN-063
HU-023	Consultar el dashboard de cobertura y avance	S5	J	Transversal	RF-106–112, RF-115, RF-116	RN-059, RN-060, RN-062
HU-024	Consultar el reporte agregado como Client	S5	J	CU-018	RF-006, RF-015, RF-114	RN-004, RN-006, RN-061
HU-025	Emitir eventos de dominio y notificar	S3	K	Transversal	RF-117–123	RN-069–072
HU-026	Orquestar las operaciones de IA	S2	L	Transversal	RF-125, RF-128–130	RN-064–068
HU-027	Registrar auditoría e integridad referencial	S1	M	Transversal	RF-131–137	RN-011, RN-073–076

6. Estado de cobertura

18/18 casos de uso con al menos una HU.
Bloques transversales (autenticación, sincronización, evidencia, eventos, IA,

auditoría) cubiertos por HU propias, aunque no deriven de un CU de actor.

Quedan fuera del MVP los ítems marcados [Fase 2]+ en los requerimientos

(Playwright, grabación de pantalla, RAG/pgvector, ingesta binaria, etc.).