Reduce cognitive load and raise active learning density in 11d2-review-and-merge.md

workshop/11d2-review-and-merge.md

@@ -1,29 +1,21 @@
 # Adventure D (Part 2): Monitor, Review, and Merge
 
-> _Once you have submitted the scenario prompt, you'll monitor the agent session, steer it if needed, review its pull request, and merge your workflow._
+> _Once the agent session ends, you'll review its pull request, ask for any revisions, and merge your workflow._
 
-**Previous:** [Adventure D: Build Any Workflow with GitHub Copilot](11d-build-copilot-agents.md)
+## 📋 Before You Start
+
+- **Step 11d complete** — you have submitted the scenario prompt in [Adventure D: Build Any Workflow with GitHub Copilot](11d-build-copilot-agents.md)
+- **Agent session running or finished** — the session you started is in progress or has completed
+- **Practice repository open** — your practice repository is open in the browser so you can view the pull request
 
 ---
 
 ## Monitor Your Session
 
-After submitting the prompt, the session shows a live activity feed. You will see the agent working through several phases:
-
-| Phase | What you see |
-|---|---|
-| **Reading** | The agent fetches the `create.md` reference and reads existing files in your repository |
-| **Planning** | The agent decides what frontmatter keys, permissions, and task brief to use |
-| **Writing** | The agent creates the workflow `.md` file in `.github/workflows/` |
-| **Compiling** | The agent runs `gh aw compile --validate` and fixes any errors it finds |
-| **Opening PR** | The agent commits both files and opens a pull request |
-
-The session typically completes in two to five minutes. You can steer it with follow-up prompts if it needs more context or takes the wrong direction. Follow along in the activity feed and expand individual steps to see exactly what the agent wrote, read, or ran — this is a good way to learn the agentic workflow format without writing it yourself.
+After submitting the prompt, watch the activity feed. The agent works through five phases: **Reading** → **Planning** → **Writing** → **Compiling** → **Opening PR**. The session typically completes in two to five minutes. You can steer it with follow-up prompts if it needs more context or takes the wrong direction.
 
-> [!IMPORTANT]
-> - The agent runs `gh aw compile ... --validate` in its session workspace and can install `gh-aw` there if needed.
-> - For manual validation or to run `gh aw compile ... --watch` yourself, install `gh-aw` locally or in Codespaces by following [Step 6](06-install-gh-aw.md).
-> - Use the GitHub **Actions tab** in [Step 12](12-test-and-iterate.md) to trigger the workflow and inspect its runtime logs.
+> [!TIP]
+> For a full breakdown of each phase, what to look for, and how to steer the session, see [Side Quest: Agent Session Phases Explained](side-quest-11-09-agent-session-phases.md).
 
 ---
 
@@ -40,26 +32,28 @@ The PR adds two files:
 | `.github/workflows/<name>.md` | Frontmatter keys match the scenario; the task brief describes what you want; `safe-outputs` limits write actions |
 | `.github/workflows/<name>.lock.yml` | Exists and is non-empty — this is the compiled GitHub Actions YAML that the runner executes |
 
-Look through the workflow Markdown body. The agent should have written a clear task brief based on the prompt you provided. If anything looks wrong — wrong schedule, missing permission, overly broad task brief — ask the agent to revise it:
+### ✏️ Exercise: inspect the diff and request a revision
 
-- **GitHub Copilot app:** start or continue a session for the pull request and describe the change.
-- **Agents tab:** leave a review comment that starts with `@copilot`, for example:
+1. Open the pull request the agent created.
+2. In the **Files changed** tab, click `.github/workflows/<name>.lock.yml` and confirm the file is non-empty — you are looking at the compiled YAML the runner will execute.
+3. Read the task brief in `.github/workflows/<name>.md`. Check that the schedule, permission scope, and `safe-outputs` action match your intended scenario.
+4. If anything looks wrong, post a revision request in the PR comment box. Start the comment with `@copilot`:
 
 ```
 @copilot Please change the schedule to weekly instead of daily.
 ```
 
 > [!IMPORTANT]
-> In the browser PR flow, comments directed at the Copilot agent **must** begin with `@copilot`. Without it, the agent will not see or act on your message.
+> Comments directed at the Copilot agent **must** begin with `@copilot`. Without it, the agent will not see or act on your message. You can also start or continue a session for the PR in the GitHub Copilot app.
 
-The agent will push an updated commit to the same branch.
+The agent will push an updated commit to the same branch. If everything looks correct, skip step 4 and proceed to merge.
 
 ### Merge the pull request
 
 Once you are satisfied with the workflow:
 
-1. In the browser, click **Merge pull request** and **Confirm merge**. In the GitHub Copilot app, merge from the pull request view or enable [**agent merge**](https://docs.github.com/en/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests#merging-a-pull-request), which asks the agent to fix blockers and merge after required reviews and checks pass.
-2. Confirm that the pull request is merged.
+1. In the browser, click **Merge pull request** and **Confirm merge**.
+2. Confirm that both workflow files are on your default branch.
 3. Delete the branch (optional but recommended).
 
 The workflow is now live on your default branch. GitHub Actions will pick it up on the next scheduled trigger or when you click **Run workflow** in the Actions tab.
@@ -72,27 +66,28 @@ After merging, your repository contains:
 
 | File | Purpose |
 |---|---|
-| `.github/workflows/<name>.md` | The Markdown task brief — the human-readable workflow definition the agent and you can edit |
+| `.github/workflows/<name>.md` | The Markdown task brief — the human-readable workflow definition you and the agent can edit |
 | `.github/workflows/<name>.lock.yml` | The compiled GitHub Actions YAML — generated automatically, do not edit by hand |
 
-You can continue iterating through a GitHub Copilot app or Agents-tab session and let the agent handle edits and recompilation. If you want a persistent validation loop or direct CLI control, follow [Step 6: Install the gh-aw CLI Extension](06-install-gh-aw.md) and use `gh aw compile --watch` in a local or Codespaces terminal.
+You can continue iterating through a GitHub Copilot app or Agents-tab session and let the agent handle edits and recompilation.
 
 ---
 
 ## ✅ Checkpoint
 
-- [ ] The agent session completed and the activity feed shows all five phases (Reading, Planning, Writing, Compiling, Opening PR)
-- [ ] You opened the pull request and confirmed both `.github/workflows/<name>.md` and `.github/workflows/<name>.lock.yml` are present in the diff
-- [ ] You reviewed the workflow task brief and used `@copilot` feedback (or an app session) to correct anything that looked wrong before merging
-- [ ] You merged the pull request into your default branch
-- [ ] Both workflow files exist in your repository after merging
-- [ ] The workflow is visible in the GitHub Actions tab
+- [ ] The agent session completed and the pull request is open in your practice repository
+- [ ] The PR diff shows both `.github/workflows/<name>.md` and `.github/workflows/<name>.lock.yml`
+- [ ] You opened `.github/workflows/<name>.lock.yml` in the PR diff and confirmed it is non-empty
+- [ ] You reviewed the task brief and posted a `@copilot` revision comment (or confirmed no changes were needed)
+- [ ] You merged the pull request and both workflow files exist on your default branch
+- [ ] The workflow appears in the GitHub Actions tab of your practice repository
 
 **Previous:** [Adventure D: Build Any Workflow with GitHub Copilot](11d-build-copilot-agents.md)
 **Next:** [Step 12: Test and Improve Your Workflow](12-test-and-iterate.md)
 
 ## 📚 See Also
 
+- [Side Quest: Agent Session Phases Explained](side-quest-11-09-agent-session-phases.md)
 - [Overview of GitHub Agentic Workflows](https://github.github.com/gh-aw/introduction/overview/)
 - [About the GitHub Copilot app](https://docs.github.com/en/copilot/concepts/agents/github-copilot-app)
 - [Managing issues and pull requests with the GitHub Copilot app](https://docs.github.com/en/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests)

workshop/README.md

@@ -85,6 +85,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo
 - [Side Quest: Configure an OpenAI API Key](side-quest-11-07-openai-key.md) — step-by-step guide to generating an OpenAI key, storing it as a repository secret, and switching your workflow to `engine: codex`; branches from [Step 11a](11a-build-daily-status.md).
 - [Side Quest: Choosing Between Cache Memory and Repo Memory](side-quest-20-01-memory-patterns.md) — decision guide, full field references, and example task briefs for both `cache-memory` and `repo-memory`; branches from [Step 20](20-persistent-memory.md).
 - [Side Quest: Sub-Agent Syntax Reference](side-quest-21-01-sub-agent-syntax.md) — name rules, block boundary rules, supported frontmatter fields, and model alias table for inline sub-agents; branches from [Step 21](21-inline-sub-agents.md).
+- [Side Quest: Agent Session Phases Explained](side-quest-11-09-agent-session-phases.md) — full phase reference table, activity feed tips, steering prompts, and advanced agent merge / `--watch` paths; branches from [Step 11d2](11d2-review-and-merge.md).
 
 ## Getting Started
 

workshop/side-quest-11-09-agent-session-phases.md

@@ -0,0 +1,60 @@
+# Side Quest: Agent Session Phases Explained
+
+> _Optional: take this detour for a full breakdown of what happens inside the agent session, then return to [Adventure D (Part 2): Monitor, Review, and Merge](11d2-review-and-merge.md)._
+
+## 🎯 What You'll Learn
+
+You'll learn what each phase of the agent session does, what to look for in the activity feed, and how to steer the session if it takes the wrong direction.
+
+## The Five Phases
+
+After you submit the scenario prompt, the session shows a live activity feed. The agent works through five phases:
+
+| Phase | What you see | What to look for |
+|---|---|---|
+| **Reading** | The agent fetches the `create.md` reference and reads existing files in your repository | Confirm the agent fetched the reference guide and found your repository files |
+| **Planning** | The agent decides what frontmatter keys, permissions, and task brief to use | The planning output should reflect your intended scenario |
+| **Writing** | The agent creates the workflow `.md` file in `.github/workflows/` | The file should contain a YAML frontmatter block between `---` fences and a Markdown task brief |
+| **Compiling** | The agent runs `gh aw compile --validate` and fixes any errors it finds | A green success message indicates the `.lock.yml` was generated without errors |
+| **Opening PR** | The agent commits both files and opens a pull request | The pull request should list two changed files: the `.md` source and the `.lock.yml` |
+
+## Steering the Session
+
+The session typically completes in two to five minutes. If the agent takes the wrong direction, you can steer it with follow-up prompts. For example:
+
+- If the agent is building the wrong scenario: _"Stop — I want Scenario A (daily status report), not Scenario B."_
+- If the agent skips compilation: _"Please compile the workflow with `gh aw compile --validate` before opening the pull request."_
+- If the agent opens a PR before the lock file is present: _"The lock file is missing. Please run `gh aw compile .github/workflows/daily-status.md --validate` (replace `daily-status` with your actual workflow filename) and add the generated `.lock.yml` to the pull request."_
+
+## Expanding Activity Feed Steps
+
+Expand individual steps in the activity feed to see exactly what the agent wrote, read, or ran. This is a good way to learn the agentic workflow format without writing it yourself. Look for:
+
+- The full contents of the `.md` file the agent wrote
+- The `gh aw compile` command it ran and any errors it fixed
+- The commit message and branch name it used
+
+## Advanced: Agent Merge
+
+The GitHub Copilot app supports [**agent merge**](https://docs.github.com/en/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests#merging-a-pull-request): enable it from the pull request view and the agent will fix any blockers and merge after required reviews and checks pass. This is an optional shortcut — you can always merge manually in the browser.
+
+## Advanced: Continuous Compilation with `--watch`
+
+If you want a live compile feedback loop while editing a workflow by hand, install the `gh-aw` CLI (see [Step 6](06-install-gh-aw.md)) and run:
+
+```bash
+gh aw compile .github/workflows/<name>.md --watch
+```
+
+Each save triggers another compile, so you get immediate feedback instead of discovering YAML mistakes later. See [Side Quest: Using `gh aw compile` to Catch Errors Early](side-quest-07-01-compile-workflow.md) for a full walkthrough.
+
+## ✅ Checkpoint
+
+- [ ] I can name the five phases of an agent session in order
+- [ ] I know what a successful Compiling phase looks like (green success message, `.lock.yml` generated)
+- [ ] I know how to steer the session if it takes the wrong direction
+- [ ] I can expand individual steps in the activity feed to inspect what the agent did
+
+---
+
+Return to [Adventure D (Part 2): Monitor, Review, and Merge](11d2-review-and-merge.md).