Kansodata Databricks Authoring

Estado actual: v0.1.1 (authoring-only).

Qué es este repositorio

Repositorio base para definir y operar el skill Kansodata Databricks Authoring (/kansodata-databricks-authoring), orientado a creación y refactorización de artefactos de análisis para Databricks sin ejecución ni persistencia.

Problema que resuelve

Estandariza cómo pasar de requerimientos en lenguaje natural a propuestas técnicas revisables (SQL y notebooks fuente), con límites de seguridad claros y salida estructurada para revisión humana.

Qué hace el skill

• Genera SQL analítico y de exploración:
  • SELECT
  • WITH ... SELECT
  • JOIN
  • agregaciones
  • funciones ventana
  • filtros
• Refactoriza SQL existente para mejorar legibilidad y mantenibilidad.
• Genera notebooks base en formato fuente para Databricks:
  • notebook SQL
  • notebook Python / PySpark
• Refactoriza notebooks existentes como texto.
• Documenta consultas SQL para revisión técnica/funcional (document_query).
• Entrega salida estable en 6 secciones:
  1. Resumen
  2. Supuestos
  3. Propuesta principal
  4. Validaciones recomendadas
  5. Riesgos o límites
  6. Siguiente acción recomendada

Qué no hace

• No ejecuta SQL.
• No guarda queries en Databricks.
• No crea ni modifica notebooks en Databricks.
• No usa APIs de Workspace, Queries, Jobs o Repos.
• No descubre esquemas automáticamente por API.
• No incorpora side effects.
• No se integra con plugins en v0.1.0.

Principios de diseño

• Clean Code: cambios pequeños, legibles y auditables.
• Arquitectura limpia y escalable: separación authoring vs ejecución.
• Hardening: mínimo privilegio, fail-closed ante ambigüedad crítica.
• Método Ralph (alineado con política global operativa): análisis primero, alcance explícito, rollback obligatorio, verificación real.

Relación futura con plugins

Este repo no implementa plugins. En evolución futura, este skill podrá conectar con:

• plugin de queries guardadas
• plugin de notebooks/workspace

Esos componentes serán repos/módulos separados para mantener aislamiento de riesgo y evitar mezclar authoring con ejecución/persistencia.

Estructura del repositorio

• README.md
• CHANGELOG.md
• package.json
• AGENTS.md
• CONTRIBUTING.md
• skills/kansodata-databricks-authoring/SKILL.md
• docs/architecture.md
• docs/authoring-decision-flow.md
• docs/contract-coverage-matrix.md
• docs/distribution-contract.md
• docs/publish-playbook.md
• docs/rejection-and-degradation-guide.md
• docs/release-checklist.md
• docs/versioning-policy.md
• docs/scope.md
• docs/rollback.md
• docs/examples.md
• .gitignore
• .github/

Ejemplos de uso del skill

Ver docs/examples.md.

Cobertura contractual

Ver docs/contract-coverage-matrix.md.
Esta matriz se usa para revisar consistencia entre contrato (SKILL.md) y ejemplos, y para detectar regresiones documentales antes de fusionar cambios.
Debe consultarse en PRs que toquen modos operativos, confianza de esquema, madurez de salida o plantillas canónicas.

Guía de degradación y rechazo

Ver docs/rejection-and-degradation-guide.md.
Debe consultarse cuando una solicitud esté fuera de alcance o tenga confianza insuficiente, para decidir entre continuar, degradar o rechazar sin romper authoring-only.
Esta guía refuerza redacción segura y evita lenguaje que sugiera ejecución automática real.

Flujo de clasificación

Ver docs/authoring-decision-flow.md.
Debe consultarse cuando se necesite clasificar una solicitud en modo operativo, nivel de confianza y estado de madurez de forma consistente.
Este flujo ayuda a decidir cuándo degradar o rechazar sin reabrir el alcance authoring-only.

Navegación normativa

Para navegar sin fricción entre contrato, alcance, clasificación y decisiones de riesgo, usar esta secuencia:
skills/kansodata-databricks-authoring/SKILL.md → docs/scope.md → docs/authoring-decision-flow.md → docs/rejection-and-degradation-guide.md → docs/contract-coverage-matrix.md.

Release readiness

Ver docs/release-checklist.md.
Debe consultarse antes de publicar una iteración documental para confirmar consistencia normativa, ausencia de claims de runtime real y reversibilidad del cambio.
Esta guía funciona como control previo de distribución sin ampliar alcance funcional.

Ejecución de publicación manual

Ver docs/publish-playbook.md.
Define prechecks, secuencia de npm publish, verificación posterior y preparación prudente para ClawHub sin sobreprometer capacidades runtime.

Versionado y trazabilidad

Ver docs/versioning-policy.md y CHANGELOG.md.
Estos documentos definen cuándo corresponde major/minor/patch, qué cambios no deben salir como release y cómo registrar cada publicación de forma auditable.

Contrato de distribución

Ver docs/distribution-contract.md.
Debe consultarse al preparar publicación pública para mantener claims permitidos/prohibidos y posicionamiento correcto del skill frente a plugins/runtime tools.
Este contrato evita promesas de ejecución real y mantiene el alcance authoring-only.

Identidad de paquete

Paquete público objetivo: @kansodata/kansodata-databricks-authoring.
Este artefacto distribuye documentación/skill authoring-only; no es plugin runtime y no ejecuta operaciones en Databricks.

Roadmap corto

1. v0.1.x: endurecer políticas de salida y ampliar ejemplos de edge cases.
2. v0.2.0: plantillas de validación semántica de SQL/notebooks (sin ejecución).
3. v0.3.0+: definir contrato de integración con plugins externos (manteniendo separación de responsabilidades).

Postura de seguridad / hardening

• Salida no mutante por defecto.
• Sin DDL/DML destructivo por defecto.
• Supuestos explícitos cuando faltan metadatos.
• Rechazo o degradación segura ante solicitudes de alto riesgo.
• Preparado para revisión humana obligatoria antes de cualquier ejecución externa.

Contribuciones

• Las contribuciones externas se realizan por rama + Pull Request hacia main.
• No se aceptan cambios directos a main.
• La trazabilidad oficial de aportes vive en el flujo nativo de GitHub: commits, PRs, historial y contributors.
• Ver lineamientos en CONTRIBUTING.md.