[ordering-review] workshop order graph: environment reference verifies tools before Codespace exists

阅读 workshop/side-quest-01-02-environment-reference.md，然后检查 README.md 和 01-prerequisites.md 中指向该文件的链接。根据 issue 中的建议，决定是否将工具检查设为完成设置后的条件检查，或将页面的入口移到设置之后。完成标准是：从 Step 1 到来的学习者不会被要求打开尚未创建的 Codespace。

Summary

Reviewed 97 workshop pages (graph: 97 nodes, 338 edges/constraints, 57 heuristic findings, 3 cycles, 3 feedback loops, 3 weird cycles). After verifying against the source pages, 1 real ordering problem remains. The other findings are false positives or intentional loops (explained below).

Mermaid graph (core path, condensed from the generated graph)

graph TD
  W["00 welcome"] --> P["01 prerequisites"]
  P --> C["02a setup Codespace"]
  P -.optional.-> L["02-SQ01 local terminal"]
  C --> A["04 Actions intro"]
  L --> A
  A --> I["05 agentic intro"]
  I --> S["05b security"]
  S --> PR["05c practice"]
  PR --> G["06 install gh-aw"]
  G --> F["07 first workflow"]
  F <-->|"access check / recovery"| M["07d confirm model access"]
  M --> R["08 run"]
  R --> RI["08b interpret"]
  RI --> E["09 editing"]
  E --> N["14 next steps"]
  N --> N2["14b PR reviewer"]
  N2 --> CL["15 conditional logic"]
  CL --> D["16 data source"]
  D --> MCP["17 MCP tools"]
  MCP --> SH["18 share and reuse"]
  SH --> T["19 training node"]
  T --> MEM["20 memory"]
  MEM --> SA["21 sub-agents"]
  SA --> ER["22 error handling"]
  ER --> AB["23 A/B experiments"]
  AB --> SR["24 self-hosted runners"]
  SR --> AU["25 audit"]
  AU --> CO["26 costs"]
  CO2["27 evaluate quality"] --> OR["28 orchestrate"] --> SK["29 skills"]
  P -.branches from.-> ENV["01-SQ02 environment reference (problem)"]
  C -. should come first .-> ENV

The full generated graph (all 97 nodes, including side quests) is in the workflow artifact /tmp/gh-aw/data/order-review-report.md.

Ordering constraints (explicit "next" chain, 32 total; capability/before edges omitted for brevity)

• 00-welcome → 01-prerequisites → 02a-setup-codespace (or side-quest-02-01-local-terminal) → 04-github-actions-intro
• 04 → 05 → 05b → 05c → 06-install-gh-aw (or side-quest-06-04-install-local) → 07-your-first-workflow
• 07 → 07d-confirm-model-access → 08-run-your-workflow → 08b → 09-agentic-editing → 14-next-steps → 14b → 15 → 16 → 17 → 18 → 19 → 20 → 21 → 22 → 23 → 24 → 25 → 26
• 27 → 28 → 29
• Capability constraints (122 "before", 62 environment_ready, 62 gh_installed, 60 gh_authenticated): 02a-setup-codespace (or the local terminal side quest) must precede any page that runs gh/gh aw commands.

Confirmed cycles / feedback loops

• 07 ↔ 07d (cycle + weird cycle): intentional recovery loop. 07 sends learners with access errors to 07d, and 07d says to return to 07. Not a defect; 07d's "Before You Start" documents both entry points.
• 05 → 05b (cycle + weird cycle): false positive. 05b's prerequisite points back to 05, which is the normal linear order.
• 02a ↔ 02-SQ01 (cycle + weird cycle): false positive. These are alternative setup paths, not sequential steps.

No confirmed true circular dependency.

Verified ordering problem

1. side-quest-01-02-environment-reference.md tells learners to verify tools in a Codespace that may not exist yet

• File reviewed: workshop/side-quest-01-02-environment-reference.md (README.md says it "branches from Step 1 (link unavailable: invalid HTTPS URL)", before 02a-setup-codespace.md)

• Instruction too early:

  "Open a terminal in your Codespace and run: gh --version / git --version" (section "Verify your tools are ready")
  "If either fails, see Set Up a Codespace (link unavailable: invalid HTTPS URL)."

The same page's "Before You Start" says "No terminal required to read this page" and "Come back here whenever the workshop uses a term you want to clarify", so learners can arrive from Step 1 before any Codespace or local terminal has been opened.

• Missing prerequisite: An opened Codespace (or local terminal) from 02a-setup-codespace.md or side-quest-02-01-local-terminal.md.
• Why it's confusing: A learner arriving from Step 1 is told to open a terminal "in your Codespace" they haven't created, and the failure remedy points to the very step that creates it. The glossary also lists gh as "Pre-installed in the Codespace", reinforcing the assumption.
• Suggested fix: Either (a) keep the page as a pure glossary and move the "Verify your tools are ready" block and Checkpoint tool checks behind an explicit prerequisite ("After you complete Set Up a Codespace (link unavailable: invalid HTTPS URL) or Local Terminal Setup (link unavailable: invalid HTTPS URL)"), or (b) update README.md and 01-prerequisites.md to link this page as branching from step 02a rather than step 1. Also reword "If either fails, see Set Up a Codespace" to branch on learners who have not yet set up an environment.

Notes on dismissed findings

• 49 missing_prerequisite_link findings are mostly side quests that reference gh/gh aw commands where the parent step already carries the prerequisites. Spot checks of side-quest-02-01-local-terminal.md confirm gh auth login (line 122) precedes gh repo clone (line 149), so that finding is a false positive.

This issue is ready for an agent to resolve.

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

• expires on Nov 4, 2026, 9:05 PM UTC