cosmoSys » cosmoSys-Req

{{>toc}}

# Guía funcional de cosmoSys-Req

Esta guía explica el modelo funcional que cosmoSys-Req añade a [[csys:cosmoSys]]. Presupone únicamente una idea básica: cosmoSys organiza ítems en árboles de proyectos y les proporciona identidades, relaciones, diagramas, documentos, informes, transferencias y copias.

No es un procedimiento paso a paso ni una metodología obligatoria de ingeniería de requisitos. Describe qué significa cada campo, estado, relación y validación para que una organización pueda integrarlos correctamente en su proceso.

## 1. Qué es un requisito en cosmoSys-Req

Un requisito es un ítem cuyo perfil activa capacidades específicas del dominio. Sigue siendo parte del mismo modelo colaborativo que las tareas, documentos y demás elementos del proyecto, pero dispone de atributos, presentación y validaciones propios.

El requisito conserva:

- un CSID estable;

- un texto principal;

- su posición dentro de la especificación;

- relaciones con otros ítems;

- fuente de derivación;

- tipo y nivel;

- información de verificación;

- cumplimiento e implementación cuando correspondan;

- estado y madurez;

- evidencia del significado aprobado.

La jerarquía indica dónde aparece en el libro. Las relaciones indican de qué depende. La derivación señala de qué requisito procede. Ninguna de estas dimensiones debe utilizarse como sustituta automática de las otras.

{{thumbnail(cosmosys-req-overview.png, size=600, title=Modelo funcional de cosmoSys-Req)}}

## 2. Identidad y presentación

Cada requisito recibe un CSID, como `SYS-0042`, mediante los mecanismos comunes de cosmoSys. El identificador no cambia al reorganizar capítulos ni al mover el requisito dentro del mismo árbol de proyectos.

El capítulo es una representación calculada a partir de la jerarquía. Puede cambiar durante la edición de la especificación.

En textos y relaciones debe preferirse la identidad estable cuando lo que se quiere conservar es el destino. El capítulo resulta apropiado para presentar la estructura de una edición concreta del documento.

Un requisito aprobado sigue siendo contenido vigente. Aunque su estado esté cerrado para Redmine, no se presenta como una tarea tachada: el cierre satisfactorio significa consolidación, no desaparición.

{{thumbnail(cosmosys-identity-and-chapter.png, size=600, title=Identidad estable y capítulo calculado)}}

## 3. Campos propios del requisito

### Tipo

El tipo describe la naturaleza del requisito según la taxonomía configurada por el proyecto. Permite distinguir, por ejemplo, requisitos funcionales, de rendimiento, de interfaz o de restricción sin deducirlo del texto.

### Nivel

El nivel sitúa el requisito dentro de la descomposición del sistema: misión, sistema, subsistema, componente u otros niveles definidos por el dominio.

Tipo y nivel son dimensiones diferentes. Un requisito de rendimiento puede existir en varios niveles; un nivel puede contener requisitos de muchos tipos.

### Justificación

La justificación explica por qué existe el requisito, qué decisión sostiene o qué razonamiento condujo a formularlo. No sustituye el texto normativo del requisito.

En consultas e informes puede presentarse debajo de la descripción, como parte del cuerpo, en lugar de convertirse en una columna estrecha difícil de leer.

### Fuente de derivación

La fuente identifica el requisito del que procede el actual. Es trazabilidad explícita de origen.

La acción **Derive** puede crear el nuevo requisito, registrar esta fuente y establecer las relaciones causales correspondientes. La herramienta ayuda a construir una operación coherente, pero el usuario sigue siendo responsable de que la derivación sea técnicamente correcta.

### Verificación

Los requisitos pueden conservar métodos y descripción de verificación. Los métodos indican cómo se prevé demostrar el cumplimiento —por ejemplo análisis, inspección, ensayo o demostración— y la descripción explica el caso concreto.

Definir un método no significa que la verificación ya se haya ejecutado. Planificación, ejecución, resultado y validación deben interpretarse de acuerdo con el proceso de la organización.

### Cumplimiento e implementación

Los perfiles que lo necesiten pueden añadir seguimiento de cumplimiento, inclusión o validación en una entrega. Estos campos permiten observar la evolución del producto sin confundirla con la madurez del texto del requisito.

Un requisito puede estar perfectamente aprobado y todavía no haberse implementado. También puede existir una implementación cuya validación siga pendiente.

## 4. Variantes suministradas

cosmoSys-Req incluye inicialmente cuatro trackers que consumen el perfil de requisito con capacidades distintas:

- `csRq`: requisito canónico, centrado en redacción y revisión;

- `csRqm`: añade gestión de trabajo, como asignación, fechas, esfuerzo y progreso;

- `csRqr`: añade seguimiento de inclusión y validación en una entrega;

- `csRqmr`: combina las capacidades de gestión y entrega.

La versión objetivo está disponible en todos los requisitos. Las diferencias no se implementan ocultando con CSS campos que siguen activos: cada tracker declara qué campos nativos utiliza, de forma que la edición rápida, la API y las operaciones masivas respeten el mismo contrato.

Los nombres de trackers son una configuración inicial. La lógica del plugin se apoya en el item profile `requirement`, no en la existencia permanente de esos cuatro nombres.

{{thumbnail(cosmosys-req-variants.png, size=600, title=Variantes suministradas del perfil de requisito)}}

## 5. Workflow básico

El ciclo principal distingue tres estados de madurez:

- `Draft`: el requisito está en elaboración;

- `Stable`: el texto está preparado para revisión o uso controlado;

- `Approved`: el requisito ha sido aceptado por el proceso correspondiente.

Los workflows de Redmine determinan quién puede realizar cada transición. La organización puede reservar la aprobación a los roles revisores y permitir que otros participantes redacten o propongan cambios.

cosmoSys-Req no aprueba automáticamente un requisito porque su texto parezca completo. La transición sigue siendo una decisión humana autorizada.

{{thumbnail(cosmosys-req-lifecycle.png, size=600, title=Ciclo de vida del requisito)}}

## 6. Cierres satisfactorios y no satisfactorios

cosmoSys añade a los estados cerrados una semántica de resultado:

- un cierre **satisfactorio** consolida el ítem;

- un cierre **no satisfactorio** lo retira del contenido vigente sin destruir su historia.

En la configuración de requisitos, `Approved` y los cierres positivos equivalentes representan consolidación. `Rejected` y `Erased` representan cierres negativos.

### Rejected

Indica que el requisito fue evaluado y rechazado. Puede existir un workflow de recuperación hacia `Draft` cuando la organización necesita reconsiderarlo.

### Erased

Representa una eliminación lógica. El requisito conserva CSID, contenido, historial, posición y relaciones, pero deja de formar parte del contenido positivo ordinario.

La eliminación lógica protege la trazabilidad y evita reutilizar accidentalmente la identidad de un requisito retirado. La eliminación física puede restringirse mediante permisos y reglas del perfil.

### Elementos huérfanos

Si un elemento positivo queda bajo un antecesor `Erased`, no debe desaparecer sin explicación. Árbol e informe pueden rescatarlo bajo un capítulo virtual de elementos huérfanos para que el usuario lo reubique.

Un elemento negativo bajo otro negativo no necesita aparecer como huérfano: ya forma parte del subárbol retirado.

Los elementos negativos se conservan en árbol e informe para trazabilidad, pero no participan en diagramas ni DSM ordinarias.

{{thumbnail(cosmosys-req-erased-orphans.png, size=600, title=Subárbol retirado y elementos positivos huérfanos)}}

## 7. Madurez y dependencias

Los estados tienen un nivel de madurez. El principio funcional es que un requisito no debería estar más maduro que aquello que lo sostiene.

Cuando `A blocks B`, A actúa como antecedente de B. Si B está aprobado y A vuelve a borrador, B se considera inconsistente.

La validación de madurez se activa mediante el item profile. Actualmente el perfil de requisito es el que utiliza esta capacidad; otros perfiles no heredan la regla por el mero hecho de tener relaciones `blocks`.

La inconsistencia no cambia automáticamente el estado. Se muestra mediante avisos y señales visuales, incluido el rojo de los diagramas. El usuario decide si debe reabrir, revisar o corregir las relaciones.

La comprobación inmediata de madurez no necesita recorrer toda la cadena para cambiar estados. La evidencia aprobada, descrita a continuación, sí conserva el contexto transitivo necesario para detectar cambios más profundos.

{{thumbnail(cosmosys-req-maturity-chain.png, size=600, title=Madurez coherente a lo largo de una cadena bloqueante)}}

## 8. Evidencia del texto aprobado

Comparar sólo estados no basta. Dos requisitos pueden volver a aparecer como `Approved` aunque el texto del antecedente haya cambiado entre ambas aprobaciones. También puede cambiar un dato compartido sin editar directamente el requisito que lo utiliza.

Cuando un requisito aumenta su madurez por encima del nivel inicial, cosmoSys-Req captura una línea base con:

- texto fuente;

- descripción resuelta;

- datos de proyecto utilizados;

- contexto transitivo de relaciones `blocks`;

- CSID y textos resueltos de los antecedentes;

- aristas de la cadena bloqueante;

- estado, madurez, fecha y hash de la evidencia.

Los nodos y aristas se ordenan de forma canónica. Así, aprobar otra vez un antecedente no oculta que cambió su contenido, y restaurar exactamente el texto y la topología anteriores elimina la deriva sin obligar a repetir una aprobación innecesaria.

### Qué provoca inconsistencia

- Cambiar la descripción explícita del requisito.

- Cambiar el valor o nombre de un `csDatum` utilizado.

- Cambiar el texto resuelto de un antecedente bloqueante.

- Añadir o retirar un antecedente dentro de la cadena.

- Reorganizar las aristas que forman el contexto causal.

### Qué no debe provocarla

- Cambiar un dato que el requisito no utiliza.

- Reordenar etiquetas efímeras del catálogo documental cuando la cita conserva el mismo marcador estable.

- Modificar sólo la presentación HTML sin cambiar el texto canónico.

- Alterar temporalmente un antecedente y restaurarlo exactamente antes de la comparación.

Las etiquetas `RD.n`, `AD.n` y `CD.n` pertenecen a la presentación. El marcador `document:di<ID>` pertenece al texto canónico. Esta separación evita inconsistencias fantasma por una simple renumeración del catálogo y debe mantenerse cubierta por pruebas de regresión.

{{thumbnail(cosmosys-req-approved-evidence.png, size=600, title=Composición y comparación de la evidencia aprobada)}}

## 9. Cómo se presenta una inconsistencia

La vista del requisito muestra un aviso y, para su descripción, un diff entre el texto aprobado y el actual. El contexto bloqueante puede señalar que la cadena cambió sin revelar textos que el usuario no está autorizado a consultar.

El aviso distingue dos causas. Si cambia un `csDatum`, el diff enfrenta el texto resuelto que se aprobó con el vigente. Si cambia algún contenido o arista de la cadena bloqueante transitiva, el aviso señala que el contexto causal ya no coincide con la evidencia aceptada.

{{thumbnail(cosmosys-req-datum-change-warning.jpg, size=600, title=Cambio de un dato reflejado en el texto resuelto)}}

{{thumbnail(cosmosys-req-blocking-chain-change-warning.jpg, size=600, title=Cambio en la cadena bloqueante aprobada)}}

Los diagramas utilizan rojo para el requisito o cluster inconsistente. Si es además el protagonista de la vista, su borde grueso debe seguir siendo rojo en lugar de quedar cubierto por el azul habitual de selección.

En el ejemplo siguiente aparecen en rojo tanto el requisito inconsistente como su dependiente afectado. La dirección de esa propagación ayuda a distinguir una deriva en el contexto causal de un simple intento de elevar la madurez de un requisito por encima de su antecedente.

{{thumbnail(cosmosys-req-inconsistent-diagram.jpg, size=600, title=Requisito inconsistente y dependiente afectado)}}

Los informes deben transportar el aviso con un refuerzo visual rojo y una señal adicional que no dependa únicamente del color. La apariencia debe sobrevivir a la conversión a ODT, DOCX y PDF.

Bajar la madurez desactiva la inconsistencia visible sin borrar la línea base. El siguiente aumento de madurez reemplaza la evidencia por la nueva revisión aceptada.

{{thumbnail(cosmosys-req-consistency.png, size=600, title=Detección de cambios en el significado aprobado)}}

## 10. Datos compartidos mediante csDatum

Los datos del proyecto pertenecen a cosmoSys base, no exclusivamente al plugin de requisitos. Un requisito puede consumirlos mediante `${Clave}` y `${Clave.value}`.

Esto permite separar una magnitud repetida de las frases que la utilizan. Cambiar el dato actualiza las presentaciones, mientras la línea base de los requisitos aprobados permite saber cuáles han cambiado de significado.

Los `csDatum` no necesitan mantener relaciones ordinarias con cada requisito consumidor. El ledger de resolución registra el uso efectivo sin llenar los diagramas de conexiones auxiliares.

La tabla de datos del informe se construye a partir de las sustituciones utilizadas durante el renderizado. Puede aparecer antes que el contenido aunque se complete después, una vez conocido el ledger final.

Los valores siguen siendo texto y pueden contener Markdown. Las fórmulas, tipos físicos y cálculos automáticos son una posible extensión futura, no una garantía actual.

{{thumbnail(cosmosys-req-engineering-model.png, size=600, title=Datos compartidos y texto resuelto)}}

## 11. Derivación

Derivar significa crear un requisito más concreto a partir de otro y conservar la trazabilidad de esa decisión.

La operación puede:

1. crear uno o varios requisitos;

2. situarlos en un destino jerárquico compatible;

3. registrar el requisito fuente;

4. crear relaciones causales de bloqueo;

5. conservar proyecto, versión y otros datos pertinentes según el contrato.

La automatización evita pasos mecánicos incoherentes, pero no decide cuántos requisitos deben derivarse ni si el texto resultante es suficiente.

{{thumbnail(requirements-derivation.png, size=600, title=Derivación hacia requisitos disciplinares)}}

La interfaz permite escoger cuántos requisitos hermanos se crearán en una sola operación. Después de generarlos, cada derivado sigue siendo un requisito independiente: el usuario puede abrir uno de ellos y cambiar su tipo o disciplina sin imponer ese cambio a los demás.

{{thumbnail(cosmosys-req-derive-select-three.jpg, size=600, title=Paso 1 crear tres requisitos derivados)}}

{{thumbnail(cosmosys-req-derive-change-one-to-mechanical.jpg, size=600, title=Paso 2 asignar Mechanical a uno de los derivados)}}

## 12. Árbol y especificación

Los requisitos se organizan bajo ítems estructurales capaces de actuar como capítulos. Un requisito ordinario no debe contener hijos; si un ítem con descendientes aparece en una migración heredada, esa estructura constituye evidencia de que probablemente era información o capítulo y no un requisito.

Los capítulos calculados ordenan la especificación. El CSID conserva la identidad incluso cuando el requisito cambia de sección.

Los requisitos aprobados permanecen visibles y reciben una presentación consolidada. Los rechazados o borrados lógicamente pueden reunirse en secciones específicas de trazabilidad en lugar de mezclarse con el contenido vigente.

La vista Tree materializa este modelo como un editor navegable en el que se distinguen capítulos estructurales y requisitos, se despliegan subárboles y se revisa la posición real que determina la especificación.

{{thumbnail(cosmosys-req-tree-editor.jpg, size=600, title=Editor real del árbol de una especificación)}}

## 13. Diagramas y DSM de requisitos

Los diagramas reutilizan las capacidades comunes de cosmoSys:

- jerarquía de la especificación;

- dependencias causales;

- vista combinada con contexto de capítulos;

- recorrido entre proyectos y niveles;

- referencias documentales cuando corresponda.

Las relaciones externas conservan un indicador de frontera y su propia jerarquía. Mostrar más pasos de la cadena no convierte los requisitos externos en requisitos locales.

La DSM permite revisar dependencias, buscar ciclos y explorar órdenes de presentación o implementación. Los requisitos retirados mediante cierre negativo no participan en la matriz ordinaria.

La siguiente captura muestra en forma de DSM el proyecto público de ejemplo [EPB](https://cosmobots.eu/projects/help-req-sample-epb). Complementa los diagramas conceptuales con la matriz real de requisitos y sus dependencias.

{{thumbnail(cosmosys-req-dsm-example.jpg, size=600, title=DSM real del proyecto de requisitos EPB)}}

## 14. Documentos de referencia

Un requisito puede citar documentos de referencia, aplicables o de cumplimiento. Cada cita conserva sentido y localización propios.

La tabla de referencias del requisito y del informe utiliza las etiquetas vigentes `RD.n`, `AD.n` y `CD.n`, pero los textos guardan marcadores internos estables. Reordenar el catálogo actualiza la presentación sin cambiar el documento citado.

Los placeholders documentales pueden insertar los catálogos en cualquier punto compatible del árbol de la especificación.

La visibilidad del documento sigue dependiendo de los permisos del usuario. Resolver una etiqueta no debe convertirse en una vía para revelar documentos restringidos.

{{thumbnail(cosmosys-document-reference.png, size=600, title=Referencia estable y etiqueta documental calculada)}}

## 15. Informes de requisitos

El informe presenta la especificación como libro, no como una tabla plana. Puede incluir:

- capítulos e ítems estructurales;

- texto normativo;

- justificación y otros campos de cuerpo;

- metadatos compactos;

- diagramas elegidos por requisito;

- referencias documentales;

- tabla de datos utilizados;

- elementos cerrados negativamente;

- avisos de inconsistencia.

Los perfiles deciden qué campos aparecen y en qué forma. El informe muestra la versión configurada como predeterminada del proyecto y transporta metadatos del proyecto a las propiedades de LibreOffice.

La plantilla controla la apariencia corporativa. El contenido procede del mismo modelo vivo que consulta el equipo.

{{thumbnail(cosmosys-req-documentation.png, size=600, title=Un modelo de requisitos con varias salidas documentales)}}

## 16. Exportación e importación ODS

El perfil de proyecto de requisitos selecciona una plantilla ODS que incluye los campos propios del dominio y hojas DSM.

La exportación puede utilizarse para revisión o trabajo temporal fuera de línea. La importación conserva el preflight común de cosmoSys: analiza identidades, linaje, altas, modificaciones, relaciones y conflictos antes de pedir confirmación.

Los códigos visibles utilizados provisionalmente durante una migración no sustituyen al CSID. Cuando existe un código externo significativo puede conservarse como `csExtCode` para facilitar trazabilidad y reescrituras posteriores.

ODS es un canal de intercambio. El proyecto sigue siendo la fuente viva de verdad después de reconciliar la transferencia.

## 17. Copias y snapshots

Los requisitos participan en las copias y snapshots comunes de cosmoSys. Una copia fiel conserva estado, identidades cuando sea posible y líneas base aprobadas. Una copia limpia reinicia el estado y no arrastra evidencias de consolidación.

Preservar CSID exige que no existan colisiones en el árbol de destino. Regenerarlos requiere reescribir referencias internas una vez construido el mapa completo entre origen y destino.

Una copia de varios proyectos crea primero todos los proyectos e ítems y restaura después sus relaciones. Este orden permite mantener dependencias entre niveles de requisitos incluso cuando el destino recibe identidades nuevas.

El snapshot declara los plugins y versiones presentes en el origen. El preflight puede advertir diferencias, pero no puede adaptar automáticamente cualquier dato creado por plugins desconocidos.

{{thumbnail(cosmosys-portable-transfers.png, size=600, title=Intercambio ODS y paquetes csys)}}

## 18. Consultas y navegación

La pestaña de ítems utiliza consultas de Redmine adaptadas al perfil de proyecto. En requisitos, el contenido consolidado no debe desaparecer por el filtro genérico de «abiertos»: los cierres satisfactorios siguen siendo parte de la especificación.

Los cierres negativos pueden excluirse de la consulta principal y permanecer accesibles mediante vistas o capítulos de trazabilidad.

Las columnas útiles incluyen CSID, capítulo, estado, tipo, nivel, versión y otros campos habilitados por el perfil. Los textos largos, como descripción o justificación, resultan más legibles como bloques bajo la fila principal que como columnas estrechas.

## 19. Permisos y revisión

Los permisos de [Redmine](https://www.redmine.org/) gobiernan lectura, edición y transiciones. El workflow puede reservar `Stable` o `Approved` a roles específicos.

Una relación bloqueante ordinaria puede impedir cierres positivos mientras el antecedente permanece abierto. El perfil de requisito permite, sin embargo, que un cierre negativo como `Rejected` siga estando disponible: rechazar algo no afirma que sus dependencias estén satisfechas.

Recuperar un requisito rechazado requiere una transición definida, por ejemplo `Rejected -> Draft`. Ser administrador no crea una transición que el workflow no contiene.

## 20. Qué no garantiza cosmoSys-Req

cosmoSys-Req no determina si un requisito es necesario, verificable o técnicamente correcto. Tampoco demuestra que una relación de derivación represente el razonamiento real del equipo.

Las líneas base detectan deriva del texto resuelto y del contexto conocido; no congelan transaccionalmente todos los objetos de la instancia. Otro usuario puede modificar información mientras se genera un informe.

El responsable debe revisar la especificación entregable. La herramienta reduce trabajo mecánico, conserva evidencias y hace visibles incoherencias que de otro modo pasarían inadvertidas, pero no sustituye el juicio de ingeniería.

## Para seguir

- [[cosmoSys-Req]] — presentación general del gestor de requisitos.

- [[csys:cosmoSys]] — plataforma común sobre la que se construye.

- [[csys:Guía funcional de cosmoSys]] — árboles, diagramas, documentos, informes, ODS y copias.

- [[Gestor de requisitos]] — introducción general a la disciplina y sus herramientas.

- [Cosmobots](https://cosmobots.eu/) — la asociación sin ánimo de lucro que impulsa el proyecto.