[ordering-review] workshop order graph: 1 confirmed ordering issue, 3 loops reviewed as intentional

Closed Beginner friendly
  • Is something wrong?
#5,211 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
git, github, markdown
Domain
documentation

Research direction

Start with workshop/side-quest-01-02-environment-reference.md, in the "Verify your tools are ready" section, and compare it with 01-prerequisites.md and 02a-setup-codespace.md. Add a "Before You Start" note pointing to Set Up a Codespace, reword the verify lead-in so it follows setup, and make the closing link go to 02a-setup-codespace.md when setup isn't finished. Done means the page no longer asks for a Codespace terminal before one exists, and the links to 02a resolve.

Written by the indexing model from the issue text.

Description

Graph health summary

Reviewed 97 workshop pages (3 dispatchers). The generated graph has 338 constraint edges, 57 heuristic findings, 3 cycles, 3 feedback loops and 3 weird cycles. After checking the cited files, one finding is a real ordering problem. The rest are false positives or intentional loops (details below).

Mermaid graph (main path, next edges only; the full 338-edge graph is in /tmp/gh-aw/data/order-review-report.md)

graph TD
  W00[00 Welcome] --> P01[01 Prerequisites]
  P01 --> S02a[02a Set Up a Codespace]
  P01 -.optional.-> SQ0201[02-SQ01 Local Terminal]
  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 Workflow]
  S07d -.error recovery.-> S07
  P01 -.branch.-> SQ0102[01-SQ02 Environment Reference]
  SQ0102 -.returns to.-> P01

Ordering constraints (key ones)

  • 00 → 01 → 02a → 04 → 05 → 05b → 05c → 06 → 07 → 07d → 08 (next links).
  • 02a (or 02-SQ01) provides environment_ready, gh_installed and gh_authenticated. All later steps that run gh depend on it.
  • 06 provides the gh aw extension. Everything using gh aw depends on it.
  • 07d is an error-recovery branch from 07 and returns to 07 or continues to 08.
  • 01-SQ02 branches from 01 and returns to 01.

Cycles, feedback loops and weird cycles

Pages Verdict
07-your-first-workflow.md ↔ 07d-confirm-model-access.md Intentional. 07d says "Arriving from step 07 (error recovery)... return to Write Your First Agentic Workflow". No fix needed.
05-agentic-workflows-intro.md ↔ 05b-agentic-workflows-security.md False positive. The before edge comes from 05b's "Before You Start" link back to 05. This is a prerequisite reference, not a loop.
02a-setup-codespace.md ↔ side-quest-02-01-local-terminal.md False positive. These are alternative setup paths that provide the same capabilities.

The 49 missing_prerequisite_link findings (for example 07, 08, 09 and 15–30 "depend on an authenticated gh session") are heuristic noise. Authentication is established in 02a, and the 06 → 07 → 08 chain covers it. I recommend no per-page changes.

Verified ordering problem

workshop/side-quest-01-02-environment-reference.md runs terminal commands before any environment exists

  • File reviewed: workshop/side-quest-01-02-environment-reference.md (section "Verify your tools are ready").

  • Quoted instruction too early: "Open a terminal in your Codespace and run:" followed by gh --version and git --version. The page also says: "If either fails, see Set Up a Codespace (link unavailable: invalid HTTPS URL)."

  • Missing prerequisite: The page branches from 01-prerequisites.md, which says "You will set one up in the next step". The Codespace in 02a-setup-codespace.md doesn't exist yet. The page also has no "Before You Start" section pointing to 02a.

  • Why it can confuse or block a learner: A learner who follows the Step 1 link to this glossary and then its verify section is told to open a Codespace terminal that they haven't created. The failure advice then sends them forward to 02a, which is circular. The closing line returns them to Step 1, so they never finish setup in this flow.

  • Suggested fix:

    1. Add a "Before You Start" note: "Complete Set Up a Codespace (link unavailable: invalid HTTPS URL) first. This reference is a glossary until you have a terminal."
    2. Change the verify section's lead-in to "Once you've completed Set Up a Codespace, open a terminal and run:".
    3. Change the end link to continue to 02a-setup-codespace.md when setup isn't done.

Status

This issue is ready for an agent to resolve.

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

  • expires on Nov 1, 2026, 10:03 PM UTC
Dominant language
JavaScript
Stars
56
Forks
40
Avg merge
2d 14h
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.