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.

Entry command: /preflight-learning-path

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.

Routing: reference-checks.md · claim-check.md (pointer) · author-testing.md · frontend-selector-pr.md · shared claim-check · shared learning-hub-standards.md · shared review reference-checks

Related: audit-guide · update-guide · review-learning-path

Voice (author-facing)

Write like a calm teammate helping someone ship, not like a linter report.

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:

1. Path unclear (ambiguous / missing {path_dir})
2. Playwright MCP blocked or broken (setup)
3. Okta / browser ready before DOM checks (and stack choice, unless already known)
4. Block Editor smoke choice (and walk-me replies if they choose guided smoke)
5. 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

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.

Prerequisites

See author-testing.md § Prerequisites. Identify verifies Playwright MCP before live checks.

Safety invariants

1. Do not modify content.json, manifest.json, or website.yaml until the author requests package-fixable fixes.
2. 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.
3. Surface only review-level findings in chat and readiness (same bar as review comment-style). Never dump Internal/Discard nits.
4. No em dashes in author-facing chat, readiness text, or drafted PR bodies.
5. One preflight run per path slug (resume from state; do not fork duplicate state files).
6. Never plan companion website / pathfinder_data / shortcode work as package blockers.

Commit safety

Same snapshot/cleanup rules as review-learning-path § Commit safety.

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

1. Tell the author briefly what you are starting (path name when known). Do not lecture.
2. Run every agent-only step you can before the next real pause.
3. At a pause: one message, one clear ask. Plain language. Do not advance until they reply.
4. Do not invent extra "reply yes if this looks right" stops between agent-only work.
5. 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)

Do not open with a "What this check is" primer.

Useful replies: ready · add playwright mcp · fix playwright mcp · static-only: <reason> · already-tested: <notes> · walk-me · skip-smoke · pass / fail step N - … / N/A - … · show report · fix all · fix 1 / fix 2 / fix 3 · fix 1,3 · frontend · done · resume / start fresh

After package fixes, ask: Want an updated ready / not-ready summary? (not "refresh readiness").

Resume

If .cursor/lp-preflight-state/{slug}.json exists:

Resume? I have an in-progress preflight for {path_dir} (stopped at {checkpoint}).

Reply resume to pick up, or start fresh to begin again.

On resume, read checkpoint + status from state and continue from that gate. Do not invent a numeric phase.

Identify path + MCP (quiet unless blocked)

Goal: Confirm {path_dir}, path_type, milestones; verify Playwright MCP; init state.

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

1. Infer or confirm {path_dir} (directory ending in -lj).
2. Record branch and HEAD sha.
3. Infer website_slug = {path_dir} minus -lj when website repo is in workspace (read-only).
4. Infer path_type: new, conversion, or update per path type.
5. List milestones from path manifest.json milestones and dirs under {path_dir}/.
6. 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.
7. Write .cursor/lp-preflight-state/{slug}.json (state schema).

If MCP is blocked, stop with the blocked shape in author-testing.md (checkpoint: identify). Do not run live later until tools work.

Static pass (no author yes)

Goal: Audit every milestone + path consistency + Learning Hub + claim-check. Keep findings for the final results menu.

Persist: Keep checkpoint: login while static runs (next human gate). Do not invent a separate author-facing "static done" pause.

Agent steps

1. Snapshot pre_review_assets; dispatch audit-guide per milestone (parallel OK).
2. Walk shared review reference-checks + learning-hub-standards.md.
3. Always scan for framing-in-milestones (Pathfinder-only omission: keep packages for the website), section intro markdown that may number as a step, and false noops.
4. Run Pathfinder CLI validate --packages {path_dir} if available.
5. 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.
6. Tag findings with review finding routing. Keep only review-level items for later author chat.
7. Write {slug}-findings.md (findings + verify-live notes).
8. Mandatory audit cleanup; verify git status.
9. 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.

Playwright DOM (no author yes between milestones)

Details: author-testing.md.

Persist: checkpoint: dom while sweeping; set checkpoint: smoke when DOM is done (before the smoke ask).

For each milestone in scope (path order; skip prose-only / terminal):

1. Derive start URL (milestone start URL).
2. Navigate; check each reftarget: exists / missing / below-fold / state-dependent.
3. Record in playwright.{milestone-slug}.

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

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).

Agent steps

1. Apply selector decision tree; promote only review-level items.
2. Apply readiness gate.
3. Write {slug}-readiness.md with outcome + PR opener checklist.
4. Show the results menu below. Mark each finding package-fixable or needs-frontend.
5. Map replies: fix all / fix N → package fixes; frontend → frontend walkthrough; show report → readiness path; done → wrap with PR-opener notes.

When there are findings

{Friendly outcome}

What we checked

• {Product claims vs live docs}
• {UI selectors on {stack}}
• {Block Editor smoke: skipped / already-tested / walked}

Please fix these {N} ({short kind})

1. {Plain problem}. {Why / better wording}.
   ({file or dirs})
2. …

Your turn (include only lines that apply)

• fix all / fix N / fix 1,3 — package edits we can make here
• frontend — upstream data-testid for item(s) {N}
• done — open a PR and leave these for review
• show report — longer write-up

Heads-up (optional)
{Stack note. Remind once if needed: preflight reports are gitignored under .cursor/lp-preflight-state/.}

When every open item needs-frontend, omit fix all / fix N. Lead with frontend.

When clean

{Ready for PR | Open PR with notes}

What we checked

• …

Nothing here that would draw a review comment on copy or selectors. Nice work.

Your turn: Reply done if you are opening the PR, or show report for the write-up.

(If Open PR with notes: say why in one line, e.g. Block Editor smoke was skipped.)

Package fixes (optional)

Goal: Surgical edits for package-fixable findings only (fix all / fix N).

Persist: checkpoint: package_fixes while editing; return to checkpoint: results after offering an updated summary.

Working on {fix all | item N | items …}. I will edit content.json / manifest.json / website.yaml only, same discipline as update-guide.

1. Apply only requested package-fixable findings.
2. Re-run Pathfinder CLI validate if content/manifests changed.
3. Suggest re-running Playwright for touched interactive milestones when relevant.
4. Do not commit unless the author explicitly asks.

Applied {N} fix(es).

Your turn: Want an updated ready / not-ready summary? Or reply frontend / done.

Frontend selector PR (optional)

When a stable selector is missing upstream, follow frontend-selector-pr.md. Canonical example: grafana/grafana-cmab-app#1795.

Persist: checkpoint: frontend for the whole walkthrough.

Frontend PR {url} (or deferred).

Your turn: Reply done when you are ready to open the learning path PR (or wait on the testid merge).

Anti-patterns

Do not

• Quiz the author between agent-only steps ("Phase N complete, reply yes")
• Edit package JSON without an explicit ask
• Leave audit artifacts in milestone assets/
• Commit .cursor/lp-preflight-state/
• Surface Internal/Discard nits in chat or readiness
• Use em dashes, rule numbers, Blocker labels, or "refresh readiness"
• Force a full Block Editor loop when they already dogfooded
• Offer fix N as the main path for a needs-frontend finding
• Recommend Ready for PR with open review-level items
• Recommend Ready for PR on new / conversion interactive paths when Playwright was skipped
• Request website-repo changes as package blockers
• Use the PR review tool instead of local import (no PR yet)
• Leave checkpoint stale across gates (resume depends on it)

Do

• Batch agent work; pause only for real human gates
• Persist named checkpoint after each gate
• Keep chat short, clear, and friendly
• Dedupe findings by root cause
• Run CLI validate when available
• Offer package vs frontend actions correctly after the results menu
• Run the shared claim-check (same policy as review)

Generated files

Write under .cursor/lp-preflight-state/ (never commit; gitignored):

---
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}
---

Deep references