[ordering-review] workshop order graph: 1 early-reference issue, 2 missing next links, loops benign

从 05-agentic-workflows-intro.md 第 53 行附近开始，那里的活动要求学习者在还没有任何工作流时就打开一个 .lock.yml。然后检查 side-quest-05-02-aw-deep-dive.md 中的示例文件对。接着为 26-manage-costs-and-budgets.md（指向 27）和 29-skills-and-domain-knowledge.md（指向 30）补上缺失的 Next 链接。完成标准是：05 中的活动与检查点一致，两个链接都已存在，并且 npx --yes markdownlint-cli2 "**/*.md" 通过。

Summary

Reviewed 97 workshop pages (graph: 97 nodes, 338 constraints, 57 heuristic findings, 3 cycles/feedback loops/weird cycles, 0 self loops). Most heuristic findings are false positives: 49 missing_prerequisite_link findings for pages 05–30 fire because those pages don't directly link to the Codespace or install steps, but the prerequisites are satisfied transitively through the linear chain. The three cycles are intentional back-links (see below). Three real ordering/navigation problems are confirmed.

Core path (the next edges)

graph TD
  w00["00 welcome"] --> p01["01 prerequisites"]
  p01 --> c02a["02a setup codespace"]
  l02["02-SQ01 local terminal"] --> a04
  c02a --> a04["04 actions intro"]
  a04 --> a05["05 agentic intro"]
  a05 --> a05b["05b security"]
  a05b --> a05c["05c practice"]
  a05c --> i06["06 install gh-aw"]
  l06["06-SQ04 install local"] --> f07
  i06 --> f07["07 first workflow"]
  f07 --> m07d["07d model access"]
  m07d --> r08["08 run workflow"]
  r08 --> r08b["08b interpret run"]
  r08b --> e09["09 agentic editing"]
  e09 --> n14["14 next steps"]
  n14 --> n14b["14b PR reviewer"]
  n14b --> n15["15 conditional logic"]
  n15 --> n16["16 data source"]
  n16 --> n17["17 MCP tools"]
  n17 --> n18["18 share and reuse"]
  n18 --> n19["19 research node"]
  n19 --> n20["20 memory"]
  n20 --> n21["21 sub-agents"]
  n21 --> n22["22 resilience"]
  n22 --> n23["23 A/B experiments"]
  n23 --> n24["24 self-hosted runners"]
  n24 --> n25["25 audit"]
  n25 --> n26["26 costs"]
  n26 -.missing next.-> n27["27 evals"]
  n27 --> n28["28 orchestrate"]
  n28 --> n29["29 skills"]
  n29 -.missing next.-> n30["30 staged mode"]

Side quests hang off these pages via before links (122 total).

Ordering constraints (summary of 338)

• 32 next constraints: the chain drawn above, plus side-quest-02-01 -> 04, side-quest-06-04 -> 07, side-quest-11-01 -> 11-08, side-quest-15-01 -> 16.
• 122 before constraints from explicit "Completed X" prerequisites. Examples: 06 -> 07, 07d -> 08, 08 -> 08b, 23 + 26 -> 27, 29 -> 30.
• 184 capability constraints: 02a or 02-SQ01 provides environment_ready, gh_installed, gh_authenticated for every page that uses gh or gh aw.

Confirmed cycles / feedback loops / weird cycles

All three are intentional and benign. Do not remove them.

• 07-your-first-workflow.md ⇄ 07d-confirm-model-access.md: 07 links forward as "Next"; 07d links back as an error-recovery entry point. 07d documents both entry points.
• 05-agentic-workflows-intro.md ⇄ 05b-agentic-workflows-security.md: 05 forward-references 05b; 05b lists 05 as its prerequisite.
• 02a-setup-codespace.md ⇄ side-quest-02-01-local-terminal.md: alternative setup paths that point at each other.

Verified ordering problems

1. 05-agentic-workflows-intro.md asks learners to open a .lock.yml before any workflow exists

• Quoted instruction: "Activity 1 — identify the parts: Open any .lock.yml file in your repo and find the on: key." (line 53). The checkpoint repeats it: "You identified the on: key in a compiled .lock.yml file".
• Missing prerequisite: The learner has not run gh aw init (step 06) or written/compiled a workflow (step 07). A fresh practice repository has no .lock.yml file to open.
• Why it confuses/blocks: The learner either can't complete the activity or opens an unrelated file. The checkpoint can't be ticked honestly.
• Suggested fix: Replace the activity with an in-page sample (the side quest side-quest-05-02-aw-deep-dive.md already has a sample .md / .lock.yml pair). Alternatively, move the "open your .lock.yml" activity to step 07 after compile. Update the checkpoint to match.

2. 26-manage-costs-and-budgets.md has no "Next" link, but 27-evaluate-workflow-quality.md requires it

• Evidence: 27's prerequisites say "You completed Manage Costs and AI Credit Budgets (link unavailable: invalid HTTPS URL)." Page 26 has no **Next:** link.
• Why it confuses: The linear path breaks at 26. Learners must go back to the README to find step 27.
• Suggested fix: Add **Next:** [Verify Your Workflow Quality with Evals](27-evaluate-workflow-quality.md) to 26.

3. 29-skills-and-domain-knowledge.md has no "Next" link, but 30-preview-with-staged-mode.md lists it as a prerequisite

• Evidence: 30 says "You completed Teach Your Agent Domain Knowledge with Skills (link unavailable: invalid HTTPS URL)". Page 29 has no **Next:** link.
• Why it confuses: Same dead-end as above.
• Suggested fix: Add **Next:** [Preview Your Workflow's Writes with Staged Mode](30-preview-with-staged-mode.md) to 29.

Optional low-priority note

05-agentic-workflows-intro.md (lines 51, 125, 132) and pages 15–24, 28–30 mention gh aw compile or gh aw run. Only pages 25 and 07 and 14b state a gh aw-installed prerequisite explicitly. This isn't a blocker, since step 06 precedes them all. Adding a one-line "gh aw works in your terminal (see step 06)" prerequisite would make out-of-order entry safer.

Status

This issue is ready for an agent to resolve. Apply fixes 1–3 and run npx --yes markdownlint-cli2 "**/*.md". Update workshop/README.md only if page links change.

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

• expires on Nov 1, 2026, 10:45 PM UTC