grafana / grafana/interactive-tutorials

Spike: Pathfinder guide health — investigate and troubleshoot learning path failures

Open
#552 4 comments 0 reactions 1 assignee Claimed by @tacole02 View on GitHub
lh-learning-path
Dominant language
HTML
Stars
13
Forks
8
Avg merge
2d 4h
Merged PRs (30d)
45

Description

## Summary

Spike to investigate and troubleshoot learning path failures surfaced in the [Pathfinder guide health overview dashboard](https://ops.grafana-ops.net/d/lehqn6p/pathfinder-guide-health-overview?from=now-6h&to=now&timezone=browser).

Compare two investigation approaches: manual deep-dive on a small set of paths, and batch investigation using gcx on a larger group.

## Goal

- Understand which reported failures are real guide/content issues vs. test infrastructure noise (especially MCP Playwright failures).
- Fix or document root causes for a representative sample of failing learning paths.
- Capture process notes, friction, and recommendations for scaling guide-health triage.

## Out of scope

- **Do not test or triage guides that depend on data sources.** These fail for external reasons (connectivity, credentials, third-party endpoints) and are not actionable in this spike.
- When selecting paths from the dashboard, skip or exclude learning paths whose failures trace to data-source setup/health steps.

## Investigation methods

### Method 1 — Manual (1–2 learning paths)

Pick 1–2 failing learning paths from the dashboard (non–data-source failures). For each:

1. Record package ID, failing step/milestone, and dashboard error signal.
2. Reproduce manually on `learn.grafana.net` (Block Editor smoke test and/or walk-through).
3. Reproduce with Playwright MCP if applicable; note whether MCP alone fails while manual passes.
4. Classify the failure (see below) and fix if the root cause is in `interactive-tutorials`, or file/link a follow-up if upstream (Pathfinder app, Grafana UI, infra).
5. Open a PR for any fixes, or document why no PR is needed.

### Method 2 — gcx batch (~5 paths, up to 10)

Select ~5 failing learning paths from the dashboard (same exclusions). Widen to ~10 if Method 1 leaves capacity.

1. Run batch investigation using **gcx** (document exact commands/workflow used).
2. For each path: capture gcx output, failure classification, and whether gcx matched manual/Playwright results.
3. Note setup time, ease of use, false positives/negatives, and where gcx did or did not help vs. manual triage.

## Documentation

See https://docs.google.com/spreadsheets/d/1qVqYzqKma9DLZfRtSl9c-qxboYUsYc1FrPkrtBkqR-8/edit?usp=sharing

## Acceptance criteria

- [ ] At least 1–2 learning paths investigated manually with classification documented
- [ ] ~5 learning paths investigated via gcx (up to 10 if scope widened), with comparison to manual results where overlap exists
- [ ] This issue updated with process notes, findings, and any PR/issue links

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.