autogen-guide-dashboard

# AutoGen Guide from Dashboard JSON Generate an interactive guide `content.json` by analyzing a Grafana dashboard JSON export. This skill orchestrates a multi-phase pipeline where **each phase runs in a sub-agent that loads only the context it needs**. The orchestrator (you) manages the workflow, user interactions, and handoffs. **Do NOT read external reference files upfront.** Each phase's sub-agent loads its own references. Everything the orchestrator needs is inline below. **Maintenance mode**: If you are being asked to maintain or update an existing guide (not create one from scratch), read `dashboard-maintenance-flow.md` in this skill directory and follow the maintenance workflow instead of the full generation pipeline below. --- ## Workflow Overview ``` Input (Dashboard JSON) │ ├─ Phase 1: Acquire & Scope ────── orchestrator (no external reads) │ Runs: extract_dashboard.py → assets/dashboard-extraction.json │ Output: dashboard JSON parsed, scope confirmed by user │ Writes: {guide_dir}/assets/dashboard-source.json │ {guide_dir}/assets/dashboard-extraction.json │ ├─ Phase 2: Extract & Assess ───── sub-agent loads dashboard-extraction-patterns.md │ │ + dashboard-selector-strategies.md │ │ + dashboard-guide-rules.md (references shared/critical-rules.md) │ │ + reads assets/dashboard-extraction.json │ Writes: {guide_dir}/assets/extraction-report.md │ ├─ Checkpoint: Plan ────────────── orchestrator builds plan, user confirms │ Writes: {guide_dir}/assets/guide-plan.md │ ├─ Checkpoint: Package Metadata ── orchestrator gathers manifest fields from user │ Writes: {guide_dir}/assets/package-metadata.json │ ├─ Phase 3: Generate Guide ──────── per-section sub-agents, each loads authoring-guide.mdc │ │ + dashboard-guide-rules.md │ │ + receives structured panel data from dashboard-extraction.json │ │ 3.1 Create guide shell (orchestrator) │ │ 3.2 For each section → sub-agent generates section JSON (parallel) │ │ 3.3 Assemble via assemble_guide.py → content.json (with validation) │ │ 3.4 Generate assets/selector-report.md (orchestrator) │ Writes: {guide_dir}/content.json + {guide_dir}/assets/selector-report.md │ ├─ Phase 4: Review & Fix ──────── sub-agent loads review-guide-pr.mdc │ │ + dashboard-guide-rules.md │ Writes: fixed content.json + change report │ ├─ Phase 5a: Write Skill Memory ── orchestrator │ Writes: {guide_dir}/assets/manifest.yaml │ ├─ Phase 5b: Generate Package Manifest ── orchestrator │ Runs: generate_manifest.py → {guide_dir}/manifest.json │ └─ Phase 6: Validate Package ──── orchestrator Runs: assemble_guide.py --validate-only + optional CLI validate --package ``` --- ## Critical Rules 22 rules govern all generated guides. Sub-agents load them from `dashboard-guide-rules.md`. Key rules the orchestrator must know: - Rule 16: no navigation steps (user is already on the dashboard) - Rule 17: no contextual preamble - Rule 21: guided steps must include `description` - Rule 22: no noop-only sections Full rules, golden examples (A–G), action decision tree, selector patterns, and the lazy-rendering CRITICAL section are all in `dashboard-guide-rules.md`. --- ## Generated Files The skill writes analysis artifacts into an `assets/` subdirectory inside the guide directory. The deliverable (`content.json`) stays at the top level. Only `content.json` is consumed by the Pathfinder plugin; everything in `assets/` is skill-internal context. ``` {guide_dir}/ content.json ← the deliverable (Pathfinder guide) manifest.json ← the package manifest (generated in Phase 5b) assets/ dashboard-source.json ← input dashboard JSON snapshot dashboard-extraction.json ← structured extraction from extract_dashboard.py extraction-report.md ← panel analysis, selectors, grades guide-plan.md ← section structure and panel assignments selector-report.md ← selector quality assessment package-metadata.json ← manifest fields gathered at Package Metadata checkpoint manifest.yaml ← provenance, drift detection, skill memory ``` ### Frontmatter disclaimer Every generated markdown file in `assets/` **must** start with the standard frontmatter from the skill-memory convention (`.cursor/skills/skill-memory.md`), extended with dashboard-specific fields: ```markdown --- disclaimer: Auto-generated by autogen-guide-dashboard skill. Do not edit manually. notice: To regenerate, re-run the skill against this dashboard. input_sha256: {sha256 of panel/variable fields} dashboard: {uid} dashboardTitle: {title} --- ``` Compute `input_sha256` using the targeted hash (see **Manifest file** section below). ### Manifest file After all phases complete, write `{guide_dir}/assets/manifest.yaml`: ```yaml # Auto-generated by autogen-guide-dashboard skill. Do not edit manually. schema_version: 1 skill_name: "autogen-guide-dashboard" generated_at: "{ISO 8601 timestamp}" input_sha256: "{hex digest — see below}" dashboard: uid: "{uid}" title: "{title}" schema_version: {schemaVersion} panel_count: {N} guide: id: "{guide_id}" sections: - "{section-id-1}" - "{section-id-2}" total_steps: {N} selector_quality: green: {N} yellow: {N} red: {N} panels: - {title: "{panel title}", type: "{panel type}", y: {gridPos.y}} files: dashboard_source: "assets/dashboard-source.json" extraction_report: "assets/extraction-report.md" guide_plan: "assets/guide-plan.md" selector_report: "assets/selector-report.md" ``` Compute `input_sha256` by hashing only the fields that signal meaningful dashboard drift, not the full JSON (which changes on cosmetic edits like time range defaults): ```bash jq -c '{panels: [.panels[] | {title, type, gridPos}], templating: [.templating.list[] | {name, type}]}' {guide_dir}/assets/dashboard-source.json | shasum -a 256 ``` Use the hex digest as `input_sha256`. This manifest is the entry point for maintenance runs. See `dashboard-maintenance-flow.md`. --- ## External Dependencies This skill reads two files **outside** its own directory. If they are moved or renamed, sub-agent phases will fail silently: - `.cursor/authoring-guide.mdc` — block types, action types, requirements (read by Phase 3 section sub-agents) - `.cursor/review-guide-pr.mdc` — complete review protocol (read by Phase 4 review sub-agent) This skill implements the **skill-memory convention**. See `.cursor/skills/skill-memory.md` for the shared `assets/`, manifest, and frontmatter standards that this skill extends. --- ## Phase 1: Acquire and Scope (Orchestrator) You handle this phase directly. No sub-agent needed. ### 1.1 Parse the Input The user provides dashboard JSON via one of: - **File path**: local path to a `.json` file - **Pasted JSON**: raw JSON in the conversation - **Grafana API URL**: `https://<instance>/api/dashboards/uid/<uid>` - **Dashboard URL**: `https://<instance>/d/<uid>/<slug>?...` (derive API URL from this) If given a dashboard URL, extract the UID (the path segment immediately after `/d/`) and strip any query parameters or trailing slug: ``` Dashboard URL: https://play.grafana.org/d/vmie2cmWz/bar-gauge?orgId=1&from=now-6h&to=now ^^^^^^^^^^ UID API URL: https://play.grafana.org/api/dashboards/uid/vmie2cmWz ``` ### 1.2 Load the Dashboard JSON - **File path**: read the file directly; copy it to `{guide_dir}/assets/dashboard-source.json`. - **Pasted JSON**: save to `{guide_dir}/assets/dashboard-source.json` for reference. - **Dashboard URL or API URL**: fetch via curl as shown below. #### Fetching from a URL Extract the UID from the dashboard URL and run: ```bash curl -sf "https://<instance>/api/dashboards/uid/<uid>" | jq '.dashboard' > {guide_dir}/assets/dashboard-source.json ``` The Grafana REST API wraps the dashboard model inside `{"dashboard": {...}, "meta": {...}}`. The `jq '.dashboard'` step unwraps it so the file contains the raw dashboard JSON with `panels`, `title`, `uid`, etc. at the top level. If `jq` is not available, fetch without piping and manually read the `.dashboard` key from the response. **Authentication limitation**: This curl approach only works for **unauthenticated / anonymous-access Grafana instances** (e.g., play.grafana.org). If the instance is protected by password auth, Okta, SAML, OAuth, or any other login mechanism, the curl will fail with a 401/403 or return an HTML login page instead of JSON. **Do not attempt to resolve authentication issues.** Instead, tell the user: > "This Grafana instance requires authentication, so I can't fetch the dashboard JSON directly. Please export the dashboard JSON yourself: > 1. Open the dashboard in your browser > 2. Click the **Share** icon (or go to Dashboard settings → JSON Model) > 3. Copy the JSON and paste it here, or save it to a file and give me the path." After fetching or receiving the JSON, validate it has the expected top-level keys: `panels` (or `rows` for legacy format), `templating`, `title`, `uid`. If you see HTML or an `{"error": ...}` response instead, the fetch failed — fall back to asking the user to provide the JSON manually as described above. ### 1.3 Run Extraction Script After loading the dashboard JSON, run the extraction script to produce a structured analysis: ```bash python .cursor/tools/extract_dashboard.py {guide_dir}/assets/dashboard-source.json > {guide_dir}/assets/dashboard-extraction.json ``` The script outputs panels with selector grades, fold positions, variable bindings, rows, data sources, duplicate title detection, and the drift hash. Use this structured output for all subsequent phases — sub-agents receive the extraction JSON instead of parsing raw dashboard JSON. ### 1.4 Assess Scope Use the extraction script's output to present scope to the user: > "This dashboard contains {N} panels across {R} rows, with {V} template variables and {D} data sources. Selector quality: {G} Green, {Y} Yellow, {R} Red. This will produce a guide with approximately {S} sections and {T} steps. Should I proceed?" Scope guidelines by panel count: - **< 3 panels**: Too small for a guide. Suggest combining with another dashboard or expanding scope. - **3–6 panels**: Small dashboard. Expect 8–15 total steps across 1–2 sections. Do not pad to hit higher targets. - **7–12 panels**: Good scope for one guide with 2–4 sections. - **12–25 panels**: Large. Consider splitting by row or logical grouping. - **> 25 panels**: Must split. Suggest one guide per row group or logical theme. ### 1.5 Identify Dashboard Metadata Extract from the JSON: - `uid` and `title` -- for guide ID and title - `schemaVersion` -- for format compatibility - URL path: `/d/<uid>/<slug>` -- for `on-page:` requirements - `tags[]` -- context for guide description ### 1.6 Create the Guide Directory Create `{guide-id}/` in the workspace root and `{guide-id}/assets/` for generated analysis files. The `guide-id` should be kebab-case, derived from the dashboard title (e.g., `performance-stats-tour`, `k8s-cpu-dashboard`). Proceed to Phase 2 after the user confirms scope. --- ## Phase 2: Extract & Assess (Sub-Agent) Launch a sub-agent using the Task tool. This sub-agent loads the dashboard-specific extraction and selector references, analyzes the JSON, and writes a structured report. ### Sub-agent prompt template Before launching the sub-agent, the orchestrator has already run `extract_dashboard.py` (Phase 1.3). The sub-agent receives the structured extraction JSON as context and its job shifts to **interpreting** the extraction — building section groupings, writing educational annotations, and producing the prose extraction report. Fill in `{placeholders}` and pass as the Task prompt: ``` You are analyzing a Grafana dashboard JSON export to produce an extraction report for a Pathfinder guide. **Read these reference files first:** 1. `.cursor/skills/autogen-guide-dashboard/dashboard-extraction-patterns.md` -- panel types, row detection, variable extraction, data source mapping 2. `.cursor/skills/autogen-guide-dashboard/dashboard-selector-strategies.md` -- selector patterns for panels, rows, variables; grading model 3. `.cursor/skills/autogen-guide-dashboard/dashboard-guide-rules.md` -- critical rules (including shared/critical-rules.md rules 1-15), golden examples, action decision tree, lazy rendering **Pre-computed dashboard extraction** (read this file — panel selectors, grades, fold positions, variable bindings, and drift hash are already computed): {guide_dir}/assets/dashboard-extraction.json **Raw dashboard JSON for context** (read this file for query expressions, thresholds, legends, and educational content): {guide_dir}/assets/dashboard-source.json **Your task:** 1. Read dashboard-extraction.json — panel inventory, selector grades, fold positions, variable bindings, and duplicate title detection are already computed; DO NOT re-grade or re-count from scratch 2. Interpret the extraction: build section groupings (by row or logical theme), annotate panels with educational context from the raw dashboard JSON (query expressions, thresholds, legends) 3. Identify the recommended guide treatment for each panel (which golden example applies, per the Action Decision Tree) 4. Note any transformations or overrides that affect panel behavior 5. Flag any selector concerns (variable-interpolated titles, duplicate titles, below-fold panels) **Write your results** to `{guide_dir}/assets/extraction-report.md` using the standard frontmatter and `## Extraction Report Template` structure from `dashboard-extraction-patterns.md`. **Return** a brief summary: row/section count, panel count, variable count, selector quality breakdown, and any concerns. ``` After the sub-agent completes, present the extraction report summary to the user. --- ## Checkpoint: Build the Guide Plan (Orchestrator) After the user sees the extraction report, build a structural plan. Read `{guide_dir}/assets/extraction-report.md` and produce `{guide_dir}/assets/guide-plan.md`. Use the `## Guide Plan Template` structure from `dashboard-extraction-patterns.md`, prefixed with the standard frontmatter disclaimer. **Present the plan to the user.** Let them adjust section order, add/remove sections, or change emphasis. Confirm the panel groupings before proceeding. --- ## Checkpoint: Package Metadata (Orchestrator) Before generating guide content, gather package metadata from the user. Present defaults where possible and ask for confirmation or overrides. **Auto-derived (confirm with user):** - `id`: {guide-id from plan} - `description`: {1-line summary derived from extraction report} - `type`: "guide" **Requires user input (with auto-suggestions):** - `category`: What category does this guide belong to? Suggest based on context (e.g., "data-availability" for datasource guides, "general" as fallback). - `startingLocation`: Where in Grafana does this guide launch? Auto-derive from dashboard URL path: `/d/{uid}/{slug}`. - `targeting.match`: Where should this guide be recommended? Suggest `{ "urlPrefix": "/d/{uid}" }` from the dashboard UID. Present the suggestion and ask the user to confirm or customize. - `testEnvironment`: Where should this guide be tested? - If source was play.grafana.org: suggest `{ "tier": "cloud", "instance": "play.grafana.org" }` - Otherwise: suggest `{ "tier": "cloud" }` as minimum default. - `author.team`: Default "interactive-learning". Ask if different. Store the confirmed metadata in `{guide_dir}/assets/package-metadata.json` for use in Phase 5b manifest generation. ```json { "contentJsonPath": "{guide_dir}/content.json", "type": "guide", "description": "...", "category": "...",