[ordering-review] workshop order graph: 1 confirmed ordering issue, 3 cycles are false positives

问题出在 workshop/side-quest-01-02-environment-reference.md 的「Verify your tools are ready」部分，该部分假设 Codespace 终端已经存在。请将其与 workshop/02a-setup-codespace.md 以及「Before You Start」部分进行对比，找出顺序上的缺口。完成的标准是：该部分首先说明所需的设置步骤，术语表在没有终端的情况下依然可以读懂，并且 npx --yes markdownlint-cli2 "**/*.md" 检查通过。

Summary

The generated report covered 97 workshop pages, 338 constraints, 57 potential findings, and 3 cycles/feedback loops/weird cycles. I checked the cited files. One ordering problem is real and small. The other findings are heuristic false positives.

The full 97-node graph and all 338 constraints are in the run's generated report (order-review-report.md). The condensed core path is below.

Mermaid graph (core path)

graph TD
  W00["00 Welcome"] --> P01["01 Prerequisites"]
  P01 --> S02a["02a Set Up a Codespace"]
  P01 -.branch.-> SQ0102["01-SQ02 Environment Reference (side quest)"]
  P01 -.branch.-> SQ0201["02-SQ01 Local Terminal (side quest)"]
  S02a --> S04["04 Actions intro"]
  SQ0201 --> S04
  S04 --> S05["05 Agentic workflows intro"]
  S05 --> S05b["05b Security"]
  S05b --> S05c["05c Practice"]
  S05c --> S06["06 Install gh-aw"]
  S06 --> S07["07 First workflow"]
  S07 --> S07d["07d Confirm model access"]
  S07d --> S08["08 Run your workflow"]
  S07 -.error recovery.-> S07d
  S07d -.return.-> S07

Ordering constraints (core)

• 00 → 01 → 02a (or 02-SQ01 local path) → 04 → 05 → 05b → 05c → 06 → 07 → 07d → 08 → ...
• 02a (or 02-SQ01) provides environment_ready, gh_installed and gh_authenticated. Every page that uses gh or gh aw depends on these.
• 06 provides the gh aw extension. 07 and later depend on it.
• 05 and 05b are linked in both directions: 05 links forward to 05b, and 05b lists 05 as a prerequisite.
• 07 and 07d are linked in both directions: 07d serves as an error-recovery page and as the normal next step.

Cycles, feedback loops and weird cycles

All three are false positives:

• 05 ↔ 05b: 05 mentions 05b ("You will explore security in...") and 05b requires 05. That is a forward reference plus a prerequisite, not a real cycle.
• 07 ↔ 07d: 07d-confirm-model-access.md documents two entry points on purpose ("Arriving from step 07 (error recovery)" and "Arriving as the next step after step 07 (normal flow)"). This is intentional.
• 02a ↔ 02-SQ01: these are alternative setup paths (Codespace vs. local terminal). They are not sequential dependencies.

The 49 missing_prerequisite_link findings for gh_authenticated come from the heuristic. Mentions of gh aw compile in 05, side-quest-05-03 and similar pages are descriptive text. In 06 onward the "Before You Start" sections correctly point to the Codespace setup. I am not treating them as defects.

Verified ordering problem

Environment Reference asks learners to open a Codespace terminal before the Codespace setup

• File reviewed: workshop/side-quest-01-02-environment-reference.md (a side quest that branches from Step 1, 01-prerequisites.md, which comes before 02a-setup-codespace.md)

• Quoted instructions that appear too early:

  • "Open a terminal in your Codespace and run:" followed by gh --version and git --version
  • "If either fails, see Set Up a Codespace (link unavailable: invalid HTTPS URL)."
  • The glossary row says gh is "Pre-installed in the Codespace".

• Missing earlier step: 02a-setup-codespace.md (or side-quest-02-01-local-terminal.md) creates the terminal environment this section assumes. The page's own "Before You Start" says "No terminal required to read this page". The page is also linked from Step 1 and from Step 6/16 content, so learners can reach it before any Codespace exists.

• Why it confuses or blocks learners: A learner who arrives from Step 1 is told to open a Codespace terminal that does not exist yet. The verify checks fail or can't be run, and the fix link points forward.

• Suggested fix: Reword the "Verify your tools are ready" section to say "After you finish Set Up a Codespace (link unavailable: invalid HTTPS URL) (or the local terminal side quest), open its terminal and run...". Add that prerequisite to "Before You Start" for the verification part only. Keep the glossary readable without a terminal. Optionally move the gh aw verification block under "after Step 6".

Notes

• The issue is ready for an agent to resolve.
• Run npx --yes markdownlint-cli2 "**/*.md" after editing.
• Check whether the golden-ticket-workshop branch needs a matching change.

Generated by 🧭 Workshop Order Review · copilot · auto · ~24 AIC · ⌖ ~1 AIC · ⊞ 4.8K · ◷

• expires on Nov 3, 2026, 6:05 PM UTC