requirement-refine

Skill: Especificación de requisitos (SRS)

Guía para crear o actualizar una Especificación de Requisitos de Software (SRS-XXX) a partir de un requerimiento en bruto: una idea, un ticket, un correo, una conversación, una transcripción de reunión, un diseño o wireframes existentes, documentación técnica, o cualquier combinación de estos — todo insumo que dé contexto para definir el alcance sirve, y no hace falta un único formato. Si el insumo incluye imágenes o gráficas, se leen y se interpretan antes de continuar. El objetivo es dejar el requerimiento en una forma estándar, sin lagunas, lista para descomponerse en historias de usuario.

Alcance de un SRS: el README.md fija el contexto de implementación de un requerimiento antes de dividirlo en trabajo: qué stack tecnológico se va a usar (y con qué respaldo), en qué repositorios se materializa y si hay un proyecto base del que partir, y los requisitos funcionales y no funcionales de alto nivel. No contiene historias de usuario, AC-XXX ni tareas — eso lo produce work-define (y, para las tareas, work-plan) a partir de este documento. Tampoco contiene modelos de datos, contratos de API ni diagramas técnicos — eso es design-define. Este skill es el paso previo, opcional pero recomendado, cuando el requerimiento llega crudo o ambiguo; si ya está claro (stack, repos y alcance conocidos, sin decisiones pendientes), se puede ir directo a /work-define.

La plantilla canónica está en assets/srs-template.md (léela antes de escribir cualquier SRS).

Mapa de referencias

Carga el archivo correspondiente cuando vayas a ejecutar la tarea; el detalle íntegro vive en references/.

Necesitas…	Archivo
Flujo paso a paso de crear y actualizar: cierre de lagunas funcionales (incluidas interfaces externas, datos y cumplimiento normativo), supuestos de funcionalidad transversal reutilizable, wireframes de UI (tipo de solución, pantallas, y su delegación a `/design-define` vía subagente), verificación y trazabilidad, riesgos, la pregunta sobre el stack (investigar vs. ya decidido) y su delegación a `/work-research`, repositorios/proyecto base, checklist, ejemplos y anti-patrones	`references/flow.md`
Guion de la entrevista: la secuencia de 17 etapas (idea → problema → objetivo de negocio → … → ready), las tres olas (Discovery / Definition / Validation), los tres roles (PO, UI/UX, Arquitecto) con su dominio y lenguaje de preguntas, la regla requisitos vs. decisiones de diseño, y la validación final con subagente sin contexto	`references/interview.md`
Detalle de RFC 2119, categorías de FR-XXX (funcionales) y NFR-XXX (ISO 25010), prioridad, estado por requisito, métodos de verificación, verificabilidad, y la Definition of Ready (DoR) del SRS	`references/quality-criteria.md`
Estructura del `README.md` de un SRS	`assets/srs-template.md`
Generación y revisión de los wireframes (`WF-XXX`): no es de este skill — se delega a `/design-define` (flujo «Wireframes» de ese skill, dueño de la plantilla y del lote de revisión); este skill resuelve tipo de solución y pantallas, invoca el subagente y registra en la sección 11 las rutas y estados devueltos	Sección «Diseño de interfaz» de `references/flow.md` (paso 4)

Referencias compartidas del plugin

Reglas transversales del catálogo; viven en la raíz del plugin, no en este skill.

${PLUGIN_ROOT}/references/language.md: Idioma — resolución obligatoria del idioma de artefactos, documentos y mensajes. Lectura obligatoria antes de ejecutar el skill.
${PLUGIN_ROOT}/references/linking.md: Enlaces — toda referencia a un archivo del proyecto se escribe como enlace que lo abre. Lectura obligatoria antes de ejecutar el skill.
${PLUGIN_ROOT}/references/requirement-criteria.md: Vocabulario de requisitos — tabla RFC 2119 y catálogos de categorías. Al redactar o clasificar un requisito o criterio.
${PLUGIN_ROOT}/references/artifacts.md: Artefactos — rutas del harness, identificadores, archivado. Al resolver una ruta o calcular un ID.
${PLUGIN_ROOT}/references/asking.md: Preguntas — mecanismo estructurado, ritmo, fallback. Antes de la primera pregunta. Este skill declara una excepción de ritmo (cierre de lagunas por tandas de hasta 3) — ver la tabla de excepciones en ese archivo.

Rutas de las referencias compartidas

${PLUGIN_ROOT} es la raíz del plugin instalado (la carpeta que contiene skills/, agents/ y references/), y toda referencia compartida de este skill se escribe como ${PLUGIN_ROOT}/references/<archivo>.md. Para resolverla: la raíz es la carpeta desde la que se cargó este archivo, dos niveles arriba (<raíz>/skills/<nombre>/SKILL.md) — el cliente anuncia esa ubicación al invocar el skill (p. ej. «Base directory for this skill: …»). Si esa ubicación no está disponible, localizar la instalación buscando el manifiesto del plugin: PLUGIN_ROOT="$(dirname "$(grep -rl '\"name\": *\"sdd-devkit\"' "$HOME/.claude/plugins" --include=plugin.json 2>/dev/null | head -1)")". En ambos casos, verificar antes de usarla que $PLUGIN_ROOT/references/language.md existe. El destino de cada enlace markdown (../../references/…) existe solo para navegar el repositorio en GitHub o en un editor: no resolverlo desde el directorio de trabajo. Nunca buscar references/ en el proyecto: un <proyecto>/references/language.md que no existe no es un archivo que falte, es una ruta mal resuelta — corregir la raíz y volver a leer, sin preguntar al usuario ni saltarse la lectura.

Resolución de idioma

Antes de ejecutar este skill, DEBES leer ${PLUGIN_ROOT}/references/language.md.

Las reglas de language.md son obligatorias y tienen prioridad para determinar el idioma de todos los artefactos, documentos y mensajes generados por este skill.

No continúes hasta haber leído y aplicado language.md.

Enlaces a archivos del proyecto: DEBES leer y aplicar ${PLUGIN_ROOT}/references/linking.md — todo archivo o carpeta existente del proyecto que este skill mencione en un artefacto, documento o mensaje (identificadores como US-XXX o WF-XXX, rutas, índices) se escribe como enlace Markdown que lo abre.

Modificador `archive` (archivar especificaciones de requisitos `SRS-XXX`)

Archiva este skill, no los de cierre. work-integrate y pr-create no archivan: siempre hay una revisión humana antes, y el usuario lo pide aquí cuando decide. Procedimiento, destinos, reglas de confirmación y contrato para el resto del catálogo: ${PLUGIN_ROOT}/references/archive.md — leerlo antes de mover nada.

Invocación	Alcance
`/requirement-refine archive SRS-XXX` · `/requirement-refine SRS-XXX archive` (uno o varios IDs; el orden es indiferente)	Los artefactos indicados, estén como estén.
`/requirement-refine archive` (sin ID)	Todos los `SRS-XXX` de `<changesPath>/requirements/` que ya estén completos; los incompletos se listan aparte con su estado y no se mueven.

Reglas que este skill aplica al archivar:

El estado no restringe, pero se informa. Antes de preguntar, componer el parte de estado: Estado del README.md y la tabla «Historias de usuario derivadas» (FR/NFR sin US derivada cuentan como incompleto). Con algo incompleto, la pregunta lo dice explícitamente y el usuario decide.
Siempre se confirma (herramienta estructurada, una sola tanda para todo el lote), mostrando origen → destino de cada carpeta y las investigaciones sueltas que quedarían huérfanas. Sin canal de respuesta, no se archiva.
Destino: <archivedPath>/requirements/<ID>-<slug>/, con <archivedPath> = specification.archivedPath de .sdd-devkit/settings.json (por defecto docs/specs/archived/) y la subcarpeta espejo de <changesPath>. git mv, guard de destino, reparación de enlaces y cierre con un commit directo docs(specs): archivar <ID>, tal como describe la referencia.
Un artefacto ya bajo <archivedPath> se informa y no se toca; un ID suelto sin archive nunca archiva.

Ubicación de archivos

Layout completo del harness, identificadores y contrato de archivado: ${PLUGIN_ROOT}/references/artifacts.md.

Lo propio de este skill:

Artefacto	Ruta
Especificación de requisitos (salida)	`<changesPath>/requirements/SRS-XXX-[nombre-corto]/README.md`
Requerimiento en bruto (entrada, conservada tal cual)	`<changesPath>/requirements/SRS-XXX-[nombre-corto]/references/`
Wireframes de pantalla (si el requerimiento tiene UI)	`wireframes/WF-XXX-[pantalla-slug].md` (documento) y `WF-XXX-[pantalla-slug].svg` (SVG hermano enlazado) — dentro de la carpeta del SRS, junto a `references/` y `assets/`, indexados en la sección 11 del `README.md`. Los crea y revisa `/design-define` vía subagente; este skill no escribe el `.md` ni el `.svg`, solo la fila de la sección 11 con la ruta y el estado devueltos. Son un recurso del SRS, no documentación de arquitectura: ni este skill ni `design-define` los ponen en `docs/architecture/`
Otros archivos de apoyo	`<changesPath>/requirements/SRS-XXX-[nombre-corto]/assets/`
Investigación de stack delegada (si se investigó)	`<changesPath>/requirements/SRS-XXX-[nombre-corto]/research/RS-XXX-[slug]/README.md` — la crea `/work-research`, este skill solo la referencia
Glosario (opcional)	`docs/glossary.md`

references/ vs. assets/. references/ guarda el insumo tal como llegó (el ticket, el correo, la transcripción de reunión, diseños, wireframes ya existentes, capturas o documentación técnica) para trazabilidad — nunca se edita ni se reescribe, solo se añade. assets/ guarda lo que este skill produce como apoyo del documento (cualquier archivo derivado distinto de los wireframes); eso sí se actualiza cuando cambia. Los wireframes no van en assets/: tienen su propia carpeta wireframes/ dentro de la carpeta del SRS (ver tabla), enlazados desde la sección 11.

Convenciones del nombre de carpeta

Reglas comunes de slug e identificadores: ${PLUGIN_ROOT}/references/artifacts.md. Lo específico del SRS:

Formato: SRS-XXX-[nombre-corto] con SRS-XXX en mayúsculas y número de 3 dígitos.
Nombre corto: minúsculas, kebab-case, sin artículos ni palabras vacías.
El secuencial es global sobre <changesPath>/requirements/ y <archivedPath>/requirements/ (un SRS archivado conserva su ID). La carpeta permanece en la ruta activa hasta que el usuario la archive con el modificador archive.
Ejemplos: SRS-001-portal-de-proveedores, SRS-004-migracion-facturacion-electronica.

Información requerida antes de redactar

Antes de crear o editar cualquier SRS, el agente debe tener clara la siguiente información. No inventar nada — si algún dato no es explícito, preguntar al usuario.

La tabla sigue el orden en que se resuelven: primero lo funcional, después la UI y al final lo técnico — salvo que una fila funcional dependa de una fila técnica puntual para cerrarse (ver la excepción en Flujo (resumen)).

Dato	Cómo obtenerlo	Si no está disponible
Requerimiento en bruto y su contexto	Cualquier insumo aportado por el usuario: descripción, ticket, correo, transcripción de reunión, diseño, wireframes, capturas o diagramas, documentación técnica existente. Todo se guarda tal cual en `references/` de la carpeta del SRS. Las imágenes y gráficas se leen y se interpretan (no se asume su contenido) antes de continuar — mismo criterio que `/work-define`	Preguntar; sin esto no hay nada que estructurar
Alcance y objetivo funcional	Del requerimiento en bruto	Preguntar; sin esto el SRS solo puede crearse en Draft
Requisitos funcionales (`FR-XXX`)	Del requerimiento en bruto	Preguntar; sin al menos un `FR-XXX` el SRS solo puede crearse en Draft
Requisitos no funcionales (`NFR-XXX`)	Del requerimiento o inferibles del dominio	Preguntar; puede quedar «No aplica» justificado
Supuestos de funcionalidad transversal reutilizable (autenticación, roles/permisos, notificaciones, auditoría, pagos, almacenamiento, búsqueda, etc.)	Inferido primero (¿ya existe/se reutiliza del proyecto base o una plataforma compartida, o está en el alcance construirla?); se pregunta solo si la inferencia es ambigua	Si es claramente reutilizada, no se pregunta — se registra el supuesto en Supuestos y dependencias y no se crea `FR-XXX`; si está en alcance, se redacta su `FR-XXX`
Interfaces externas (usuario, hardware, software, comunicaciones)	Del requerimiento, a nivel de existencia y contrato mínimo	Preguntar; omitir las subsecciones que no apliquen
Requisitos de datos (entidades, retención/privacidad, volumen)	Del requerimiento o del dominio	Preguntar; formalizarlos antes de Ready si el requerimiento maneja datos
Cumplimiento normativo (normativa aplicable y cómo se cumple)	Del requerimiento o del dominio (p. ej. datos personales, financieros, de salud)	Preguntar solo si el dominio lo exige; «No aplica» es válido
Prioridad de cada `FR-XXX`/`NFR-XXX`	Propuesta por lote al cerrar los requisitos, confirmada en una sola pregunta (ver Prioridad)	Sin asignar, el SRS no puede declararse Ready
Restricciones, supuestos y fuera de alcance	Del requerimiento o del usuario	Preguntar
¿Requiere diseño de interfaz (UI)?	Inferido del objetivo funcional y los `FR-XXX` una vez identificados; se pregunta solo si la inferencia es ambigua	Si es claramente Sí o No, no se pregunta — se registra la conclusión y se continúa; «No» cierra la sección de wireframes sin más
Tipo de solución (web, app nativa, híbrida, escritorio) y ¿responsiva? — solo si hay UI	Inferido de menciones explícitas, el actor y su contexto de uso; se pregunta solo si la inferencia es ambigua	Sin resolver, el SRS no puede declararse Ready si hay UI involucrada
Revisión de cada wireframe (aprobado / con cambios)	La hace `/design-define` dentro del subagente (lote completo, una sola pregunta por vuelta); este skill recibe el estado final y las observaciones con impacto en `FR-XXX`	Sin resolver (algún `WF-XXX` devuelto `Proposed`), el SRS no puede declararse Ready si hay UI involucrada
Verificación y trazabilidad (origen, dependencias, estado del requisito)	Por cada `FR-XXX`/`NFR-XXX`, una vez cerrados	Sin resolver, el SRS no puede declararse Ready
Método y criterio de verificación de cada requisito	Propuesto por lote (ver Métodos de verificación), confirmado en una sola pregunta; criterio redactado en términos verificables (ver Verificabilidad)	Sin método o criterio, el SRS no puede declararse Ready
Riesgos (probabilidad, impacto, mitigación)	Propuestos por lote a partir de lo ya cerrado, confirmados en una sola pregunta	Dato informativo; no bloquea `Estado: Ready` salvo que el usuario lo trate como laguna abierta
Modo de resolución del stack (investigar vs. ya decidido)	Pregunta estructurada, una vez cerrado lo funcional, la UI, la verificación y los riesgos	No aplica — se pregunta siempre en ese momento, salvo que ya se haya adelantado por la excepción de duda funcional
Stack tecnológico resuelto	Investigación delegada a `/work-research` (dominio Técnica) si el usuario pidió investigar, o respuesta directa si ya lo tiene decidido	Sin resolver, el SRS queda en Draft
Repositorios git de la implementación	Indicados por el usuario, o candidatos inferidos de submódulos/repos anidados del workspace	Sin ellos el SRS no puede declararse Ready
¿Nuevo o existente?, por cada repositorio	Pregunta estructurada explícita por cada repositorio identificado — nunca inferida del nombre	Sin resolver, el SRS no puede declararse Ready
Proyecto base (starter, scaffold, boilerplate) — solo si el repositorio es nuevo	Preguntado por cada repositorio nuevo; «No aplica» si el repositorio es existente	Preguntar; «ninguno, desde cero» es una respuesta válida para un repositorio nuevo

El único dato estrictamente obligatorio para crear el documento es tener identificado el alcance funcional del requerimiento. Si algo no es completamente resoluble con la información disponible, el SRS se crea con Estado: Draft y las lagunas documentadas en Observaciones. El estado Ready requiere todos los datos sin excepción.

Excepción de orden: si una fila funcional (FR-XXX/NFR-XXX) no se puede cerrar sin una decisión técnica puntual, esa decisión se resuelve en ese momento — no se espera a llegar a las filas de Stack/Repositorios.

Flujo (resumen)

El procedimiento completo —cómo preguntar al usuario, la pregunta inicial sobre el stack y su delegación a /work-research, la vuelta por repositorios (nuevo o existente) y proyecto base, el cierre de lagunas por tandas, los pasos de Crear y Actualizar, el checklist y los ejemplos/anti-patrones— está en references/flow.md. Síntesis:

Crear (funcional primero, técnico al final): fijar ID y carpeta SRS-XXX-[nombre-corto]/ → capturar el requerimiento en bruto y guardarlo en references/ → cerrar lo funcional con la entrevista por olas y roles de references/interview.md — Ola 1 Discovery con el PO (problema, objetivo, actores, proceso actual, resultado deseado, reglas) y Ola 2 Definition por rol (PO: FR-XXX y criterios; UX: experiencia; ARCH: calidad, restricciones, integraciones), cada tanda de un solo rol y en su lenguaje, integrando el agente las respuestas (alcance, actores, FR-XXX, NFR-XXX, reglas de negocio, interfaces externas, requisitos de datos, cumplimiento normativo), inferir primero si alguna capacidad transversal común (autenticación, roles, notificaciones, etc.) ya existe o se reutiliza en vez de crear un FR-XXX para ella, preguntando solo si queda duda, y al final del cierre asignar prioridad a cada FR-XXX/NFR-XXX por lote → si el requerimiento tiene UI propia (inferido, o preguntado solo si es ambiguo), inferir el tipo de solución (web, nativa, híbrida, responsiva), identificar las pantallas y delegar los wireframes a /design-define mediante subagente (genera wireframes/WF-XXX-[pantalla-slug].md + .svg en la carpeta del SRS, presenta el lote y lo revisa con el usuario con una sola pregunta por vuelta), registrar en la sección 11 las rutas y estados devueltos y trasladar a los FR-XXX afectados las observaciones reportadas → completar verificación y trazabilidad de cada requisito (origen, dependencias, estado) y asignar método y criterio de verificación por lote → identificar riesgos y presentarlos como lote → recién entonces resolver lo técnico: preguntar si se investiga el stack o ya está decidido, resolverlo (delegando a /work-research mediante subagente, o registrando la decisión directa del usuario), identificar repositorios y, por cada uno, si es nuevo o existente y, si es nuevo, si hay proyecto base → redactar el README.md con la plantilla (Introducción, Descripción general, Stack tecnológico, Repositorios, FR-XXX, NFR-XXX, Reglas de negocio, Interfaces externas, Requisitos de datos, Cumplimiento normativo, Diseño de interfaz, Verificación y trazabilidad, Riesgos, Enlaces y archivos de apoyo, Observaciones) → Ola 3 Validation sobre el documento redactado: análisis de gaps, revisión cruzada PO+UX+ARCH y validación con un subagente sin el contexto de la sesión (solo lee la carpeta del SRS) que confirme que basta para implementar sin repreguntar — hallazgos a tandas por rol u Observaciones → glosario si aplica → cierre. Excepción: si una laguna funcional no se puede cerrar sin una decisión técnica puntual, esa pieza se adelanta y se pregunta dentro de la misma tanda funcional, sin esperar al bloque técnico.
Actualizar: identificar y leer el README.md → aplicar cambios conservando siempre los ids FR-XXX/NFR-XXX/BR-XX existentes (son inmutables: los nuevos toman el siguiente libre) → revalidar → confirmar.
Cierre: si queda Draft, cerrar lagunas con preguntas estructuradas (tandas de hasta 3, encadenando tantas como haga falta); si queda Ready, ofrecer /work-define para descomponer el SRS en historias de usuario — nunca crear la US directamente desde este skill. Si algún repositorio de la sección 4 no tiene el harness (AGENTS.md/.sdd-devkit/settings.json), agregar /arch-init como opción adicional en la misma pregunta.

Las modalidades RFC 2119 y las categorías de FR-XXX/NFR-XXX detalladas están en references/quality-criteria.md.

Criterios para `Estado: Ready` (resumen)

Promover a Ready solo si se cumplen todos; el detalle de cada criterio está en references/quality-criteria.md.

Stack tecnológico resuelto: investigado (con RS-XXX enlazado) o decidido explícitamente por el usuario, sin alternativas abiertas.
Repositorios identificados y, por cada uno, su tipo resuelto (nuevo o existente) y el proyecto base resuelto cuando aplica (uno concreto, «desde cero» si es nuevo, o «No aplica» si es existente).
Sección Requisitos funcionales completa: al menos un FR-XXX con categoría, prioridad, estado y enunciado RFC 2119 en MAYÚSCULAS.
Requisitos no funcionales revisados y priorizados (con entradas o «No aplica» justificado).
Interfaces externas revisadas (usuario, hardware, software, comunicaciones); «No aplica» si no corresponde.
Requisitos de datos formalizados si el requerimiento maneja datos.
Cumplimiento normativo trazado si el dominio lo exige; «No aplica» si no corresponde.
Diseño de interfaz: si el requerimiento tiene UI propia, el tipo de solución (web, nativa, híbrida, escritorio) y si debe ser responsiva están definidos, y cada pantalla tiene su wireframe revisado por el usuario (aprobado, o con los cambios ya trasladados al SRS); «No aplica» si no hay UI.
Verificación y trazabilidad completa: todo FR-XXX/NFR-XXX con método y criterio de verificación redactado en términos comprobables.
Riesgos identificados, con probabilidad, impacto y mitigación.
Alcance y fuera de alcance declarados sin ambigüedad.
Observaciones sin aclaraciones ni decisiones pendientes abiertas.
Ola 3 superada: gaps y revisión cruzada resueltos, y la validación del subagente sin contexto sin hallazgos pendientes (ver references/interview.md).

Si falta cualquiera, mantener Estado: Draft con las lagunas documentadas en Observaciones.

Mensaje al usuario

Solo resultados y lo que el usuario debe saber o decidir. No incluir razonamiento interno ni narración del trabajo en curso («leí el requerimiento», «creé el archivo»). Si hay pendientes, listarlos agrupados por sección (Stack, Repositorios, FR-XXX, NFR-XXX, Interfaces externas, Requisitos de datos, Cumplimiento normativo, Wireframes, Verificación y trazabilidad, Riesgos). Los wireframes se generan todos (SVG enlazado, no pegado como código) antes de mostrarlos, y se presentan juntos, en un solo mensaje: WF-XXX y nombre de cada pantalla con el enlace a su documento (wireframes/WF-XXX-[pantalla-slug].md en la carpeta del SRS) y a su SVG (…/WF-XXX-[pantalla-slug].svg) para revisarla con facilidad — nunca uno por turno. La prioridad, el método de verificación y los riesgos también se proponen como lote y se confirman en una sola pregunta cada uno — nunca requisito por requisito. Al llegar a Ready, ofrecer explícitamente /work-define como siguiente paso — nunca crear la historia de usuario desde aquí. Si algún repositorio de la sección 4 todavía no tiene el harness (AGENTS.md/.sdd-devkit/settings.json), agregar /arch-init como opción adicional en esa misma pregunta.