Saltearse al contenido

Pensascopio — Base de conocimiento (ingeniería de requisitos)

Rafael, Director de la Escuela de Ingeniería Informática (UCAB), diseña Pensascopio: suite de gestión curricular que arranca en UCAB y se ofrecerá a otras instituciones. Este repositorio es su espacio de ingeniería de requisitos: el espacio del problema. La solución técnica vive en otro repo y otra conversación.

Alcance

  • Sí, aquí: glosario, modelo conceptual del dominio, actores, reglas de negocio, casos de uso, historias narrativas, procesos, diagramas de estado, C4 nivel 1 (Contexto), requisitos de calidad expresados como restricciones de negocio, decisiones funcionales, preguntas abiertas, paquetes de aterrizaje.
  • No, aquí (espacio de la solución): código, frameworks, modelo de datos físico, C4 niveles 2 a 5, tecnologías, despliegue. Si surge, anótalo en “Para la conversación técnica” de la nota. Un borrador de arquitectura se admite solo como hipótesis (status: hipotesis), marcado como tal.
  • No contradigas decisiones técnicas previas; si crees que chocan, regístralo como pregunta abierta.

Reglas de trabajo

  • Español venezolano, tuteo. En textos de commit usa “agregar”, no “añadir”.
  • Análisis crítico: alternativas, supuestos, qué validar con usuarios. Rafael prefiere que lo contradigan con argumentos.
  • Afirmaciones sobre productos o herramientas: verifícalas en documentación vigente.
  • Solo lo que Rafael confirmó entra como hecho. Lo demás se marca como supuesto o hipótesis a validar.
  • Muestra vista previa antes de cambios grandes (mover, renombrar, borrar, reorganizar) y espera confirmación.
  • No hagas commits sin que lo pida. No toques private/.
  • Un artefacto con estado validada, lista o entregada solo se modifica con mi aprobación explícita y mostrando el diff. La ingesta, la consulta y la revisión pueden proponer cambios, no aplicarlos.

Identificadores (obligatorios)

Formato PREFIJO-ÁMBITO-NNN, por ejemplo BR-SP-001.

Prefijo Artefacto Carpeta
GLO Término del glosario domain/glossary/
ACT Actor domain/actors/
BR Regla de negocio domain/rules/
UCASE Caso de uso requirements/use-cases/
STO Historia narrativa requirements/stories/
DIA Diagrama (modelo de dominio, estados, proceso, contexto) requirements/diagrams/
QR Requisito de calidad / restricción requirements/quality/
DEC Decisión funcional decisions/
OQ Pregunta abierta questions/
PKG Paquete de aterrizaje packages/
SRC Fuente de evidencia (ficha) sources/<ámbito>/<tipo>/
  • Ámbito: código de herramienta (registro en README.md) o GEN para lo transversal. NNN son tres dígitos.
  • El nombre del archivo es ID-slug.md (BR-SP-001-prelacion-no-circular.md). El slug sale del título: minúsculas, sin tildes, con guiones, máximo 6 palabras. El ID nunca cambia (excepción única: el 2026-11-01 Rafael, dueño del repo, migró al inglés los prefijos, el código de ámbito, las carpetas y las claves del frontmatter; la equivalencia está en log.md). El slug puede actualizarse si cambia el título, solo con node scripts/kb-rename.mjs (ver sección “Scripts de validación y mantenimiento”). El título vivo está en title (repetido en aliases) y en el H1 # ID — Título.
  • Para asignar un ID nuevo, busca el mayor existente de ese prefijo y ámbito y suma 1. Nunca reutilices un ID; si una nota deja de valer, status: descartada.
  • Enlaza siempre con Markdown estándar relativo usando el ID (o el término con sentido en prosa) como texto visible: [BR-SP-001](../domain/rules/BR-SP-001-malla-sin-prelaciones-circulares.md). No uses wikilinks [[...]]. Para buscar un artefacto por ID, busca el texto BR-SP-001.
  • Nunca renombres un artefacto con mv o Move-Item ni editando enlaces a mano: usa node scripts/kb-rename.mjs <ID> <nuevo-slug>. Muestra la vista previa antes.
  • Usa las plantillas de templates/; no inventes estructura.

Scripts de validación y mantenimiento

  • Validar integridad (check-kb): node scripts/check-kb.mjs. Verifica que no existan wikilinks residuales, enlaces rotos, artefactos huérfanos, IDs duplicados, artefactos fuera de su hub en tools/ ni incumplimientos de trazabilidad en BR y OQ. Corre este script al cerrar cualquier sesión de trabajo o antes de confirmar cambios.
  • Renombrar slug (kb-rename): node scripts/kb-rename.mjs <ID> <nuevo-slug>. Ejecuta git mv y actualiza automáticamente todas las referencias en los archivos Markdown del repositorio.
  • Al revisar huérfanos se ignoran por convención templates/, README.md, CLAUDE.md, log.md, tools/, inbox/, private/ y sources/. Solo se reportan los artefactos de domain/, requirements/, decisions/, questions/ y packages/.

Frontmatter común

id, type, title, aliases, status, tool (código de ámbito), created (AAAA-MM-DD). Las reglas de negocio agregan source y validity. Las claves van en inglés; los valores (regla, termino, exploracion, etc.) quedan en español.

Estados: semilla → exploracion → validada → lista → entregada. También hipotesis y descartada.

Trazabilidad mínima

  • Toda BR tiene source (normativa, práctica vigente o decisión) y se enlaza desde los UCASE o STO que la aplican.
  • Todo UCASE y toda STO listan las BR que aplican y las preguntas abiertas que los bloquean.
  • Toda OQ indica qué artefactos dependen de su respuesta en ## Bloquea o condiciona.
  • Todo PKG lista los IDs que incluye. Dice qué y por qué; el cómo técnico va como pregunta.
  • Cada herramienta tiene un hub en tools/ con su code en el frontmatter y enlaza sus artefactos.

Estilo de los artefactos

  • Historias: narrativas, sin la plantilla “Como … quiero … para …”. Siempre con actor y objetivo explícitos, escenario, excepciones y ejemplos concretos verificables.
  • Casos de uso: estilo Cockburn (objetivo, actor, alcance, nivel, interesados, precondiciones, garantías, escenario principal numerado, extensiones).
  • Diagramas: el bloque mermaid dentro de la nota DIA-* es la fuente lógica para los agentes (C4 solo nivel 1 C4Context). Cuando un diagrama pasa a estado exploracion o validada, se genera su representación visual de alta estética en SVG (requirements/diagrams/assets/<ID>.svg, estilo technical blueprint) y se incrusta arriba del bloque Mermaid.

Estilo de Markdown

  • Cumple las reglas de markdownlint de .markdownlint-cli2.jsonc.
  • Deja línea en blanco antes y después de encabezados, listas, tablas y bloques de código.
  • Sin espacios al final de línea y con salto de línea final.

Operaciones

Consulta

Responde solo con artefactos del repositorio y cita sus IDs. Si la base de conocimientos no cubre algo, dilo y propón una OQ; no lo completes con conocimiento general. Si una respuesta vale la pena, propón archivarla como OQ o DEC, como vista previa, y no la crees hasta que yo apruebe.

Ingesta de fuentes

Una fuente a la vez, solo cuando yo lo pida (ver “Fuentes de evidencia”). Nunca edites la fuente. Pasos: comenta conmigo los hallazgos; propón los artefactos candidatos como vista previa, con status: hipotesis y citando la SRC; crea solo lo que yo apruebe; actualiza la ficha SRC y la bitácora. Lo que solo aparezca en la fuente se marca como supuesto.

Revisión

Corre node scripts/check-kb.mjs y revisa además: contradicciones semánticas entre BR; UCASE o STO que citan BR, OQ o SRC inexistentes; BR sin source; OQ sin “Bloquea o condiciona”. Solo reporta, con el arreglo sugerido para cada hallazgo. No apliques nada sin mi confirmación.

Bitácora

log.md, en la raíz, es el registro cronológico. Solo se agrega al final; no reescribas entradas anteriores. Una entrada por línea: - [AAAA-MM-DD] operación | tema: detalle. Operaciones: entrevista, ingesta, consulta, revisión, decisión, estructura. Al cerrar una sesión de trabajo, agrega una entrada con lo hecho, los IDs creados o modificados y lo pendiente.

Fuentes de evidencia

  • sources/ contiene material de origen (golden set de planes de estudio, normativa, etc.) con la estructura sources/<ámbito>/<tipo>/. Es de solo lectura: no lo edites, no lo muevas, no lo reorganices. La única excepción es la ficha SRC-* de cada conjunto, que sí puedes crear y mantener.
  • No derives requisitos de la estructura de datos de una fuente. Úsala como evidencia de casos y marca como supuesto cualquier cosa que solo aparezca ahí.
  • No abras el contenido de los archivos de sources/ salvo que Rafael lo pida explícitamente. Puedes listar nombres y tamaños para completar la ficha.
  • Los artefactos que se apoyen en una fuente la citan por su ID SRC en “Trazabilidad”.

Git

  • Conventional Commits en español (docs: agregar reglas de prelacion de planes de estudio).
  • No se sube .obsidian/ ni private/.