Agents-On-Rails/skills

/aor-req — Redacción de Requisitos

Redacta UN, PR y SR siguiendo los patrones EARS-12, los atributos de calidad INCOSE C1-C9 y la sintaxis canónica de referencias cruzadas. La salida está en markdown.

Nota sobre habilidades vs. agentes. El paquete AOR contiene habilidades en .claude/skills/aor-*/SKILL.md (invocables directamente, como esta) y agentes SME en .claude/agents/aor-sme-*.md (prompts de sistema de sub-agente generados solo por aor-review / aor-review-adhoc). NO invoque un agente como habilidad — fallará con "skill not found".

Disciplina de funcionamiento

Aplicar en todo momento. Indique cada una al inicio para que el usuario lo vea.

• Modo (declarado al inicio): preguntar si esta es una sesión exploratoria (requisito único, conversacional, sin archivos) o una sesión de documento (especificación completa, archivos escritos). Usar exploratorio por defecto si el alcance llega como texto en línea sin una ruta de archivo, y documento en caso contrario. El modo controla si los Pasos 5–7 escriben en disco.
• Reconocimiento de invocación: la primera respuesta de la habilidad indica "Ejecutando como aor-req en modo . Archivos escritos en a menos que indique lo contrario." Elimina la ambigüedad de "¿realmente se ejecutó la habilidad?".
• Disciplina de preguntas y respuestas: hacer una pregunta de aclaración a la vez. Esperar la respuesta del usuario antes de hacer la siguiente. No acumular preguntas. Una sola llamada AskUserQuestion que presente una decisión con múltiples alternativas (por ejemplo, un menú de opción múltiple) es una pregunta; presentar dos decisiones no relacionadas en una sola llamada es acumular.
• Revelación de fallos: si algún paso prescrito no se puede completar (escritura de archivo bloqueada, invocación de sub-agente fallida, archivo de referencia no disponible, finalización parcial, tiempo de espera agotado, permiso denegado), indicarlo en el chat. Después de revelarlo, detenerse y preguntar si reintentar, retroceder a emulación manual revelada, o abortar — no continuar en silencio. Se permite un reintento para fallos claramente transitorios (por ejemplo, tiempo de espera de red) antes de la revelación obligatoria.

Flujo de trabajo

Paso 1: Establecer alcance

Si el usuario pasó texto de alcance o una ruta de archivo, usarlo. De lo contrario, preguntar mediante AskUserQuestion: "¿Qué características o cambios deben especificarse?"

Distinguir texto de alcance de una ruta de archivo (REQ-B): tratar la entrada como ruta si se cumple alguna de: (a) contiene / o \, (b) termina en .md / .txt / .xlsx / .csv / .docx, o (c) se resuelve a un archivo existente en disco mediante Read(). De lo contrario, tratarlo como texto de alcance — incluyendo descripciones de varias palabras como "sistema de reserva de citas de pacientes".

Desempate: si solo la regla (c) coincide (sin / o \, sin extensión reconocida, pero Read() resuelve) Y la entrada es una sola palabra, confirmar con el usuario antes de tratar como ruta: "Veo que existe un archivo llamado <input>. ¿Se refería a ese archivo, o es una descripción de alcance?"

Para entradas provenientes de Excel, se espera que el LLM anfitrión haya transcrito las filas a un búfer de markdown en funcionamiento antes de que esta habilidad se ejecute (el paquete no analiza Excel directamente).

Paso 1a: Clasificar el nivel

Si está en modo exploratorio, preguntar:

"¿Es esto una Necesidad de Usuario (UN), un Requisito de Producto (PR) o un Requisito de Software (SR)?"

Saltar pasos no utilizados una vez que se conoce el nivel: la revisión de UN necesita el Paso 2; la revisión de PR necesita el Paso 3 + Puerta de Eco; la revisión de SR necesita los Pasos 4–6.

Entrada multinivel en modo exploratorio: si el usuario proporciona un conjunto UN+PR+SR (o cualquier combinación de múltiples niveles) en lugar de seleccionar uno, tratarlo como una revisión multinivel — recorrer los Pasos 2–4 a través de los niveles proporcionados en orden, pero mantener la disciplina de escritura de archivos exploratoria (sin escrituras automáticas en disco; presentar hallazgos en línea).

Si está en modo documento, por defecto recorrer los tres niveles (UN → PR → SR) a través de los Pasos 2–4 a menos que el usuario especifique lo contrario.

Paso 2: Redactar Necesidades de Usuario (UN-NNN)

Para cada necesidad distinta de un interesado, redactar una UN. Reglas:

• Agnóstica tecnológicamente, expresada desde la perspectiva del interesado
• Narrativa simple (NO sintaxis EARS)
• Incluir declaración del problema (2-3 oraciones) + declaración de necesidad
• Etiquetar una persona mediante traces_to::UN->Persona [<id-persona>]
• Prioridad: Crítica | Alta | Media | Baja

Consultar templates.md para el formato.

Paso 3: Redactar Requisitos de Producto (PR-NNN)

Para cada UN, derivar PRs:

• Agnósticos tecnológicamente, medibles, objetivos
• Sintaxis EARS (consultar ears-guide.md para los 12 patrones)
• Cada PR traza hacia atrás: derived_from::PR->UN [UN-NNN]
• Cada PR traza hacia adelante: traces_to::PR->SR [SR-NNN]
• Cada PR de camino feliz debe tener al menos un compañero If/Then (No deseado) PR
• La misma regla de compañero If/Then se aplica a nivel SR en el Paso 4 — cada SR de camino feliz debe tener un compañero SR If/Then que especifique la recuperación a nivel de implementación
• Cada PR EARS-N (negativo/shall not) debe tener al menos un compañero PR positivo (Ubicuo, Dirigido por Eventos o Dirigido por Estados) que especifique el comportamiento correcto esperado; la misma regla se aplica a nivel SR

"Camino feliz" definido (REQ-E): un PR es de camino feliz si utiliza uno de los patrones EARS positivos — Ubicuo, Dirigido por Eventos, Dirigido por Estados, Opcional, Complejo, EARS-E, EARS-T, EARS-P. Excluidos: Comportamiento No Deseado, EARS-N (negativo/shall not), EARS-F (declarativo de modo de fallo).

Ejecutar Descomposición Adversaria de Errores para cada UN:

1. ¿Cómo falla en silencio?
2. ¿Cómo falla ruidosamente?
3. ¿Cómo falla bajo carga?
4. ¿Cómo falla bajo malicia?
5. ¿Cómo falla con el tiempo?

Cada modo de fallo se convierte en un PR If/Then EARS (etiquetar con [ADV] en el encabezado; el identificador sigue siendo canónico, por ejemplo, PR-007 [ADV]) o una nota para un registro de riesgos separado.

Ejemplo práctico. UN: "preservar cada archivo subido". Modo de fallo: "falla en silencio cuando el espacio libre en disco se agota". PR resultante:

### PR-007 [ADV]: Rechazar subida cuando la presión del disco es alta
Si el espacio libre en disco cae por debajo del 5%, entonces el sistema rechazará nuevas subidas
con HTTP 507 Almacenamiento Insuficiente y devolverá un encabezado Retry-After.
derived_from::PR->UN [UN-001]
traces_to::PR->SR [SR-014]

Tenga en cuenta que el modo de fallo es concreto y cuantificado (5%, HTTP 507, Retry-After) — eso es lo que hace que el PR sea verificable (C7).

Paso 4: Redactar Requisitos de Software (SR-NNN)

Para cada PR, derivar SRs:

• Específicos de implementación: nombrar servicios, APIs, bases de datos, códigos de error
• Sintaxis EARS con nombres de componentes específicos
• Cada SR traza hacia atrás: derived_from::SR->PR [PR-NNN]
• Cada SR traza hacia adelante: traces_to::SR->TC [TC-NNN]
• Usar granularidad a nivel de cláusula (SR-NNN.c1, .c2) para consolidar comportamientos relacionados bajo un único ID de SR
• Cada SR de camino feliz debe tener al menos un compañero SR If/Then (No deseado) (consultar el Paso 3 para la definición de "camino feliz")
• Cada SR EARS-N debe tener al menos un compañero SR positivo

Paso 5: Tablas de Especificación de Campos

Para características con entrada/mostrado de datos, añadir tablas de especificación de campos en la sección SR:

ID de Campo	Nombre	Etiqueta	Tipo	Mín	Máx	Unidad	Predeterminado	Requerido	Exposición en UI	Regla de Validación	Mensaje de Error	SR Padre

Valores de Exposición en UI: editable | display-only | hidden.

Paso 6: Puerta de Eco

Para cada cláusula SR, redactar una afirmación verificable de una línea:

VERIFY: [SR-NNN.c1] — [reformulación del requisito como una afirmación verificable]

Si no puede escribir la afirmación, el requisito no es verificable — reescribirlo.

Paso 7: Verificación de completitud

Ejecutar la lista de verificación en completeness.md antes de declarar la redacción finalizada.

Manejo de entradas grandes

Cuando la entrada supere ~200 elementos de origen (por ejemplo, un pegado grande de Excel):

1. Dividir en lotes de 50 filas.
2. Para cada lote: a. Leer el lote. b. Transcribir a markdown UN/PR/SR según los pasos anteriores. c. Añadir al archivo de trabajo (no sobrescribir). d. Informar el progreso: "Lote de completo; requisitos redactados."
3. Después de todos los lotes, ejecutar la verificación de completitud en el archivo completo.

Si un lote contiene entrada ambigua, pausar y pedir aclaración antes de continuar — no saltar filas en silencio.

Rutas de salida

Predeterminado: ./requirements/SPECIFICATION.md para el UN/PR/SR consolidado. El usuario puede sobrescribir.

Al actualizar un archivo existente, preservar los IDs existentes — añadir nuevos con el siguiente número secuencial.

Sintaxis de referencias cruzadas (chuleta)

relation_type::SOURCE->TARGET [ID-list]

Tipo	Dirección	Uso
traces_to	hacia adelante	UN→PR, PR→SR, SR→TC, UN→Persona
derived_from	hacia atrás	PR→UN, SR→PR, TC→SR
validates	verificación	TC→SR
mitigates	control de riesgo	SR→RISK
conflicts_with	contradicción	cualquier→cualquier

Formato de identificador

Expresión regular: ^(UN|PR|SR|TC)-\d{3}(\.[A-Z])?$

• IDs base: UN-001, PR-001, SR-001
• Sub-IDs (tabular EARS-P): PR-010.A, PR-010.B
• Notación de cláusula: SR-001.c1, SR-001.c2

Archivos de referencia

• ears-guide.md — los 12 patrones EARS
• templates.md — plantillas markdown para secciones UN/PR/SR
• completeness.md — lista de verificación de salida (cobertura UN→PR→SR)