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,listaoentregadasolo 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) oGENpara lo transversal.NNNson 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á enlog.md). El slug puede actualizarse si cambia el título, solo connode scripts/kb-rename.mjs(ver sección “Scripts de validación y mantenimiento”). El título vivo está entitle(repetido enaliases) 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 textoBR-SP-001. - Nunca renombres un artefacto con
mvoMove-Itemni editando enlaces a mano: usanode 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 entools/ni incumplimientos de trazabilidad enBRyOQ. 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>. Ejecutagit mvy 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/ysources/. Solo se reportan los artefactos dedomain/,requirements/,decisions/,questions/ypackages/.
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 sucodeen 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
mermaiddentro de la notaDIA-*es la fuente lógica para los agentes (C4 solo nivel 1C4Context). Cuando un diagrama pasa a estadoexploracionovalidada, 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 estructurasources/<ámbito>/<tipo>/. Es de solo lectura: no lo edites, no lo muevas, no lo reorganices. La única excepción es la fichaSRC-*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
SRCen “Trazabilidad”.
Git
- Conventional Commits en español (
docs: agregar reglas de prelacion de planes de estudio). - No se sube
.obsidian/niprivate/.