[ordering-review] workshop order graph: 1 side-quest ordering issue, 3 benign cycles

Open Beginner friendly
#5,790 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
88/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
github-actions, markdown

Research direction

Read workshop/side-quest-01-02-environment-reference.md and workshop/README.md to confirm where the side quest branches and when Codespace setup happens. Update the verification instructions so learners know to run the checks after completing Codespace setup, and adjust the README branch note if appropriate. Done when learners following the side quest before setup are clearly told to treat the page as reference until they have a Codespace.

Written by the indexing model from the issue text.

Description

Graph health summary

Reviewed 98 pages (3 dispatcher pages), 346 edges, 59 heuristic findings, 3 cycles, 3 feedback loops and 3 weird cycles. After verifying the cited pages, 58 findings are false positives (details below). One real ordering problem remains. The full generated graph and constraint list are in order-review-report.md from the run artifacts. The condensed core path is below.

graph TD
  w00["00 welcome"] --> p01["01 prerequisites"]
  p01 --> s02a["02a setup codespace"]
  p01 -.->|branch| sq0102["01-SQ02 environment reference"]
  p01 -.->|branch| sq0201["02-SQ01 local terminal"]
  s02a --> a04["04 actions intro"]
  sq0201 --> a04
  a04 --> a05["05 agentic intro"]
  a05 --> a05b["05b security"]
  a05b --> a05c["05c practice"]
  a05c --> i06["06 install gh-aw"]
  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"]

Ordering constraints (key ones)

  • 01 → 02a (Codespace) or 02-SQ01 (local) → 04 → 05 → 05b → 05c → 06 → 07 → 07d → 08 → 08b → 09
  • environment_ready, gh_installed and gh_authenticated are provided by 02a (or 02-SQ01).
  • gh aw commands require 06 (extension installed) and 07's gh aw init.
  • 05/05b and 07/07d have reciprocal before/next edges (see cycles).

Cycles, feedback loops and weird cycles

All three are benign:

  1. 05 ↔ 05b – 05b says "You've read What Are Agentic Workflows?" and 05 says "Next: How Agentic Workflows Stay Safe". This is a normal prev/next pair, not a loop.
  2. 07 ↔ 07d – 07d deliberately has two entry points (error recovery from 07, or the normal next step), and 07 links to it for troubleshooting. This is documented intentionally.
  3. 02a ↔ 02-SQ01 – these are alternative environment paths (Codespace vs local) that reference each other as options, not a sequential loop.

The 51 missing_prerequisite_link findings (gh_authenticated not linked to 02a on later steps) are heuristic false positives. All those pages sit after 02a and 06 in the linear path, and 06/07 already state the prerequisites.

Verified ordering problem

File: workshop/side-quest-01-02-environment-reference.md

Instruction that appears too early (section "Verify your tools are ready"):

Open a terminal in your Codespace and run:
gh --version / git --version / gh auth status

Missing earlier step: The side quest branches from Step 1 (link unavailable: invalid HTTPS URL) (per workshop/README.md), but the Codespace is not created until 02a-setup-codespace.md. The page's own "Before You Start" says "No terminal required", yet the checkpoint section asks learners to open a Codespace terminal and run gh/gh auth status. It also says "If any command fails, see Set Up a Codespace", which points forward to a step the learner may not have done.

Why it confuses learners: A learner who follows the side quest right after Step 1 has no Codespace or terminal to open, so the verification looks broken or leads them to skip the check.

Suggested fix:

  • Change the intro to: "Do this verification after you finish Set Up a Codespace (link unavailable: invalid HTTPS URL); until then, treat this page as read-only reference."
  • Replace "Open a terminal in your Codespace and run:" with "After completing Set Up a Codespace, open its terminal and run:".
  • Optionally move the README branch note to "branches from Step 2a".

This issue is ready for an agent to resolve.

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

  • expires on Nov 17, 2026, 11:07 AM UTC
Dominant language
JavaScript
Stars
62
Forks
43
Avg merge
11h 26m
Merged PRs (30d)
13

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

  • No Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from githubnext/gh-aw-workshop

All issues in githubnext/gh-aw-workshop

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.