cosmoSys » cosmoSys-Req

{{>toc}}

# cosmoSys-Req

**cosmoSys-Req es un [[Gestor de requisitos]] libre, abierto y gratuito para ingeniería de sistemas.**

Se construye sobre [[csys:cosmoSys]] y Redmine para que los requisitos no vivan en una base de datos aislada: comparten proyectos, usuarios, documentos y mecanismos de colaboración con el resto del trabajo de ingeniería, pero conservan su identidad, sus atributos y su ciclo de revisión propios.

Si ya trabajas con requisitos, aquí puedes ver qué aporta la herramienta. Si no, [[Gestor de requisitos]] explica primero qué información se gestiona y por qué una hoja de cálculo empieza a quedarse corta cuando el sistema crece.

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

## Requisitos++

Cada requisito recibe un **CSID estable y legible**, como `M2-0027`, que puede conservar aunque el ítem cambie de capítulo o se mueva dentro del árbol de proyectos. Junto al texto se pueden mantener su tipo y nivel, la justificación, la fuente de derivación, los métodos y la descripción de verificación, y la información de cumplimiento e implementación que corresponda.

La herramienta separa dimensiones que a menudo se mezclan:

- la **jerarquía del libro** indica dónde se presenta el requisito;

- las **relaciones** indican de qué depende, qué bloquea o con qué está conectado;

- la **derivación** conserva el requisito del que procede;

- el **workflow** expresa su madurez de redacción y revisión;

- la **verificación y el cumplimiento** describen cómo se evaluará y qué resultado se ha obtenido.

Por eso un requisito puede reorganizarse en la especificación sin perder su procedencia, y dos requisitos cercanos en el documento no tienen por qué fingir una dependencia que no existe.

## Ayudas al proceso de creación de requisitos

La acción **Derive** ayuda a crear requisitos derivados como una operación coherente: sitúa los nuevos ítems, registra la fuente y crea las relaciones causales. El usuario sólo tiene que nombrar y describir los nuevos requisitos, ahorrándose el tedio de establecer las relaciones una a una.

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

En el siguiente diagrama vemos cómo un requisito complejo se ha derivado en cosmoSys:

![](https://cosmobots.eu/help-req-sample-cstick-req/cosmosys/diagrams/dependency/svg?issue_id=108&visible_layers%5B%5D=blocks&visible_layers%5B%5D=precedes&visible_layers_present=1)

Puedes consultar este ejemplo [aquí](https://cosmobots.eu/projects/help-req-sample-cstick-req).

## Gestión de características, datos del proyecto

cosmoSys incorpora `csDatum`, un diccionario de datos común al árbol de proyectos. Una definición reúne una clave estable, un nombre legible y un valor textual con sus unidades o interpretación.

Así, un requisito puede almacenar:

```text

The mirror system shall reach ${AverageThroughput.value} average throughput.

```

y presentar el valor vigente —por ejemplo, *85%*— sin duplicarlo en cada texto. `${AverageThroughput}` presenta el nombre legible y `${AverageThroughput.value}` el valor. Las expresiones desconocidas permanecen visibles para que la falta de información no quede escondida.

Los datos utilizados se registran durante la generación del informe y pueden formar una tabla de metadatos. Además, la evidencia de aprobación permite advertir si cambiar un dato ha alterado realmente el significado de un requisito consolidado. `csDatum` sigue siendo texto: el cálculo de fórmulas, las magnitudes tipadas y los motores automáticos de evaluación pertenecen a una evolución posterior.

{{thumbnail(cosmosys-req-engineering-model.png, size=600, title=elementos relacionados)}}

## Ciclo de vida del requisito

El ciclo básico distingue `Draft`, `Stable` y `Approved`: redacción, texto preparado para revisión y requisito aceptado. `Rejected` y `Erased` son cierres negativos; no equivalen a destruir físicamente el ítem. Su identidad, contenido, historial, posición y relaciones permanecen disponibles para trazabilidad y recuperación autorizada, aunque las vistas del contenido vigente puedan ocultarlos por defecto.

Los estados cerrados también tienen significado. Un requisito aprobado es contenido consolidado, no una tarea «terminada» que deba desaparecer o mostrarse tachada. cosmoSys-Req conserva los requisitos aprobados en el árbol y en la especificación, y distingue los cierres satisfactorios de las retiradas o rechazos.

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

## Control de consistencia

Una relación de bloqueo puede representar una dependencia causal: si un requisito de sistema da origen a otro más concreto, el requisito fuente bloquea al derivado. El derivado no debería aparecer más maduro que aquello de lo que deriva.

cosmoSys-Req asigna niveles de madurez a los estados y comprueba la cadena bloqueante. Si un requisito `Approved` depende de otro que vuelve a `Draft`, la inconsistencia se hace visible. Los diagramas la resaltan en rojo y la presentación del requisito explica el problema; el sistema no cambia estados silenciosamente ni pretende sustituir la decisión del revisor.

### Control del texto realmente aprobado

Comprobar sólo inconsistencias a partir de los estados de los requisitos o de cambios en sus propios textos (descripción, justificación...) no basta. Un requisito seguirá en `Approved` aunque se haya cambiado un dato del proyecto que utiliza. Si un requisito depende de otro que se modifica y se aprueba de nuevo, también podría dejar de detectarse la inconsistencia. Esto es muy común en sistemas de gestión de requisitos que basan su detección de consistencias en localizar requisitos que dependen de otros menos maduros.

cosmoSys-Req dispone de mecanismos para impedir que estos cambios pasen inadvertidos.

Cada vez que aumenta la madurez, cosmoSys-Req guarda evidencia del texto **explícito** que se revisó y del contexto transitivo de requisitos que lo bloqueaban. Es decir, obtiene una fotografía del texto que el revisor analizó y consideró válido e incluye también los textos de todos los requisitos de los que dependía, recorriendo toda la cadena de dependencias. La fotografía de esa transición se registra y actúa como referencia hasta el siguiente aumento de madurez.

Cada vez que un requisito va a mostrarse, se toma una instantánea efímera que se compara con la de referencia:

- si cambia porque cambió un `csDatum`, detecta la diferencia;

- si cambia el texto de un requisito antecedente, la detecta;

- si se añade, elimina o reorganiza una dependencia de la cadena, también la detecta.

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

Cuando existe deriva, la vista muestra el aviso y, para el texto del propio requisito, un diff entre lo aprobado y lo actual. La forma usual de aceptar el cambio es bajar la madurez, revisar y volver a subirla (por ejemplo Approved -> Stable -> Draft -> Stable -> Approved). La configuración de workflows, roles y permisos permite reservar esas transiciones al equipo revisor que corresponda.

Si se revierten los cambios que causaron la inconsistencia, cosmoSys-Req retira las advertencias, pues el requisito vuelve a expresarse exactamente igual que en la fotografía de referencia. De esa manera, un cambio accidental no dispara toda una cadena de trabajo.

Estas revisiones de la consistencia son una ayuda a la revisión: no una promesa de consistencia transaccional ni un sustituto de la responsabilidad técnica sobre el documento entregado. Es un mecanismo de calidad contra errores, no una garantía ante negligencias ni sabotajes.

## Trazabilidad que se puede ver y navegar

La jerarquía, las relaciones y las referencias no quedan escondidas en columnas dispersas. cosmoSys genera a partir del modelo vigente:

- diagramas jerárquicos, para comprender el libro y sus capítulos;

- diagramas de dependencias, para recorrer causas y consecuencias;

- diagramas combinados, que expresan a la vez dependencias y jerarquías;

Los diagramas no son simples dibujos que haya que actualizar a mano. Se regeneran desde los mismos ítems y relaciones que consulta el equipo y pueden incorporarse después a la documentación. También son navegables para agilizar su análisis. Se acabó perder el hilo  buscando en una matriz o buscando códigos en el proyecto para averiguar de qué otros requisitos dependía el requisito del que deriva el actual.

Este es un ejemplo de diagrama combinado.

![Diagrama combinado](https://cosmobots.eu/help-req-sample-epb/cosmosys/diagrams/combined/svg?combined_layout_mode=dot&issue_id=4&render_variant=v1&visible_layers%5B%5D=blocks&visible_layers%5B%5D=precedes&visible_layers_present=1)

Nota: puedes navegar por este proyecto de ejemplo [aquí](https://cosmobots.eu/projects/help-req-sample-epb)

## Referencias documentales enriquecidas

Las normas, especificaciones de nivel superior, manuales o evidencias pueden catalogarse como documentos de referencia, aplicables o de cumplimiento, creando referencias como RD.1, AD.1 o CD.1, muy útiles cuando se genere el informe, al estilo de un documento o artículo de ingeniería.

Normalmente son los documentos los que referencian a otros documentos, pero en cosmoSys-Req cada ítem puede referenciar documentos. Cada requisito puede mantener una lista de referencias sin limitación de número o familia documental.

Además, cada referencia desde un ítem puede, a discreción del usuario, tener su propio **sentido** —por qué se usa— y su **localización** —capítulo, página, tabla o anexo relevante—, lo que ayuda al equipo a entender por qué ese ítem referencia ese documento y a encontrar dentro de él el texto de interés.

Las etiquetas del catálogo se calculan automáticamente. Una cita textual conserva una identidad interna estable y sigue apuntando al documento correcto aunque el catálogo cambie de orden, evitando mantener a mano referencias como `RD.2` o `AD.4` repartidas por toda la especificación. Si un usuario intercambia las entradas que en ese momento se muestran como `RD.5` y `RD.6`, las citas presentan sus nuevas etiquetas sin modificar su destino ni el Markdown almacenado. El diseño separa así un simple cambio de numeración del contenido esencial que fue revisado, para evitar inconsistencias fantasma.

## Generación de informes de calidad

El proyecto puede leerse como un libro: capítulos, requisitos, metadatos, referencias y diagramas forman una vista HTML que se revisa antes de exportar. Las plantillas de LibreOffice controlan la presentación final y permiten producir documentos editables o PDF sin convertir una tabla de cientos de columnas en la especificación oficial.

La documentación procede de la misma información sobre la que trabaja el equipo. No elimina la necesidad de establecer baselines o revisar una entrega concreta, pero evita mantener por separado un modelo vivo y un documento que empieza a envejecer desde el momento en que se copia.

{{thumbnail(cosmosys-req-documentation.png, size=600, title=De modelo de proyecto a documentación)}}

Los proyectos de requisitos pueden tener versiones, y los requisitos pueden asociarse a aquella en la que se han de consolidar. En la pestaña Roadmap se puede consultar en qué versión se espera consolidar cada requisito y cuántos quedan pendientes para poder cerrar una entrega.

El informe muestra la versión que el proyecto tenga configurada como predeterminada.

Los informes no parecen como volcados de una hoja de cálculo, con demasiadas columnas y textos largos apretados en una de ellas mientras en otras se derrocha espacio. Los informes parecen libros de especificaciones legibles y bien formateados.

El usuario determina si cada metadato se presenta en una tablilla tras la descripción del requisito o como un apartado más del requisito dentro del cuerpo del texto.

cosmoSys-Req ofrece también capítulos especiales que se autogeneran. Por ejemplo, el usuario puede situar en el árbol un marcador para generar un capítulo de referencias documentales, otro de elementos eliminados y otro con los datos del proyecto. El usuario decide libremente en qué lugar del documento se muestran. El informe contendrá esas secciones con sus tablas correspondientes, autogeneradas por la herramienta, y presentadas como cabría de esperar en un documento técnico.

Los diagramas también pueden incorporarse a los informes acompañando a cada requisito. Para cada uno se puede escoger de forma independiente qué diagrama mostrar: ninguno, dependencias, jerarquía o combinado. cosmoSys-Req incluye además mecanismos para preservar su legibilidad y evitar tediosos postprocesos de ajuste estético manual.

Por ejemplo, si el documento utiliza una plantilla con orientación vertical y cosmoSys-Req estima que un diagrama tendría que reducirse demasiado para caber en el ancho disponible, puede moverlo a una página con orientación apaisada, siempre que la plantilla proporcione esa página alternativa y el cambio mejore su escala.

## Exportaciones con revisión previa

Los requisitos pueden exportarse a una hoja de cálculo ODS (compatible con Excel) útil para revisión o trabajo temporal fuera de línea. También pueden importarse por el mismo método.

Al volver a cargarla, cosmoSys no aplica los cambios a ciegas: prepara una transferencia, compara altas y modificaciones, detecta incidencias y exige confirmación.

La plantilla específica de requisitos conserva sus campos propios y las hojas DSM, que pueden resultar muy útiles para revisar dependencias sin conexión.

cosmoSys-Req también comprueba el linaje de la hoja al cargar. Así puede detectar cambios concurrentes respecto a la exportación de origen y evitar que dos ramas del mismo ODS sobrescriban silenciosamente el proyecto.

## Extensiones al requisito y su ciclo de vida

Algunas organizaciones utilizan la gestión de requisitos como otra vista más del avance del proyecto. Un requisito aprobado puede además marcarse como incluido cuando su implementación se incorpora al sistema en desarrollo, y como validado cuando supera sus validaciones. De esa manera se evita crear tareas asociadas sólo para este seguimiento y se puede saber si una entrega está lista consultando los requisitos aún no validados. El equipo de QA puede identificar qué requisitos podrían validarse observando cuáles están incluidos. No es un uso canónico de los gestores de requisitos, pero sí un uso extendido.

En nuestra experiencia con versiones anteriores de cosmoSys-Req, donde los requisitos seguían mostrando campos típicos de las tareas —como fechas o personas asignadas—, algunas organizaciones utilizaban esos campos para determinar quién debía redactar cada requisito o cuándo debía estar consolidado. De esa manera combinaban la potencia del gestor de requisitos con la de un gestor de tareas. Como en el caso anterior, no es un uso canónico, pero sí extendido.

Por tanto, cosmoSys-Req incluye por defecto cuatro tipos de ítem para representar requisitos:

- `csRq`: redacción y gestión del requisito, uso canónico;

- `csRqm`: añade asignación, fechas, esfuerzo y progreso de trabajo, combinando requisito y tarea;

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

- `csRqmr`: combina `csRqm` y `csRqr`.

## Colaborar sobre un modelo común

cosmoSys-Req es una aplicación web multiusuario sobre [Redmine](https://www.redmine.org/). Roles, permisos, workflows, proyectos y subproyectos permiten repartir visibilidad y responsabilidad sin que cada participante mantenga una copia privada de la especificación.

No hay licencias por puesto que obliguen a dejar fuera de la revisión a parte del equipo. La organización puede alojar su propia instancia y decidir qué personas, equipos o proveedores acceden a cada proyecto.

Es también **software libre, abierto y gratuito**. La organización puede auditar el código y dispone de formatos abiertos, exportaciones, snapshots y la API de Redmine para evitar que el conocimiento quede secuestrado.

La generación actual es una refundación técnica y conceptual de un sistema utilizado desde 2019. Continúa en evolución activa: conviene evaluarla de forma controlada y comprobar cada entrega, como corresponde a cualquier herramienta que participa en un proceso de ingeniería.

## Pero, ¿quién es el dueño de mis datos?

cosmoSys es software libre, abierto y gratuito. La instalación y los datos permanecen bajo el control de la organización, el código puede auditarse y no existe una licencia de salida para recuperar el trabajo propio.

La interoperabilidad no se trata como una función accesoria. Los requisitos pueden intercambiarse mediante ODS, los informes se entregan en formatos documentales abiertos, los snapshots `.csys` son paquetes ZIP con un manifiesto JSON y los ficheros originales, y la API de [Redmine](https://www.redmine.org/) ofrece otra vía de acceso programático. Los formatos se han escogido expresamente para que extraer, inspeccionar y transformar los datos sea tan natural como introducirlos.

Esto no significa que operar un servidor carezca de costes de infraestructura o administración. Significa que cosmoSys no cobra por puesto, no esconde la información en un formato deliberadamente opaco y no exige pagar un rescate para llevársela a otra herramienta.

**Tu organización, dus datos, tus decisiones. Abandónanos cuando quieras.**

{{thumbnail(cosmosys-data-ownership-without.png, size=600, title=Recuperar datos en una herramienta cautiva)}}

{{thumbnail(cosmosys-data-ownership-with.png, size=600, title=Recuperar datos con cosmoSys-Req)}}

## Código y recursos

- **Código fuente:** [cosmoBots/cosmoSys-Req](https://github.com/cosmoBots/cosmoSys_Req) en GitHub.

- **Versiones publicadas:** [releases de cosmoSys-Req](https://github.com/cosmoBots/cosmoSys_Req/releases).

- **Instalación y actualización:** [instrucciones del repositorio](https://github.com/cosmoBots/cosmoSys_Req#installation-classic-no-docker).

- **Licencia:** [GNU General Public License v3.0](https://github.com/cosmoBots/cosmoSys_Req/blob/main/LICENSE).

- **Documentación funcional:** [[Guía funcional de cosmoSys-Req]].

- **Plataforma base:** [código fuente de cosmoSys](https://github.com/cosmoBots/cosmoSys).

## Snapshots, copias y plantillas

En cualquier instante, un usuario puede guardar un snapshot inmutable del estado material de uno o varios proyectos seleccionados. El paquete `.csys` descargable es un ZIP abierto y sencillo: contiene un manifiesto JSON y los ficheros binarios organizados por contenido para evitar duplicados.

Al materializar el snapshot o copiar directamente un proyecto se puede escoger entre una copia fiel, que conserva el estado material y puede preservar los CSID cuando no haya colisiones, y una copia limpia, que reinicia el estado de trabajo y genera normalmente nuevas identidades. Esto permite guardar un proyecto patrón y levantar nuevos proyectos a partir de él.

Como en cosmoSys los proyectos pueden subdividirse en forma de árbol, las copias pueden hacerse de proyectos individuales o como una selección de todos o algunos proyectos del mismo árbol.

El usuario también puede optar por copiar directamente un proyecto en otro, con opciones similares, sin necesidad de descargar previamente el paquete.

Ambos procesos se benefician de un sistema de carga con `preflight`, en el que un asistente irá informando de los cambios a acometer y permitiendo que el usuario tome las decisiones oportunas para controlar esa carga.

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

## Lo que cosmoSys-Req no decide por ti

La herramienta estructura información, conserva evidencias y hace visibles muchas incoherencias. No determina si un requisito está bien escrito, no demuestra por sí sola que el sistema lo cumpla y no convierte una mala relación en una buena decisión de ingeniería.

Su propósito es más útil y más realista: que el equipo pueda encontrar el origen de una decisión, comprender sus consecuencias, revisar qué ha cambiado y producir una representación coherente de lo que sabe en ese momento.

El resultado no es simplemente una lista de requisitos, sino un **libro vivo y un modelo conectado del proyecto**.

{{thumbnail(cosmosys-req-traceability.png, size=600, title=Cadena de trazabilidad del proyecto)}}

## Para seguir

- [[Gestor de requisitos]] — qué información gestiona esta clase de herramientas.

- [[csys:cosmoSys]] — árboles, diagramas, informes, documentos, ODS y reutilización de proyectos.

- [[Guía funcional de cosmoSys-Req]] — conceptos, campos, estados y validaciones propios de requisitos.

- [[csys:Guía funcional de cosmoSys]] — explicación detallada de las capacidades compartidas y su uso.

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