bi-superpowers 1.0.0

package/src/content/routing.md

@@ -0,0 +1,201 @@
+# Skill Routing Priority System
+
+This document defines the order in which skills are evaluated and activated by the AI agent.
+
+## Priority Levels
+
+| Priority | Type | Description |
+|----------|------|-------------|
+| 0 | **Explicit** | User typed `/skill-name` directly |
+| 1 | **First-run** | Auto-suggest for new users |
+| 2 | **Context** | Based on detected files in project |
+| 3 | **Keyword** | Match user message against triggers |
+| 4 | **General** | Default assistant behavior |
+
+---
+
+## Routing Logic
+
+## BI Skill-First Routing
+
+Before acting on any BI-related request, classify the user's intent against the
+nine shipped BI skills. If one skill clearly matches, follow that skill before
+giving implementation advice or taking action. This is skill-first for BI
+intents, not a dependency on a general-purpose skill framework.
+
+Do not force skill routing for unrelated, administrative, or simple non-BI
+questions. The goal is to prevent ad hoc Power BI work, not to add ceremony to
+every conversation.
+
+### BI skill precedence
+
+Use this order when more than one BI skill could apply:
+
+| Priority | Skill | Use first when |
+|----------|-------|----------------|
+| 1 | `/bi-start` | The user asks for orientation, "what can you do?", or a session opener |
+| 2 | `/bi-connect` | The request is about MCP setup, Power BI Desktop connection, DAX UDFs, or DAXLIB |
+| 3 | `/bi-kickoff` | The user is starting a new BI project from scratch |
+| 4 | `/bi-refactor` | The user has an existing PBIP/PBIX to diagnose, migrate, repair, or clean up |
+| 5 | `/bi-modeling` | The request is about semantic model shape, relationships, Date Table, RLS, or model health |
+| 6 | `/bi-performance` | The symptom is slow/large/expensive and no measured bottleneck exists yet |
+| 7 | `/bi-dax` | The user has a concrete DAX measure, calculation group, or formula-level issue, especially with a baseline |
+| 8 | `/bi-powerquery` | The request is about Power Query/M staging or Demo/Real data appends |
+| 9 | `/bi-scorecard` | The request is about Power BI Service scorecards, goals, targets, owners, cadence, or check-ins |
+
+### Examples
+
+| User intent | Route |
+|-------------|-------|
+| "conectá Power BI" | `/bi-connect` |
+| "arranco un proyecto nuevo" | `/bi-kickoff` |
+| "arreglá este PBIP existente" | `/bi-refactor` |
+| "auditá el modelo" | `/bi-modeling` |
+| "la página está lenta" | `/bi-performance` |
+| "esta medida DAX da mal" | `/bi-dax` |
+| "conectar mis datos reales con Power Query" | `/bi-powerquery` |
+| "armar objetivos con owners y metas" | `/bi-scorecard` |
+| "traducime este texto" | No BI skill; respond normally |
+
+### 1. CHECK EXPLICIT COMMAND
+
+If user message starts with "/" and matches a skill name:
+- Activate that skill immediately
+- Skip all other checks
+
+### 2. CHECK FIRST-RUN CONDITION
+
+Check `config.json` for first-time user:
+
+```
+If config.isFirstSetup == true AND
+   config.hasRunProjectKickoff == false AND
+   config.skillPreferences.autoSuggestProjectKickoff == true:
+
+→ Show welcome message and suggest /bi-kickoff
+```
+
+**Suggested message:**
+```
+Welcome to BI Agent Superpowers! I noticed this is your first time here.
+
+To get the most out of this toolkit, I recommend starting with
+the **Project Kickoff** wizard (/bi-kickoff).
+
+Would you like to start? (yes/no)
+```
+
+### 3. CHECK PROJECT CONTEXT
+
+Scan current directory for relevant files:
+
+| Files Detected | Suggested Skill |
+|----------------|-----------------|
+| `.pbix` / `.pbip` / `.tmdl` files (existing project) | `/bi-refactor` |
+| `.xlsx` / `.xlsm` files (no model yet) | `/bi-kickoff` |
+| Agent MCP config missing when user asks about Power BI | `/bi-connect` |
+
+### 4. CHECK KEYWORDS
+
+Match user message against skill triggers:
+
+| Keywords | Skill |
+|----------|-------|
+| "bi-start", "start session", "empezar", "what can you do here?" | `/bi-start` |
+| "kickoff", "analyze project", "analizar proyecto", "qué tengo aquí?" | `/bi-kickoff` |
+| "modelar", "modelo semántico", "semantic model", "star schema", "relaciones", "RLS", "Date Table" | `/bi-modeling` |
+| "DAX", "medida", "calculation group", "filter context", "optimizar medida", "Sallieri" | `/bi-dax` |
+| "performance", "rendimiento", "lento", "VertiPaq", "BPA", "refresh tarda", "página lenta" | `/bi-performance` |
+| "connect Power BI", "MCP connection", "Power BI Desktop", "conectar Power BI", "modeling mcp", "DAX UDF", "functions.tmdl", "DAXLIB" | `/bi-connect` |
+| "Power Query", "M query", "M script", "append real data", "Demo/Real", "Data = Real", packaged Andina Nexus `*_Real` targets such as "Ventas_Real", "Servicios_Real", "Proyectos_Real", "Movimientos financieros_Real", "Nómina_Real", "conectar datos reales al modelo" | `/bi-powerquery` |
+| "scorecard", "scorecards", "Power BI Metrics", "Power BI Goals", "goals API", "scorecards API", "objetivos", "targets", "metas", "KPI owner", "cadencia", "check-in", "status rules" | `/bi-scorecard` |
+| "refactor Power BI", "refactorizar Power BI", "modelo existente", "existing PBIP", "reparar visuales", "limpiar modelo" | `/bi-refactor` |
+
+### 5. DEFAULT BEHAVIOR
+
+No skill activated → respond as a general BI assistant using AGENTS.md context and the installed BI Superpowers skills. Do not reference `library/` snippets unless the user's project actually contains that folder.
+
+---
+
+## Skill Conflict Resolution
+
+If multiple skills match:
+
+1. **Explicit command always wins** — `/skill-name` overrides everything
+2. **Context + keyword same skill** → Activate immediately
+3. **Context + keyword different skills** → Ask user which they prefer
+4. **Never activate multiple wizard-style skills** simultaneously
+
+---
+
+## Config-Based Customization
+
+Users can customize routing in `config.json`:
+
+```json
+{
+  "skillPreferences": {
+    "autoSuggestProjectKickoff": true,
+    "disabledSkills": [],
+    "defaultSkill": null
+  }
+}
+```
+
+| Setting | Effect |
+|---------|--------|
+| `autoSuggestProjectKickoff: false` | Disable first-run auto-suggestion |
+| `disabledSkills: ["bi-connect"]` | Never suggest these skills |
+| `defaultSkill: "bi-kickoff"` | Suggest this skill when context is ambiguous |
+
+---
+
+## Available Skills (9)
+
+| Skill | Purpose | Typical Duration |
+|-------|---------|-----------------|
+| `/bi-start` | Start a session, show the skill menu, check updates, and route to a specialist | 1-2 min |
+| `/bi-kickoff` | Start a new BI project from `base-template`, build the semantic model, and write AGENTS.md | 10-20 min |
+| `/bi-refactor` | Diagnose and clean up an existing PBIP/PBIX project: template-assisted diagnosis, semantic cleanup via MCP, report topology preserved | 15-45 min |
+| `/bi-modeling` | Design and audit semantic models, relationships, and template migrations | 10-30 min |
+| `/bi-dax` | Author, explain, debug, and optimize DAX measures and calculation groups | 5-30 min |
+| `/bi-performance` | Profile model/report performance, VertiPaq size, BPA, and refresh issues | 10-45 min |
+| `/bi-connect` | Connect to Power BI Desktop via the official Microsoft MCP; guide DAX UDF authoring with Microsoft Learn + DAXLIB references | 2-10 min |
+| `/bi-powerquery` | Create strict Power Query staging queries for real data and append them to the current model's Demo/Real business tables | 10-30 min |
+| `/bi-scorecard` | Create Power BI Service scorecard blueprints from model metrics and manage goals, check-ins, and status rules | 10-30 min |
+
+---
+
+## Workflow Chains
+
+After completing a skill, suggest the logical next step:
+
+| After Completing | Suggest Next |
+|-----------------|--------------|
+| `/bi-kickoff` (MCP not connected) | `/bi-connect` to set up the connection |
+| `/bi-connect` | Back to `/bi-kickoff` if the project hasn't been analyzed yet |
+| `/bi-powerquery` staging ready | Refresh/apply the generated M in Power BI Desktop, then validate the `Data` filter behavior |
+| `/bi-scorecard` blueprint created | Power BI Service to bind current/target values to report visuals when first-time connected values are needed |
+
+**Suggestion format:**
+```
+Great work! Based on what we just completed, you might want to:
+→ /next-skill — Brief reason why it's a natural next step
+
+Would you like to continue with that?
+```
+
+---
+
+## Updating After Project Kickoff
+
+After user completes `/bi-kickoff`, update config:
+
+```json
+{
+  "hasRunProjectKickoff": true,
+  "isFirstSetup": false
+}
+```
+
+This prevents repeated auto-suggestions.