bmc-docs-and-repos-organizer
Organiza carpetas y documentación en Calculadora-BMC, detecta huecos o docs obsoletos, mantiene índices en docs/ y READMEs, y guía flujos GitHub (ramas, PR, etiquetas). Use when the user asks to organ
SKILL.md.cursor/skills/bmc-docs-and-repos-organizer/SKILL.md
GitHubBMC Docs & Repos Organizer
Before working: Read docs/team/knowledge/DocsOrganizer.md if it exists. Reference: reference.md.
Mantiene el workspace legible para humanos y agentes: rutas predecibles, hubs enlazados, READMEs mínimos útiles y documentación alineada al código y a AGENTS.md.
Objetivos
- Clasificar — Cada tipo de conocimiento tiene un “hogar” (team vs google-sheets-module vs bmc-dashboard-modernization vs procedimientos).
- Indexar — Los hubs (
README.mdendocs/,docs/team/, submódulos) enlazan a los documentos hijos; evitar islas sin enlace ascendente. - Detectar gaps — Rutas citadas que no existen, duplicados canónico vs copia vieja, docs que contradicen
AGENTS.mdo el inventario de planillas. - GitHub — Ramas por tema (
docs/...,chore/docs-index), PRs pequeños, descripciones que enlazan a issues o aPROJECT-STATEcuando aplica.
Mapa mental del repo (Calculadora-BMC)
| Área | Ruta típica | Qué documenta |
|---|---|---|
| Equipo / runs | docs/team/ |
Estado, prompts, judge, panelsim, orientación |
| Planillas / Sheets | docs/google-sheets-module/ |
Mapeos, inventario, sync accesos |
| Dashboard UI | docs/bmc-dashboard-modernization/ |
Interface map, propuestas |
| API / operación | AGENTS.md, docs/api/, docs/procedimientos/ |
Comandos, deploy, checklists |
| Cursor | .cursor/agents/, .cursor/skills/ |
Definición de agentes y skills |
Protocolo de corrida (orden sugerido)
1. Inventario rápido
- Listar cambios recientes relevantes (git o lo que indique el usuario).
- Identificar nuevos archivos en
docs/o scripts sin mención en ningún README/hub.
2. Detección de problemas
- Enlaces rotos — Referencias
docs/...o rutas relativas inexistentes. - Doble canónico — Dos documentos que declaran la misma verdad (elegir uno canónico; el otro: redirección breve o enlace prominente).
- Obsolescencia — Términos o comandos que ya no existen en
package.json/AGENTS.md. - Secretos — Nunca documentar tokens; recordar
.env.examplecomo lugar de nombres de variables, no valores.
3. Acciones correctivas (mínimo necesario)
- Añadir o actualizar README en la carpeta afectada (3–15 líneas: propósito, enlaces abajo).
- Actualizar un hub (p. ej.
docs/team/README.mdo el README del submódulo) con una línea y enlace. - Si el cambio es grande: proponer un PR solo de docs con título claro (
docs: index …).
4. README: checklist por archivo
- Qué es esta carpeta.
- Enlaces a los 1–3 documentos más importantes.
- Dueño o convención (opcional): “canónico vs histórico”.
- No duplicar
AGENTS.mdentero; enlazarlo.
5. GitHub (cuando toque código + docs)
- Rama descriptiva; PR con descripción en oraciones completas; si el repo usa plantillas de PR, respetarlas.
- Si hay CI: cambios solo en Markdown suelen no requerir build; si se tocó
src/, recordarnpm run lint/ gates segúnAGENTS.md.
Integración con “Full team run” (plan 0→9)
- Tras pasos con muchos artefactos (5 Reporter, 5f Audit, 7 Repo Sync, 8 PROJECT-STATE), este skill puede ejecutarse como paso opcional para:
- enlazar nuevos reportes desde un índice en
docs/team/reports/o README de team; - asegurar que
MATPROMT/PROMPT-FOR-EQUIPO-COMPLETOreferencien rutas reales.
- enlazar nuevos reportes desde un índice en
No sustituye el paso 8 (Orchestrator sigue siendo quien actualiza PROJECT-STATE con la política del repo).
Handoff
- To Repo Sync — Si existen paths
BMC_DASHBOARD_2_REPO/BMC_DEVELOPMENT_TEAM_REPO, listar qué docs deben copiarse o alinearse en el repo hermano. - To Orchestrator — Lista corta de “pendientes documentales” para
PROJECT-STATE(sin editar hasta confirmación del usuario si la política lo exige). - To Mapping / Contract — Si el gap es de verdad de negocio (columnas, API), no inventar: escalar con ruta al documento canónico.
Referencias
AGENTS.mddocs/team/PROJECT-TEAM-FULL-COVERAGE.mddocs/team/INVOQUE-FULL-TEAM.md.cursor/agents/bmc-dashboard-team-orchestrator.md.cursor/agents/bmc-repo-sync-agent.md