Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[ordering-review] workshop order graph: 1 confirmed ordering problem, 3 benign loops

Open Beginner friendly
  • Is something wrong?
#5,059 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
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
github, markdown
Domain
documentation

Research direction

Read workshop/05-agentic-workflows-intro.md, focusing on Activity 1 and its Checkpoint, then check the stated prerequisites in 06-install-gh-aw.md and 07-your-first-workflow.md. Verify when learners first create a .lock.yml and update the activity or its placement and checkpoint so they can complete it in the documented order. Done means the step no longer asks learners to open a file that does not yet exist.

Written by the indexing model from the issue text.

Description

Summary

Reviewed 97 workshop pages (338 edges, 57 heuristic findings, 3 cycles/feedback loops/weird cycles). After verifying the cited files, one real ordering problem is confirmed. The rest are false positives or intentional structure. The dispatcher pages were not flagged.

Graph (core path, condensed)

graph TD
  W00[00 Welcome] --> P01[01 Prerequisites]
  P01 --> C02a[02a Set up Codespace]
  P01 -.before.-> L02[02-SQ01 Local terminal]
  C02a --> A04[04 Actions intro]
  L02 --> A04
  A04 --> A05[05 Agentic intro]
  A05 --> S05b[05b Security]
  S05b --> P05c[05c Practice]
  P05c --> I06[06 Install gh-aw / gh aw init]
  I06 --> F07[07 First workflow / compile]
  F07 --> M07d[07d Model access]
  M07d -.error recovery.-> F07
  M07d --> R08[08 Run]
  R08 --> R08b[08b Interpret run]
  R08b --> E09[09 Agentic editing]
  E09 --> N14[14 Next steps]

Ordering constraints

  • 00 → 01 → 02a (or 02-SQ01) → 04 → 05 → 05b → 05c → 06 → 07 → 07d → 08 → 08b → 09 → 14.
  • Environment, gh and gh authentication come from 02a, or from 02-SQ01 locally. Every gh aw command depends on 06 (extension installed, gh aw init run).
  • .lock.yml files exist only after 07 (gh aw compile).
  • 07d depends on 07 in normal flow and is also an error-recovery detour from 07.
  • All later steps (15–30) and side quests assume 06–09 are complete.

Cycles, feedback loops and weird cycles

All three are benign and intentional. No change is needed.

  • 07-your-first-workflow.md ↔ 07d-confirm-model-access.md. 07 links to 07d for error recovery and 07d links back. 07d documents both entry points.
  • 05-agentic-workflows-intro.md ↔ 05b-agentic-workflows-security.md. 05 only forward-references 05b ("You will explore security in...") and 05b lists 05 as its prerequisite.
  • 02a-setup-codespace.md ↔ side-quest-02-01-local-terminal.md. The two are alternative environment paths that point at each other as fallbacks.

Confirmed ordering problem

1. 05-agentic-workflows-intro.md asks learners to open a .lock.yml before any exists
  • File reviewed: workshop/05-agentic-workflows-intro.md
  • Instruction that is too early (Activity 1): "Open any .lock.yml file in your repo and find the on: key." The code block says # Example: open .github/workflows/my-workflow.lock.yml. A Checkpoint item repeats it: "You identified the on: key in a compiled .lock.yml file". The page also says "gh aw compile generates it from the .md".
  • Missing prerequisite: 06-install-gh-aw.md (extension installed, gh aw init) and 07-your-first-workflow.md (first gh aw compile). Nothing before step 05 creates a .lock.yml in the learner's new practice repo (my-agentic-workflows), and 02a only creates an empty repo.
  • Why it confuses or blocks: A learner who follows the Before You Start list (only step 04) has no .lock.yml to open. They can't finish Activity 1 or tick the Checkpoint, and they may think setup failed.
  • Suggested fix: Make Activity 1 work without the learner's repo. For example, embed a short sample .lock.yml snippet in the page, or link to a public example such as the .github/workflows/*.lock.yml files in this workshop repo. Alternatively, move the "open your own .lock.yml" activity to step 07, after the first compile. Update the checkpoint item to match.

Heuristic findings reviewed and dismissed

  • side-quest-01-02-environment-reference.md (flagged for gh --version / gh aw before environment setup). False positive. It is an optional reference page and says "No terminal required to read this page".
  • About 49 missing_prerequisite_link findings on steps 07 to 30 and their side quests (gh aw compile, gh aw run, gh aw logs and similar). These pages are later in the path, after 06 and 07. Many already list "gh aw is installed" or a working workflow as a prerequisite, for example 14b, 18 and 25. Optionally, side quests that lack any "Before You Start" link to 06 could add one, but this is low severity and not a blocker.
  • side-quest-02-01-local-terminal.md (gh repo clone flagged). It sits inside the local-terminal path, which provides the terminal.

This issue is ready for an agent to resolve.

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

  • expires on Oct 28, 2026, 10:44 PM UTC
Dominant language
JavaScript
Stars
56
Forks
40
Avg merge
2d 7h
Merged PRs (30d)
16

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.