[ordering-review] workshop order graph: one ordering defect found (Step 5 Activity 1 references .lock.yml before it exists)

Leggi workshop/05-agentic-workflows-intro.md e confronta Activity 1 con l’ordine del workshop in workshop/README.md e con i passaggi per creare un workflow in workshop/06-install-gh-aw.md e workshop/07-your-first-workflow.md. Decidi come deve funzionare l’attività prima che esista un file .lock.yml compilato, quindi aggiorna le istruzioni dello Step 5 affinché i partecipanti possano completarla a quel punto. L’obiettivo è che Activity 1 non richieda più un file che non è ancora stato creato.

Summary

An automated graph/ordering review of workshop/*.md found 3 confirmed problems: two genuine mutual "before" cycles between adjacent core steps, and one case where learners are asked to inspect a compiled .lock.yml file before any step in the workshop has created one.

• Files reviewed: 96 (93 learning pages + 3 dispatcher pages)
• Graph nodes: 96, edges: 334
• Potential findings flagged by heuristics: 56 (most were false positives from the heuristic's generic "gh_authenticated" capability check, which does not track that Step 2 — Codespace setup — already establishes an authenticated gh session for every downstream core/side-quest page)
• Confirmed real issues after manual verification: 1 (plus 2 cycles reviewed and dismissed as intentional)

Mermaid graph

graph TD
  node_001["00 00-welcome.md\nWelcome to our Agent Factory Tour"]
  node_002["01 01-prerequisites.md\nBefore we start"]
  node_006["02a 02a-setup-codespace.md\nSet Up a Codespace"]
  node_007["02-SQ01 side-quest-02-01-local-terminal.md\nSide Quest: Set Up Your Local Terminal"]
  node_008["04 04-github-actions-intro.md\nGitHub Actions in 5 Minutes"]
  node_009["05 05-agentic-workflows-intro.md\nWhat Are Agentic Workflows?"]
  node_010["05b 05b-agentic-workflows-security.md\nHow Agentic Workflows Stay Safe"]
  node_011["05c 05c-agentic-workflows-practice.md\nPractice: Recognize Agentic Workflows"]
  node_015["06 06-install-gh-aw.md\nInstall the gh-aw CLI Extension"]
  node_020["07 07-your-first-workflow.md\nWrite Your First Agentic Workflow"]
  node_021["07d 07d-confirm-model-access.md\nConfirm Model Access"]
  node_023["08 08-run-your-workflow.md\nRun and Watch Your Workflow"]

  node_002 -->|before| node_006
  node_006 -->|before| node_008
  node_007 -->|before| node_006
  node_007 -->|before| node_008
  node_002 -->|before| node_007
  node_006 -->|before| node_007
  node_008 -->|before| node_009
  node_009 -->|before| node_010
  node_010 -->|before| node_009
  node_006 -->|capability:gh_authenticated| node_009
  node_010 -->|before| node_011
  node_009 -->|before| node_011
  node_015 -->|before| node_020
  node_006 -->|before| node_015
  node_009 -->|before| node_015
  node_020 -->|before| node_021
  node_021 -->|before| node_020
  node_020 -->|before| node_023

(Full generated graph had 96 nodes / 334 edges; this excerpt shows only the nodes and edges relevant to the confirmed findings below. The complete machine-generated graph is available in the workflow run artifacts order-review-context.json / order-review-report.md.)

Ordering constraints (relevant excerpt)

• 01-prerequisites.md must come before 02a-setup-codespace.md (explicit next-step link).
• 02a-setup-codespace.md must come before 04-github-actions-intro.md (explicit next-step link) and establishes gh auth status / an authenticated terminal session used by all later steps.
• 04-github-actions-intro.md must come before 05-agentic-workflows-intro.md (explicit next-step link and listed prerequisite).
• 05-agentic-workflows-intro.md must come before 05b-agentic-workflows-security.md (explicit "Next:" link) and 05b-agentic-workflows-security.md lists 05-agentic-workflows-intro.md as a "Before You Start" prerequisite — these two constraints point in opposite directions.
• 06-install-gh-aw.md must come before 07-your-first-workflow.md (explicit prerequisite: "Completed Install the gh-aw CLI Extension").
• 07-your-first-workflow.md must come before 07d-confirm-model-access.md (explicit "Next:" link, reached only on an access error) and 07d-confirm-model-access.md tells the learner arriving from the error path to "return to Write Your First Agentic Workflow" — these two constraints also point in opposite directions.

(The full 334-line constraint list is in the workflow's generated order-review-report.md artifact; only the subset above is relevant to the confirmed findings.)

Confirmed cycles / feedback loops

1. Cycle: 05-agentic-workflows-intro.md ↔ 05b-agentic-workflows-security.md (edge types: before, next)
2. Cycle: 07-your-first-workflow.md ↔ 07d-confirm-model-access.md (edge types: before, next)
3. Cycle: 02a-setup-codespace.md ↔ side-quest-02-01-local-terminal.md (capability edges: environment_ready, gh_authenticated, gh_installed) — reviewed and dismissed as a false positive: this is an intentional either/or branch (choose Codespace or local terminal, not both in sequence), not a true ordering conflict. No action needed for this one.

Cycles 1 and 2 are not actual learner-facing problems either, after close reading:

• 05-agentic-workflows-intro.md → 05b-agentic-workflows-security.md → the back-reference in 05b's "Before You Start" list is simply documenting that 05 is a soft-read prerequisite, not asking the learner to re-do 05b before 05. The graph heuristic over-reads a "Before You Start: You've read X" bullet as a hard reverse edge. No fix needed.
• 07-your-first-workflow.md ↔ 07d-confirm-model-access.md is an intentional, clearly-labeled error-recovery branch: Step 7 says "if you see an error... see Confirm Model Access," and 07d says "if you arrived from the step 07 access check... return to Write Your First Agentic Workflow." This is a documented detour-and-return pattern, not a genuine ordering defect. No fix needed.

Confirmed ordering problem

workshop/05-agentic-workflows-intro.md — Activity 1 references a file that does not exist yet

• File reviewed: workshop/05-agentic-workflows-intro.md
• Exact quoted instruction: "Activity 1 — identify the parts: Open any .lock.yml file in your repo and find the on: key."
• Missing prerequisite: No .lock.yml file exists in the learner's repository at this point in the workshop. The gh-aw CLI extension (which compiles .md workflow files into .lock.yml) is not installed until Step 6 — Install the gh-aw CLI Extension, and the first workflow file (and therefore the first .lock.yml) is not created and compiled until Step 7 — Write Your First Agentic Workflow (gh aw compile producing daily-report-status.lock.yml). Step 5 comes before both of these in the curriculum order (workshop/README.md rows 5, 6, 7).
• Why this could block or confuse a learner: A learner following the instructions literally in a freshly created my-agentic-workflows repository (per Step 2's setup) will find no .github/workflows/*.lock.yml file to open, because none has been generated yet. The example block in the same section (# Example: open .github/workflows/my-workflow.lock.yml) also references a filename that does not match any file the learner has created (daily-report-status.md is the actual name used starting in Step 7). This activity cannot be completed as written at this point in the workshop.
• Suggested fix: Either (a) move "Activity 1" to a later step (after Step 7, once daily-report-status.lock.yml exists), or (b) rewrite Activity 1 to use a pre-supplied read-only example .lock.yml snippet embedded directly in the page (so no live file is required), or (c) explicitly tell the learner this is a conceptual preview and point them to revisit the real compiled file once they reach Step 7/8 (adding a forward-reference note rather than an imperative "Open any .lock.yml file in your repo").

Status

Ready for an agent to resolve. Recommended scope: fix the Step 5 Activity 1 ordering problem described above; no changes needed for the three flagged cycles, which were reviewed and found to be intentional branch/detour patterns, not defects.

[!WARNING]

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• github.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "github.com"

See Network Configuration for more information.

Generated by 🧭 Workshop Order Review · copilot · auto · 96.8 AIC · ⌖ 5.64 AIC · ⊞ 8.5K · ◷

• expires on Oct 13, 2026, 7:05 AM UTC