Guide a learning path author through pre-PR self-review in interactive-tutorials. Mirrors /review-learning-path-pr (shared static checklists, shared claim-check, Playwright DOM, readiness) from the author side, then optional package fixes and optional frontend data-testid PR. Use when the user runs /preflight-learning-path.
Instrucciones de origen · Vista previa de solo lectura
name
preflight-learning-path
description
Guide a learning path author through pre-PR self-review in interactive-tutorials. Mirrors /review-learning-path-pr (shared static checklists, shared claim-check, Playwright DOM, readiness) from the author side, then optional package fixes and optional frontend data-testid PR. Use when the user runs /preflight-learning-path.
Preflight learning path (author self-review)
Walk through a {slug}-lj/ package before you open a PR. Mirrors review-learning-path: shared static checklists, shared claim-check, Playwright DOM, then readiness and optional fixes. Author flow batches agent work and pauses only at real human gates (not a five-stop quiz).
Terminology: Say learning path or path in author messages; use {path_dir} in agent notes.
Mirror skill:review-learning-path. Shared claim policy lives under the review skill so both callers cannot drift.
Do NOT read external reference files upfront. Each step loads its own references on demand.
Skill memory: State lives in .cursor/lp-preflight-state/ (gitignored; never commit). Static pass dispatches audit-guide, which writes {milestone}/assets/. See Commit safety.
Write like a calm teammate helping someone ship, not like a linter report.
Do
Don't
Short sentences; plain words
Jargon in chat (post-inline, MUST FIX, "refresh readiness", rule numbers)
Say what is wrong, why it matters, which file
Dump severity labels or audit counts
Offer only actions that can resolve the item
Offer fix N when the real fix is upstream
Celebrate clean passes briefly
Hedge with "seems fine" / "maybe"
Pause only when you truly need the author
Quiz them with "reply yes" between agent-only steps
No em dashes in author chat, readiness text, or drafted PR bodies. Use periods, commas, or parentheses.
Address the author as you. Prefer "copy fixes," "product claims vs docs," "UI selectors," "smoke test," "ready / not-ready summary."
Author experience (hard flow)
Do as much as you can without stopping. Authors should not confirm every internal phase.
Pause only for:
Path unclear (ambiguous / missing {path_dir})
Playwright MCP blocked or broken (setup)
Okta / browser ready before DOM checks (and stack choice, unless already known)
Block Editor smoke choice (and walk-me replies if they choose guided smoke)
Results + fix menu (and later fix / frontend / done)
Do not pause for "Phase 0 complete, reply yes" or "Phase 1 complete, reply yes" when the path is known and MCP is healthy. Run identify → static → then ask for login in one beat.
Internal checkpoint names (see state schema) stay in state and agent notes. Author chat can say "checking your path," "live checks," "results" instead of a quiz board.
Human-in-the-loop contract
You (agent)
Author (human)
Infer path when clear; confirm only if ambiguous
Share {path_dir} when asked
Run static + claim-check without a mid-stop
Wait or do other work
Open Playwright; ask when logged in
Okta in Playwright browser; reply when ready
Run DOM checks; then ask about smoke
already-tested / walk-me / skip-smoke
One results + fix menu
fix all / fix N / frontend / done / show report
Apply package or frontend fixes only when asked
Approve edits / push
Workflow overview
Input (path_dir or current branch)
│
├─ Identify + MCP check ─────── quiet unless path/MCP needs the author
│
├─ Static pass ─────────────── audit + path/LH + claim-check (no author yes)
│
├─ PAUSE: login + stack ────── Playwright Okta; stack (or static-only if allowed)
│
├─ Playwright DOM ──────────── required (unless static-only)
│
├─ PAUSE: smoke choice ─────── already-tested / walk-me / skip-smoke
│
├─ Results + fix menu ──────── one readiness summary (former Phase 3)
│
├─ Optional package fixes ──── fix all / fix N
│
└─ Optional frontend testid ── when needs-frontend
Inputs
Required: {path_dir} ending in -lj/ (for example monitor-azure-resources-lj). Infer from current branch if omitted; confirm if ambiguous.
Optional: website_slug ({path_dir} minus -lj). Website repo is read-only for conversion (PR #416).
Optional: learn_host (default learn.grafana.net).
Optional: waive_live_testing via static-only: <reason> at the login/stack pause. See static-only preflight.
Do not modifycontent.json, manifest.json, or website.yaml until the author requests package-fixable fixes.
Never commit preflight artifacts (.cursor/lp-preflight-state/ or audit-guide files under {milestone}/assets/). Remind the author once that reports are local and gitignored.
Surface only review-level findings in chat and readiness (same bar as review comment-style). Never dump Internal/Discard nits.
No em dashes in author-facing chat, readiness text, or drafted PR bodies.
One preflight run per path slug (resume from state; do not fork duplicate state files).
Never plan companion website / pathfinder_data / shortcode work as package blockers.
Snapshot before static; delete new files before login pause
Pre-existing package assets/
Author/migrate notes
Never delete paths listed in pre_review_assets
Static snapshot:find {milestone}/assets -type f 2>/dev/null | sort → store in state pre_review_assets.
Static cleanup (mandatory before login pause): remove audit files not in the snapshot; verify git status --porcelain -- {path_dir} shows no untracked audit paths.
How this skill runs
Tell the author briefly what you are starting (path name when known). Do not lecture.
Run every agent-only step you can before the next real pause.
At a pause: one message, one clear ask. Plain language. Do not advance until they reply.
Do not invent extra "reply yes if this looks right" stops between agent-only work.
If they say "keep going" during a real pause (login / smoke / results), still honor that pause's need (e.g. you cannot DOM-check without login).
Results menu format (after live)
Section
Content
Header
Friendly outcome (e.g. almost ready, with N copy fixes first)
What we checked
Plain bullets: claims vs docs, UI selectors, smoke choice
Findings
Numbered: what is wrong, why it matters, which file
Persist: After init (or when blocked on MCP), set checkpoint to identify (still blocked) or login (ready for login pause). Set status: in_progress.
Author chat
If {path_dir} is missing or ambiguous:
Which learning path package should I preflight? Share the {slug}-lj/ directory, or tell me to infer it from your current branch.
If path is clear, say one short line (e.g. "Preflighting {path_dir}. Running the static checks now.") and continue. Do not ask them to confirm the path/type/MCP table when everything looks fine.
Mention once (early, not every pause): reports land under .cursor/lp-preflight-state/ and are gitignored; do not force-add them to a PR.
Agent steps
Infer or confirm {path_dir} (directory ending in -lj).
Record branch and HEAD sha.
Infer website_slug = {path_dir} minus -lj when website repo is in workspace (read-only).
Infer path_type: new, conversion, or update per path type.
List milestones from path manifest.jsonmilestones and dirs under {path_dir}/.
Verify Playwright MCP (user-playwright). Cover missing, needs-auth, toggled-off, and configured-but-broken per If Playwright MCP is missing or broken. Do not silently skip. Do not edit mcp.json until they agree.
Run Pathfinder CLI validate --packages {path_dir} if available.
Run the shared claim-check pass (preflight pointer: claim-check.md). Write {slug}-claim-check.md. Route Contradicted / Unsupported / Overstated as Fix before PR. Do not edit package JSON here.
Tag findings with review finding routing. Keep only review-level items for later author chat.
Do not cite rule numbers or audit severity labels in chat.
Then go straight to the login pause (unless static-only was already set).
PAUSE: Login + stack
Goal: Author is logged into Playwright on {learn_host}; record stack (or allow static-only when rules permit).
Persist: Before asking, checkpoint: login. After ready, set checkpoint: dom. After allowed static-only, set checkpoint: results and waive_live_testing.
Live checks next
I need you logged into {learn_host} in the Playwright browser (Okta there). I can open it for you if it is not open yet.
Also tell me which stack you are using (for example learn.grafana.net shared, fresh Cloud stack).
Reply ready when the Playwright browser is logged in (include the stack in the same reply if you have not already).
Or static-only: <reason> to skip live testing (not for new / conversion interactive paths).
Wait for:ready (+ stack), or allowed static-only: <reason>.
Record stack_state, or waive_live_testing + static_only_reason.
Reject bare static-only and static-only on new / conversion with interactive milestones. Precedence: static-only preflight.
If static-only: skip Playwright + smoke; jump to results menu with Not live-tested notes.
Keep chat quiet during the sweep (or a short progress line). Prefer documenting stack gaps over false "missing" on the wrong stack.
Then go to the smoke pause.
PAUSE: Block Editor smoke
Persist: Before asking, checkpoint: smoke. After the author replies, set checkpoint: results (or stay on smoke during walk-me until scoped milestones finish).
Have you already smoke-tested this path in Block Editor (Show me / Do it)?
already-tested: <short notes> if yes (stack + anything flaky)
walk-me for a guided per-milestone check now (local JSON import)
skip-smoke to continue without recording Block Editor evidence
Reply
Behavior
Readiness
already-tested: …
Store dogfood evidence
Can still be Ready for PR if Playwright clean and no open blockers
Same when scoped milestones pass or documented N/A
skip-smoke
Continue
Cap at Open PR with notes
After smoke (or walk-me finishes), build readiness and show the results menu once.
Results + fix menu
Goal: One readiness outcome; right next actions. Author chat shape: Author-facing findings.
Persist:checkpoint: results when showing the menu. On fix all / fix N → checkpoint: package_fixes. On frontend → checkpoint: frontend. On done → status: complete, keep checkpoint: results (or frontend if that was last).
---
disclaimer: Auto-generated by preflight-learning-path skill. Do not edit manually.
notice: To regenerate, re-run the skill from the relevant pause.
path_dir: {path_dir}
---
