grafana / grafana/interactive-tutorials

Authoring: catch LP static audit rules before PR (on-page, startingLocation, rule 6)

Open
#431 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
13
Forks
8
Avg merge
2d 4h
Merged PRs (30d)
45

Description

## Problem

When converting a learning path with `/build-interactive-lj` (and related authoring), we currently lean on:

1. Live UI testing during authoring (correct for selectors / Show me / Do it)
2. Post-PR `/review-learning-path-pr` Phase 1–2 static audit

That order is backwards for **static** rules. Issues like missing `on-page`, missing milestone `startingLocation`, and markdown `##` used for grouping (AGENTS.md rule 6) should fail (or be auto-fixed) during **scaffold / lint / check**, not first appear in PR review.

Observed on PR https://github.com/grafana/interactive-tutorials/pull/430 (`grafana-cloud-onboarding-lj`): live stack testing caught real selector/UI drift; the static gaps only showed up in the post-PR audit and required a follow-up fix commit.

## Proposal

Tighten the authoring path so Phase 1–2 style checks run **before** opening a PR:

### `/build-interactive-lj` (and `/create-learning-path`)
- Scaffold checklist must require:
- `exists-reftarget` + `on-page` for page-specific interactive steps
- `startingLocation` on interactive milestone manifests (not only path root)
- No `##` / `###` for grouping steps — use `section` (+ rule 14 bookends)
- `skippable: true` for permission-gated / conditional steps
- `verify` after save/create where applicable
- Prefer failing the wrap-up phase (or blocking “ready for PR”) until these pass

### `/lint` + `/check` (and CI if not already)
- Ensure the same rules are enforced on `*-lj/` packages locally and in CI so authors cannot open a PR that would fail Phase 1 static audit for these items

### Docs / skills
- Update `.cursor/commands/build-interactive-lj/README.md` critical rules / wrap-up
- Align `audit-guide` / `review-learning-path` so authoring and review cite the same checklist (avoid “review-only” surprises)

## Out of scope
- Replacing live Pathfinder / Playwright testing — still required for selectors and UI drift
- Companion website `pathfinder_data` migration (separate track)

## Success criteria
- A newly scaffolded LP that omits `on-page` / `startingLocation` / uses `##` for step grouping fails authoring validation before `gh pr create`
- PR review Phase 1 for those rules is mostly a confirmation pass, not the first discovery

## Context
- Raised during review of #430 while authoring + reviewing the same LP

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading .cursor/commands/build-interactive-lj/README.md and tracing the /build-interactive-lj, /create-learning-path, /lint, and /check entry points. Compare their current checks with the audit-guide and review-learning-path checklists, then verify that omitted on-page or startingLocation fields and ## step grouping fail before gh pr create, with the same rules enforced locally and in CI.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
ci-cd, documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.