grafana / grafana/interactive-tutorials
Authoring: catch LP static audit rules before PR (on-page, startingLocation, rule 6)
- 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