fix(05): split agentic-workflows-intro to reduce cognitive load (#1787)

Copilot · web-flow · commit 7ce0449a0cef · 2026-07-21T11:33:03.000+02:00
diff --git a/workshop/05-agentic-workflows-intro.md b/workshop/05-agentic-workflows-intro.md
@@ -40,215 +40,16 @@ If you already write Actions YAML, the frontmatter stays the same (triggers, per
 - **What it produces:** A synthesized report or action the agent composes from live repository data — different every run based on what it finds.
 - **Why it exists:** Classic Actions handles deterministic CI/CD. Agentic workflows fill the gap for tasks that need judgment — or you can mix both in a single hybrid workflow.
 
-## Classify these tasks
-
-For each task below: classify it as **agentic workflow** or **standard Actions workflow**, check the box, then reveal the answer before the next task:
-
-You just saw how a standard Actions workflow follows fixed steps. Agentic workflows replace those fixed steps with a plain-English task brief — use that contrast to classify the tasks below.
-
-**Task A:** Run unit tests on every pull request, fail if any test exits non-zero, and upload coverage.
-
-- [ ] I have classified Task A
-
-<details>
-<summary>Check Task A answer</summary>
-
-**Task A — Standard Actions workflow:** every run follows the same fixed steps: start the test job, fail on a non-zero exit code, and upload the coverage artifact. No judgment required.
-
-</details>
-
-**Task B:** Review newly opened issues each morning, group them by theme, flag the urgent ones, and post a short triage summary.
-
-- [ ] I have classified Task B
-
-<details>
-<summary>Check Task B answer</summary>
-
-**Task B — Agentic workflow:** the agent has to inspect live repo context, group similar issues, and decide what looks urgent before it writes the summary.
-
-</details>
-
-## Reflection
-
-Before you check the reflection item in the checkpoint below, write one sentence describing what you would want _your_ agentic workflow to do. Put it wherever you keep workshop notes: your editor, a scratch file, or a notes app. Example: summarize new issues and flag urgent ones. Focus on a task that needs judgment, not a test or deploy script. You'll use this idea in later.
-
-## What the agent decided
-
-A scheduled agentic workflow generates a report like this:
-
-```markdown
-## Daily Repository Status — July 12
-
-- ✅ CI health: 18 workflows succeeded, 1 failed (`docs-link-check`)
-- 🔄 Pull requests: 7 open (2 need review, 1 stale > 14 days)
-- 🐛 Issues: 4 new, 3 closed, 2 high-priority still open
-- 🚀 Releases: No new tags in the last 24 hours
-
-### Recommended next actions
-1. Re-run `docs-link-check` and update broken external URLs.
-2. Review PR #412 and PR #415 before noon.
-3. Triage high-priority issue #398 with the platform team.
-```
-
-**Your turn:** Answer in your own words — _what did the agent decide on its own?_ Identify at least two lines where the agent made a judgment call rather than just reading a number.
-
-## Check your understanding
-
-Apply what you just saw — answer each question in your notes, then reveal.
-
-Should the daily report run on a schedule or wait for manual dispatch? State which and why.
-
-- [ ] I chose a trigger type and explained my reasoning
-
-<details>
-<summary>Check your answer</summary>
-
-A scheduled trigger runs automatically — appropriate for a daily report. `workflow_dispatch` requires a button click in the Actions tab.
-
-- [ ] Schedule: runs automatically, no button click needed
-- [ ] `workflow_dispatch`: requires a manual click each run
-
-</details>
-
-How does the agent post the report if it always operates read-only?
-
-- [ ] I explained how the agent writes output
-
-<details>
-<summary>Check your answer</summary>
-
-Agents always run read-only. Any writes — including posting the report — go through [safe outputs](https://github.github.com/gh-aw/reference/safe-outputs/) and guardrails.
-
-- [ ] The agent itself is always read-only
-- [ ] Writes happen through safe outputs and guardrails
-
-</details>
-
-Write one sentence for the task brief — this becomes your brief in Step 7.
-
-- [ ] I wrote my one-sentence brief
-- [ ] My brief describes a task that needs judgment, not fixed steps
-
-## The two files
-
-An agentic workflow has two files. Here is the `.md` source you write:
-
-```markdown
----
-on:
-  schedule: daily
-permissions:
-  issues: read
----
-
-Review all open issues, summarize the key themes, and post a short digest as a new issue.
-```
-
-> [!NOTE]
-> `schedule: daily` is fuzzy shorthand that `gh aw compile` converts into a standard Actions cron expression. You never write raw cron syntax in an agentic workflow `.md` file.
-
-And here is the `.lock.yml` `gh aw compile` generates — what GitHub Actions actually runs:
-
-```yaml
-# Auto-generated by gh aw compile. Do not edit by hand.
-name: Review open issues
-on:
-  schedule:
-    - cron: "0 8 * * *"
-permissions:
-  issues: read
-```
-
-Both files live in `.github/workflows/`. Look at them and answer: which part of the `.md` is the **task brief**, and which part tells GitHub Actions when to run?
-
-## Concept check — before you continue
-
-Before you reveal the answers below, write a one-sentence definition for each term:
-
-- [ ] Agentic workflow
-- [ ] Lock file
-- [ ] Engine
-- [ ] `workflow_dispatch`
-
-<details>
-<summary>Check your answers</summary>
-
-| Term | Plain-language meaning |
-|---|---|
-| Agentic workflow | A GitHub Actions workflow that uses an AI model to reason and act |
-| [Lock file](https://github.github.com/gh-aw/reference/glossary/#workflow-lock-file-lockyml) | The compiled YAML that GitHub Actions actually runs |
-| [Engine](https://github.github.com/gh-aw/reference/engines/) | The AI model provider (for example, GitHub Copilot) used by the workflow |
-| `workflow_dispatch` | A manual trigger — you start the run by clicking a button in the Actions tab |
-
-Confirm each:
-
-- [ ] Lock file: compiled, not hand-edited
-- [ ] Engine: AI model provider
-- [ ] `workflow_dispatch`: manual trigger from Actions
-- [ ] Agentic workflow: AI reasoning loop
-
-</details>
-
-If you had to look up more than one term, take a moment to review that section before continuing.
-
-## Classify more tasks
-
-**Task C:** Each Friday, scan all open issues and pull requests, summarize recent activity by contributor, and post a weekly team progress digest.
-
-- [ ] I have classified Task C
-
-<details>
-<summary>Check Task C answer</summary>
-
-**Task C — Agentic workflow:** the agent has to read contributor activity across issues and pull requests, decide what counts as meaningful progress, and compose a digest that differs every week.
-
-</details>
-
-**Task D:** On every pull request, run ESLint (fail on errors), then have an AI read the diff and post a summary comment.
-
-- [ ] I have classified Task D
-
-<details>
-<summary>Check Task D answer</summary>
-
-**Task D — Agentic (hybrid) workflow:** ESLint is deterministic — same result every run. The AI summary requires judgment: reading the diff and deciding how to describe the change. Combining fixed and AI steps makes a workflow agentic.
-
-- [ ] The ESLint step produces the same pass-or-fail result every run
-- [ ] The AI step produces different output based on what it reads in the diff
-- [ ] A workflow mixing deterministic and AI steps is still agentic overall
-
-</details>
-
-## Self-check
-
-What makes a workflow agentic rather than standard? Write your answer in your notes.
-
-- [ ] I wrote my self-check answer in my notes
-
-<details>
-<summary>Show model answer</summary>
-
-A workflow is agentic when an AI agent makes judgment calls — reading context, deciding what matters, and producing output that differs each run. Standard workflows follow fixed steps.
-
-Does your answer include:
-- [ ] AI making judgment calls on live context
-- [ ] Output that varies each run
-- [ ] Contrast with standard fixed-step workflows
-
-</details>
-
 > [!TIP]
-> If this still feels fuzzy, Step 7 makes the distinction concrete. Return here after Step 7.
+> Want to go deeper? [Side Quest: Agentic Workflows Deep Dive](side-quest-05-02-aw-deep-dive.md) covers exercises, example output, the two-file structure, and concept checks.
 
 ## ✅ Checkpoint
 
-- [ ] I described what an agentic workflow is in one sentence
+- [ ] I can describe what an agentic workflow is in one sentence
 - [ ] I can explain one way an agentic workflow differs from a standard Actions workflow
-- [ ] I can point to the task brief and the trigger in the sample `.md` file
-- [ ] I can describe the difference between the `.md` source file and the compiled `.lock.yml`
+- [ ] I can identify the three parts: trigger → agent → safe output
 
 <!-- journey: all -->
 **Next:** [Install the gh-aw CLI Extension](06-install-gh-aw.md)
 <!-- /journey -->
 
-
diff --git a/workshop/README.md b/workshop/README.md
@@ -41,6 +41,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo
 ## Optional Side Quests
 
 - [Side Quest: Agentic Workflows for GitHub Actions Power Users](side-quest-05-01-actions-power-user.md) — one-page cheat sheet for what changes vs what stays the same in agentic workflows; branches from [Step 5](05-agentic-workflows-intro.md).
+- [Side Quest: Agentic Workflows Deep Dive](side-quest-05-02-aw-deep-dive.md) — classification exercises, example agent output, the two-file structure, and concept checks; branches from [Step 5](05-agentic-workflows-intro.md).
 - [Side Quest: Terminal Basics](side-quest-01-01-terminal-basics.md) — optional primer that branches from [Step 1](01-prerequisites.md).
 - [Side Quest: Environment Reference](side-quest-01-02-environment-reference.md) — glossary of workshop environments and tool terms with official docs links; branches from [Step 1](01-prerequisites.md).
 - [Side Quest: Install `gh-aw` Troubleshooting](side-quest-06-01-install-troubleshooting.md) — optional install troubleshooting reference that branches from [Step 6](06-install-gh-aw.md).
diff --git a/workshop/side-quest-05-02-aw-deep-dive.md b/workshop/side-quest-05-02-aw-deep-dive.md
