review-learning-path

# Review learning path PR Help a **human reviewer** work through a `{slug}-lj/` pull request in **five phases**. You run static checks and draft comments; **the reviewer** smoke-tests in Block Editor and approves what posts to GitHub. **This is not a full AI review.** You are a review coach, not the reviewer. **Terminology:** Say **learning path** or **path** in reviewer messages; use `{path_dir}` in agent notes. Call live testing **Block Editor smoke test** (load via PR review tool in Block Editor dev tools). **Entry command:** [/review-learning-path-pr](../../commands/review-learning-path-pr.md) **Do NOT read external reference files upfront.** Each phase loads its own references on demand. **Skill memory:** State lives in `.cursor/pr-review-state/` (gitignored). Phase 1 dispatches [audit-guide](../audit-guide/SKILL.md), which writes `{milestone}/assets/` on the PR branch. See [Commit safety](#commit-safety). **Routing:** [reference-checks.md](reference-checks.md) · [claim-check.md](claim-check.md) · [comment-style.md](comment-style.md) · [learning-hub-standards.md](learning-hub-standards.md) · [github-review.md](github-review.md) **Related:** [audit-guide](../audit-guide/SKILL.md) · [review-guide-pr.mdc](../../review-guide-pr.mdc) · [preflight-learning-path](../preflight-learning-path/SKILL.md) (author pre-PR mirror) --- ## Human-in-the-loop contract | You (agent) | Reviewer (human) | |---|---| | Check out PR, run audit + path checks | Confirm path, choose test stack | | Write internal workbook; Phase 1 chat stays tiny (≤3 verify-live items) | Skim workbook if curious; never paste to author | | Required Playwright DOM check per milestone | Log into Playwright (Okta) | | Record DOM + smoke test results | Run Show me / Do it in Block Editor per milestone | | Draft **author-facing** fixes as short inline comments in chat | Approve, edit, or skip before GitHub post | | Post approved comments, submit when told | Choose APPROVE / COMMENT / REQUEST_CHANGES | --- ## Workflow overview ``` Input (PR URL or number) │ ├─ Phase 0: Setup ───────────── checkout PR, infer path_dir │ ├─ Phase 1: Static pass ─────── audit + path/LH checks → workbook (internal) │ ├─ Phase 2: Live test ───────── required Playwright DOM + Block Editor smoke test │ (skipped when static-only) │ ├─ Phase 3: Draft review ────── draft comments + summary in chat; reviewer approves; │ then post to GitHub draft review │ └─ Phase 4: Submit ──────────── reviewer confirms verdict; publish ``` --- ## Inputs - **Required**: `pr_number` or GitHub PR URL for `grafana/interactive-tutorials`. - **Optional**: `path_dir`, `website_slug`, `learn_host` (default `learn.grafana.net`). - **Optional**: `waive_live_testing` — skip Phase 2. Requires `static-only: <reason>` at Phase 1 end. See [static-only reviews](reference-checks.md#static-only-reviews). - **Optional**: `reuse_live` — record prior Block Editor evidence and skip per-milestone re-test. Requires `reuse-live: <notes>`. See [reuse-live](reference-checks.md#reuse-live-prior-evidence). --- ## Safety invariants 1. **Never modify author `content.json` or `manifest.json`.** 2. **Never post to GitHub before Phase 3 approval** from the reviewer. 3. **Never submit before Phase 4** explicit `submit` from the reviewer. 4. **Never commit review artifacts** — `.cursor/pr-review-state/` or audit-guide output under `{milestone}/assets/`. 5. **Never paste the workbook to the author** — `pr-{n}-findings.md` is reviewer-private. Author fixes go as short GitHub inline comments on the file, not workbook dumps or agent paraphrases of the audit. 6. **Phase 1 chat stays tiny** — one outcome sentence + ≤3 “verify live” bullets. No audit volume in chat. --- ## Commit safety Same rules as before. Snapshot `pre_review_assets` before audit-guide; mandatory cleanup before Phase 1 checkpoint; verify `git status --porcelain -- {path_dir}` shows no untracked audit files. Re-verify commit safety after Phase 1 before Phase 2. --- ## How this skill runs 1. Announce phase, what you're doing, why (2–3 sentences). 2. Do agent work (audit, Playwright, draft text). 3. Stop at checkpoint — one ask. **Do not advance** until the reviewer replies. 4. **Never batch phases.** --- ## Checkpoint format | Section | Content | |---|---| | **Header** | `Phase {n} complete` + one-line outcome | | **Summary** | Up to 3 plain-language bullets. No rule counts, no "blocking patterns." | | **Your turn** | Exactly one action | | **Up next** | One sentence | **Reply keywords:** `yes` · `ready` · `static-only: <reason>` · `reuse-live: <notes>` · `pass` / `fail step N — …` / `partial — …` / `N/A — …` · `post all` / `post 1,2` / `skip` · `show summary` · `submit COMMENT` · `resume` / `start fresh` **Tone:** Plain language. No audit jargon in chat. Say when things went cleanly. --- ## Resume If `.cursor/pr-review-state/pr-{n}.json` exists: > **Resume?** In-progress review for PR #{n} — stopped after phase {phase}. > > Reply **resume** or **start fresh**. --- ## Phase 0: Setup **Goal:** Checkout PR, infer path, init state. ### Tell the reviewer > **Phase 0 — Setup** > > Share the PR (URL or `#403`) from `grafana/interactive-tutorials`. ### Agent steps 1. `gh pr view` + `gh pr checkout` 2. Infer `{path_dir}`, `website_slug`, `pr_type` 3. Write `pr-{n}.json` with `pull_request_node_id` ([github-review.md](github-review.md)) ### Checkpoint > **Phase 0 complete** — PR #{n} on `{head_branch}` @ `{short_sha}`, path `{path_dir}` ({M} milestones), type `{pr_type}`. > > **Your turn:** Reply **yes** to start the static pass. --- ## Phase 1: Static pass **Goal:** Audit every milestone + path consistency + Learning Hub checks + shared [claim-check](claim-check.md). Output: **internal workbook only**. Combines the former Phases 1–2 and workbook write. ### Tell the reviewer > **Phase 1 — Static pass** > > I'm reading each milestone and checking manifests, `website.yaml`, and Learning Hub structure. Nothing goes to GitHub. I'll save notes to your private workbook. ### Agent steps 1. Snapshot `pre_review_assets`; dispatch [audit-guide](../audit-guide/SKILL.md) per milestone (parallel OK). 2. Walk all [reference-checks.md](reference-checks.md) checklists + [learning-hub-standards.md](learning-hub-standards.md). 3. **Always scan** for [section intro markdown that may number as a step](reference-checks.md#section-intro-markdown-numbered-as-a-step) and [false noops](reference-checks.md#noop-and-non-interactive-steps). Put matches under **Verify in Block Editor**. 4. Run Pathfinder CLI validate if available. 5. Run the shared [claim-check](claim-check.md) pass. Write `pr-{n}-claim-check.md`. Route Contradicted / Unsupported / Overstated as **post inline** (same bar as preflight). Do not edit package JSON here. 6. Tag every finding with [finding routing](reference-checks.md#finding-routing): **post inline**, **internal**, or **discard**. 7. Write `pr-{n}-findings.md` — header: *"Reviewer workbook — internal only. Do not paste to PR."* - **Verify in Block Editor** — items that need live test to confirm (include section-intro markdown and false-noop candidates) - **Post inline if confirmed** — static compliance issues (broken depends, id mismatch, CLI fail) and claim-check MUST FIX items - **Internal** — nits, LH editorial, selector polish, `website.yaml` gaps 8. Mandatory audit cleanup; verify `git status`. 9. **Do not** cite rule numbers or blocking counts in chat. ### Checkpoint Phase 1 chat stays **tiny**. Do not dump the workbook, audit counts, or author-facing fix lists into chat. > **Phase 1 complete** — static pass done. > > - {One plain sentence: e.g. "Looks clean statically." or "A few things to verify when you smoke-test."} > - **Verify live** (≤3 bullets, plain language only — omit this list if none): > - {e.g. watch for "You'll…" numbered as step 1} > - {e.g. Label/Display noops look like false steps} > - {e.g. Services tab selector on credentialed stack} > > Workbook stays private (`.cursor/pr-review-state/pr-{n}-findings.md`). Do not paste it to the author. > > **Your turn:** Reply **yes** and your test stack (e.g. `learn.grafana.net shared`, `fresh Cloud stack`, `Azure credentialed`). > > Or **`static-only: <reason>`** to skip live testing (not on **new** / **conversion** interactive PRs). > > Or **`reuse-live: <notes>`** when Block Editor evidence already exists (author dogfood, earlier in-thread pass). See [reuse-live](reference-checks.md#reuse-live-prior-evidence). > > **Up next:** Block Editor smoke test with required Playwright DOM check per milestone *(or draft review if static-only / reuse-live)*. Record: `stack_state`, or `waive_live_testing` + `static_only_reason`, or `reuse_live` + `reuse_live_notes` (+ `stack_state` when known). **Reject** bare `static-only` and static-only on **new** / **conversion** with interactive milestones. **Reject** bare `reuse-live` (notes required). --- ## Phase 2: Live test (Block Editor smoke test) **Goal:** Reviewer smoke-tests each milestone. **Required Playwright DOM check** runs before each milestone's Block Editor test. Skipped when `waive_live_testing` is true → jump to Phase 3. Skipped when `reuse_live` is true → record prior evidence, fill `pathfinder` from notes / workbook, jump to Phase 3. Do **not** re-prompt per milestone. See [reuse-live](reference-checks.md#reuse-live-prior-evidence). ### Setup (tell the reviewer once) > **Phase 2 — Live test** > > Two browsers: > - **Playwright** (Okta login): I use this for required DOM checks per milestone. > - **Your normal browser**: Block Editor smoke test. > > **Playwright:** Log into `{learn_host}` with Okta. Reply **ready** when logged in. > > **Block Editor:** Open `{learn_host}/plugins/grafana-pathfinder-app?dev=true` → **?** → Debug → Block Editor → dev tools → **PR review tool** → point at PR #{n}. > > Stack: `{stack_state}` > > Reply **ready** when both are set up. I won't ask you to test a milestone until you do. > > Or **`reuse-live: <notes>`** if Block Editor was already run for this PR (dogfood / resume) and you have evidence to record. **Wait for:** `ready` or `reuse-live: <notes>`. ### Milestone scope | `pr_type` | Scope | |---|---| | **new** / **conversion** | Every interactive milestone in path `milestones` | | **update** | PR-touched interactive milestones first; full path on request | ### Per-milestone loop For each milestone in scope (path order; skip prose-only / terminal): **Step A — Required Playwright DOM (agent):** 1. Derive start URL ([milestone start URL](reference-checks.md#milestone-start-url)). 2. Navigate; check each `reftarget`: exists / missing / below-fold / state-dependent. 3. Record in `playwright.{milestone-slug}`. 4. Briefly tell reviewer DOM result (one line) before Block Editor prompt. **Step B — Block Editor smoke test (reviewer):** > **Milestone {i} of {M}: `{milestone-id}`** > > Open `{derived_start_url}`, then run every **Show me** and **Do it** in Block Editor. > > If earlier milestones used `doIt: false` on save or credential steps, run **Do it** on those before testing downstream UI, or note the stack was already configured. > > Also scan the section step list for **false step numbers**: intro prose numbered as step 1 (for example "You'll …"), or learner-action `noop`s numbered as interactive steps. Say so in your reply if you see either. > > **Your turn:** Reply **pass**, **fail step N —** *what happened*, **partial —** *what failed / what passed*, or **N/A —** *reason*. Record in `pathfinder.{milestone-slug}`. Advance only after reviewer replies. **Do not** post GitHub comments during Phase 2. ### Checkpoint > **Phase 2 complete** — smoke test done. > > - Passed: [short list or *all*] > - Failed: [short list or *none*]