autogen-guide-dashboard

name	autogen-guide-dashboard
description	Generate interactive guide content.json files from Grafana dashboard JSON. Analyzes dashboard panels, variables, rows, and data sources to produce a Pathfinder guide that tours or explains a dashboard. Use when the user provides dashboard JSON (file, pasted, or Grafana API URL) and wants to create a guide from it.

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:

---
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:

# 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):

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:

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:

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.

{
  "contentJsonPath": "{guide_dir}/content.json",
  "type": "guide",
  "description": "...",
  "category": "...",
  "author": { "team": "interactive-learning" },
  "startingLocation": "/d/{uid}/{slug}",
  "targeting": { "match": { "urlPrefix": "/d/{uid}" } },
  "testEnvironment": { "tier": "cloud" }
}

---

Phase 3: Generate Guide (Per-Section Sub-Agents)

Generate the guide section by section. This keeps each sub-agent's context small and focused.

3.1 Orchestrator: Create the Guide Shell

Write the initial {guide_dir}/content.json with root structure and intro markdown. The intro should be 1–2 sentences max — never mention the dashboard name, instance, or URL (the user already knows where they are). Jump straight to what the guide covers.

{
  "id": "{guide_id}",
  "title": "{guide_title}",
  "blocks": [
    {
      "type": "markdown",
      "content": "{1–2 sentences: what the guide covers and what the user will learn — no dashboard name, no instance name, no preamble}"
    }
  ]
}

3.2 For Each Section: Launch a Sub-Agent

Iterate through the sections in {guide_dir}/assets/guide-plan.md. Launch all section sub-agents in parallel — each section is independent and has no dependency on other section outputs. Send a single message with multiple Task tool calls, one per section, and wait for all to complete before proceeding to assembly (3.3).

Step budget: aim for 3–8 interactive steps per section. A complete dashboard guide should have 8–40 interactive steps total depending on dashboard size (small dashboards with 3–6 panels are fine at 8–15 steps; do not pad with unnecessary noops to reach a higher count). If a section has more panels than the budget allows, prioritize the most important ones and mention the rest in the intro or summary markdown.

Targeting vs noop steps: The step budget counts all interactive steps, but distinguish between targeting steps (those with a reftarget — highlights, buttons, guided steps) and noop steps (informational, no DOM targeting). A section must have at least 1 targeting step. If a planned section would contain only noop steps (e.g., all panels are below-fold Red-grade), do not emit it as a standalone section — instead merge its noop blocks into the preceding section's tail (after that section's summary markdown but before the section closing).

Per-section sub-agent prompt template

Fill in {placeholders} and launch via the Task tool:

You are generating ONE section of a Pathfinder interactive guide for a Grafana dashboard as a JSON object.

**Read these reference files first:**
1. `.cursor/authoring-guide.mdc` -- block types, action types, requirements, best practices
2. `.cursor/skills/autogen-guide-dashboard/dashboard-guide-rules.md` -- critical rules, golden examples, action decision tree, selector patterns, lazy rendering

**Section to generate:**
- Section ID: {section_id}
- Section title: {section_title}
- Requirements: {section_requirements_array}
- Objectives: {section_objectives_array_or_none}
- Row expand needed: {yes_no}
- Variables relevant to this section: {variable_list_or_none}

**Panel JSON context** (the panels in this section):
```json
{panel_json_array_for_this_section}

Variable definitions (template variables referenced by these panels):

{variable_definitions_json}

Golden examples to follow: {list the matching example letters, e.g. "A, G" or "C, D, G"}

Step budget: Generate 3–8 interactive steps for this section, with at least 1 targeting step (a step with a reftarget — highlight, button, or guided). If ALL panels in the section would be noop (e.g., all below-fold Red-grade), report this in your summary so the orchestrator can merge this section into an adjacent one. If the section has more panels than the budget allows, prioritize the most important ones and mention the rest in the intro or summary markdown.

Your task:

1. Return a single JSON object: {"type": "section", "id": "{section_id}", ...}
2. First block: brief intro markdown (what the user will explore in this section)
3. If a row needs expanding, that's the first interactive step
4. Generate steps for each key panel per the action decision tree
5. Last block: brief summary markdown (what the user learned)
6. Return ONLY the section JSON object — no wrapper, no root structure

Also return a brief text summary: step count, any selectors you're uncertain about, any panels you omitted and why.

#### Building the panel context

For each section, provide two inputs:

1. **Structured panel data** from `{guide_dir}/assets/dashboard-extraction.json` — filter to only the panels in this section (by row or gridPos grouping). This gives the sub-agent precomputed selectors, grades, fold positions, and variable bindings without re-parsing.

2. **Raw panel JSON objects** from the dashboard for educational context (query expressions, thresholds, legends). Extract from `{guide_dir}/assets/dashboard-source.json`. Trim large `targets[].expr` queries to the first 200 characters if very long.

Include the variable definitions from the extraction output that are referenced by these panels.

This two-layer approach gives the sub-agent both structural certainty (from the script) and educational richness (from the raw JSON).

#### Choosing which golden example to pass

Use the `## Golden Example Routing` table in `dashboard-guide-rules.md` to select which examples to pass for this section.

### 3.3 Orchestrator: Assemble the Guide

After all section sub-agents complete:

1. **Write each returned section JSON** to a temporary file: `{guide_dir}/assets/section-{section_id}.json`
2. **Check for noop-only sections** (before assembly): if a section has zero targeting steps (every interactive step is `noop`), merge its blocks into the preceding section's tail (after summary markdown) rather than passing it to assembly. If the noop-only section is the *first* section, merge it into the *following* section's intro instead.
3. **Add the closing summary markdown** to the shell as the final top-level block — ultra-short, 1–2 sentences max. Never recap every section or panel.
   ```json
   {
     "type": "markdown",
     "content": "{1–2 sentences: one takeaway or next step — not a recap}"
   }

4. Run the assembly script to assemble and validate:

   python .cursor/tools/assemble_guide.py \
     --shell {guide_dir}/assets/guide-shell.json \
     --sections {guide_dir}/assets/section-*.json \
     --output {guide_dir}/content.json
   

   The script validates: unique section IDs, no multistep singletons, tooltip lengths, section bookends, step counts, and no noop-only sections.
5. If validation fails: fix the flagged issues in the section JSON files and re-run.
6. Spot-check: read the first and last sections to verify structure and bookends.

3.4 Orchestrator: Generate Selector Report

After assembly, write {guide_dir}/assets/selector-report.md by collating sub-agent feedback. Start the file with the standard frontmatter disclaimer (see "Generated Files" section), then use the template from dashboard-selector-strategies.md (section "Selector Quality Report Template").

Section chaining guidance

Dashboard tour sections are almost always independent. Use chaining only in rare cases:

Relationship	Use section-completed?
Section 1 navigates to the dashboard, section 2 explores panels	No -- use on-page:/d/{uid}/{slug}
Section 1 explains variables, section 2 depends on a variable value	Rarely -- only if section 2 literally requires a specific value
Sections map to different rows on the same dashboard	No -- use on-page:/d/{uid}/{slug}
Section 1 installs prerequisites (data source, demo data)	Yes -- section 2 requires the prerequisite

---

Phase 4: Review & Fix (Sub-Agent)

Launch a sub-agent to review and fix the assembled guide.

Sub-agent prompt template

You are reviewing an auto-generated Pathfinder guide for a Grafana dashboard tour.

**Read these reference files first:**
1. `.cursor/review-guide-pr.mdc` -- complete review protocol (sections 1-4 are blocking checks)
2. `.cursor/skills/autogen-guide-dashboard/dashboard-guide-rules.md` -- rules, golden examples, and the "Review Checklist (Always Include)" section

**Then read the guide:**
3. `{guide_dir}/content.json`

**Apply every check from sections 1-4** of the review protocol against the guide JSON.
**Apply every item** from the "Review Checklist (Always Include)" in dashboard-guide-rules.md.

**Additionally check for these dashboard-specific issues:**
{tailored_items_conditional_only}

For each issue found, **fix it directly** in `{guide_dir}/content.json`.

After fixing all issues, **return a report**:
- List of issues found and how each was fixed
- Any issues that couldn't be auto-fixed (need human decision)
- Confirmation that the guide JSON is valid/parseable
- Confirmation that all section IDs are unique
- Confirmation that the requirements chain is logical
- Step count per section: total interactive steps, targeting steps (with reftarget), and noop steps — flag any section with 0 targeting steps (noop-only) or >10 total steps

Building the tailored review checklist

Before launching the review sub-agent, build {tailored_items_conditional_only} from the Phase 2 extraction report. Only include the sections that apply to this dashboard — the "always include" items are now in dashboard-guide-rules.md and the sub-agent reads them directly.

**Panel title uniqueness** (include if duplicate titles were found):
- These panels have duplicate titles: {list titles and how they're disambiguated}
- Verify nth-match indices are correct
- Verify row-scoped selectors target the right panel

**Variable-interpolated titles** (include if any panel title contains $variable):
- These panels have variable-interpolated titles: {list}
- Verify the selector accounts for the current variable value
- Consider using nth-match or row scoping instead of the interpolated title

**Variable interactions** (include if guide has variable exploration steps):
- These variables are referenced: {list names and types}
- Verify variable highlight steps use doIt: false
- Verify tooltip explains what the variable filters

**Row expand steps** (include if guide has collapsed rows):
- These rows need expanding: {list row titles}
- Verify expand step uses action: "button" with row title text
- Verify subsequent panel highlights in the row use row-scoped selectors

---

Final Delivery (Orchestrator)

After Phase 4 completes:

1. Read the review report -- check if any issues couldn't be auto-fixed

2. Validate JSON -- ensure {guide_dir}/content.json parses correctly

3. Spot-check -- read the first and last sections to verify bookends and structure

4. Write the skill memory manifest -- generate {guide_dir}/assets/manifest.yaml (Phase 5a; see "Generated Files" section for the template). Compute the dashboard SHA-256 hash and record section IDs, step counts, and selector quality from the review output.

5. Run Phase 5b -- generate the Pathfinder package manifest:

   python .cursor/tools/generate_manifest.py \
     --input {guide_dir}/assets/package-metadata.json \
     --content {guide_dir}/content.json \
     --output {guide_dir}/manifest.json
   

6. Run Phase 6 validation:

   python .cursor/tools/assemble_guide.py --validate-only {guide_dir}/content.json
   

   And if the Pathfinder CLI is available:

   node {pathfinder-app}/dist/cli/cli/index.js validate --package {guide_dir}
   

   If the CLI is not available, report this as incomplete and instruct the user to run validation manually.

7. Present to the user -- summarize what was generated:

   • Guide location: {guide_dir}/content.json
   • Package manifest: {guide_dir}/manifest.json
   • Sections: N (list names)
   • Total interactive steps: N (average per section)
   • Selector quality: N Green, N Yellow, N Red
   • Any compromises, omitted panels, or known issues
   • Review fixes applied

8. Note the manifest -- the manifest.json has been generated alongside the guide. If you need this guide to appear in contextual recommendations, verify the targeting.match rules.

9. Note selector improvements -- point the user to assets/selector-report.md for any fragile selectors

---

Optional Inputs

The user may provide additional context. Use it when available:

Input	How to Use
Guide type hint	"dashboard tour", "SRE guide" → influences plan structure and tone
Dashboard URL path	/d/abc123/my-dashboard → use in on-page: requirements
Audience	"beginners", "SREs", "platform engineers" → adjust depth and terminology
Focus panels	"focus on the latency panels" → prioritize those panels, mention others briefly
Data source type	"Prometheus", "Loki" → tailor query explanations

---

Error Handling

Dashboard JSON is not valid Grafana format

Report immediately. Validate the presence of panels (or legacy rows), title, and uid. If missing, ask the user to provide a valid Grafana dashboard JSON export.

Legacy row format (schemaVersion < 16)

Older dashboards use rows[].panels[] instead of flat panels[]. Detect via schemaVersion or the presence of rows array. Flatten to the modern format for extraction: each row becomes a section, each row's panels become top-level panels with gridPos derived from their row position.

No panel titles

Generate the guide anyway, but do not rely on :nth-match() for below-fold untitled panels. Grafana lazy-renders panels, so nth-match(N) only works when all N matching elements are in the DOM (i.e., the user has scrolled past them). Instead:

• Use noop or markdown to describe untitled panels (safest)
• For the first untitled above-fold panel, nth-match(1) in an interactive block with doIt: false is acceptable
• For below-fold untitled panels, use guided blocks with lazyRender: true if you must target them
• Include a prominent note in the extraction report about the fragile selectors

Variable-interpolated titles

Panels with titles like Details for $component produce selectors that depend on the current variable value. Flag these in the extraction report. Use row-scoped selectors or :nth-match() as fallback. The guide may need to specify a default variable value in its intro.

Very large dashboard (> 25 panels)

Stop at the first natural boundary (e.g., after the first 3 row groups). Report what was covered and what was omitted. Suggest the user split into multiple guides or narrow the focus.

Sub-agent failures

If a sub-agent returns an error or incomplete result, read its output, diagnose the issue, and either retry with adjusted parameters or handle the phase manually as a fallback.