feat: add PR reviewer patterns workshop activities (step 13 + 3 side quests) (#1912)

Copilot · pelikhan · web-flow · commit e7312968affa · 2026-07-23T06:48:58.000-07:00
Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
Co-authored-by: pelikhan &lt;4175913+pelikhan@users.noreply.github.com&gt;
diff --git a/.github/skills/micro-environment-simulator/workshop-student-journey.js b/.github/skills/micro-environment-simulator/workshop-student-journey.js
@@ -52,6 +52,7 @@ const STEP_FILE_ALIASES = {
   "08b-interpret-your-run": ["08b-interpret-your-run.md"],
   "09-agentic-editing": ["09-agentic-editing.md"],
   "12-test-and-iterate": ["12-test-and-iterate.md"],
+  "13-pr-reviewer-workflow": ["13-pr-reviewer-workflow.md"],
   "14-next-steps": ["14-next-steps.md"],
   "15-conditional-logic": ["15-conditional-logic.md"],
   "16-connect-data-source": ["16-connect-data-source.md"],
@@ -81,6 +82,7 @@ const STEP_IDS = [
   "08b-interpret-your-run",
   "09-agentic-editing",
   "12-test-and-iterate",
+  "13-pr-reviewer-workflow",
   "14-next-steps",
   "15-conditional-logic",
   "16-connect-data-source",
diff --git a/workshop/12-test-and-iterate.md b/workshop/12-test-and-iterate.md
@@ -95,5 +95,5 @@ If you want a stricter review loop, score each run for accuracy, completeness, a
 - [ ] I compared the new run with the previous run and decided what to change next
 
 <!-- journey: all -->
-**Next:** [What's Next? Keep Exploring](14-next-steps.md)
+**Next:** [Build Your First Event-Driven Workflow: PR Auto-Reviewer](13-pr-reviewer-workflow.md)
 <!-- /journey -->
diff --git a/workshop/13-pr-reviewer-workflow.md b/workshop/13-pr-reviewer-workflow.md
@@ -0,0 +1,136 @@
+<!-- page-journey: all -->
+<!-- page-adventure: advanced -->
+# Build Your First Event-Driven Workflow: PR Auto-Reviewer
+
+_You've built a scheduled workflow. Now build one that fires when something happens — and posts a useful review the moment a pull request opens._
+
+## 🎯 What You'll Do
+
+Create a new agentic workflow triggered by the `pull_request` event. When a contributor opens or updates a PR, your workflow will read the changed files and the PR description, then post an automated review comment summarising what changed and flagging anything worth a second look.
+
+By the end you will have a working PR reviewer workflow and understand how event-driven triggers differ from scheduled ones.
+
+## 📋 Before You Start
+
+- You have a working `daily-report-status` workflow from [Test and Improve Your Workflow](12-test-and-iterate.md).
+- You understand the two-file structure (`.md` source + `.lock.yml`) from earlier steps.
+
+## Why Event-Driven Triggers?
+
+Your daily-status workflow runs on a schedule — it wakes up on its own, checks what happened, and reports. A PR reviewer workflow is different: it runs the moment a developer opens or updates a pull request, with the full PR context handed to it automatically.
+
+This is the `pull_request` trigger:
+
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize]
+```
+
+`opened` fires when a PR is first created. `synchronize` fires every time a new commit is pushed to the PR branch. Together they cover the full PR lifecycle without any manual intervention.
+
+Event-driven workflows are the foundation of most real-world agentic review automation. The same pattern powers auto-labellers, summary generators, and quality checklists — three of which you can explore in the side quests at the end of this step.
+
+## Create the Workflow File
+
+In your practice repository, create `.github/workflows/pr-reviewer.md`:
+
+```markdown
+---
+name: PR Auto-Reviewer
+on:
+  pull_request:
+    types: [opened, synchronize]
+permissions:
+  pull-requests: write
+  contents: read
+safe-outputs:
+  create-issue-comment:
+    limit: 1
+---
+
+You are a helpful PR reviewer. When a pull request is opened or updated:
+
+1. Read the list of changed files and the PR title and description.
+2. Write a short summary (3–5 sentences) of what the PR does.
+3. List up to three things a reviewer should pay close attention to, based on the file names and PR description alone.
+4. Post the summary and checklist as a single comment on the pull request.
+
+Keep the tone constructive and specific. Do not speculate about code you have not seen.
+```
+
+A few things to notice in this frontmatter:
+
+- `permissions: pull-requests: write` lets the agent post a comment on the PR.
+- `safe-outputs: create-issue-comment: limit: 1` caps the workflow at one comment per run, preventing spam if the workflow is triggered repeatedly.
+- The agent brief uses only information available in the trigger context (changed file paths, PR title, PR description) — it does not need to read raw file contents to produce a useful first-pass review.
+
+## Compile and Push
+
+From your repository root, compile the workflow:
+
+```bash
+gh aw compile
+```
+
+Then commit both files:
+
+```bash
+git add .github/workflows/pr-reviewer.md .github/workflows/pr-reviewer.lock.yml
+git commit -m "feat: add PR auto-reviewer workflow"
+git push
+```
+
+> [!TIP]
+> If you want to watch the compiler update the lock file every time you save, run `gh aw compile --watch` instead and keep it running in a background terminal while you edit.
+
+## Test It by Opening a PR
+
+Create a small branch with a trivial change — for example, add a comment to any file — and open a pull request against your default branch.
+
+The workflow fires automatically within a few seconds of the PR being created. To watch it:
+
+1. Go to the **Actions** tab of your repository.
+2. Find the **PR Auto-Reviewer** run next to your pull request.
+3. Open the run and watch the agent step process the PR context.
+4. Navigate back to the pull request and check the **Conversation** tab — your automated review comment should appear there.
+
+![PR auto-reviewer comment posted by the workflow](images/13-pr-reviewer-comment.svg)
+
+## Inspect the Agent's Reasoning
+
+Open the run log and look for the agent's `[plan]` and `[tool]` lines. You should see the agent:
+
+1. Reading the PR metadata (title, description, file list).
+2. Planning its summary based on available context.
+3. Calling the `create-issue-comment` tool to post the result.
+
+If the agent posted a comment but it feels generic, the brief is working but may need tightening. Try adding a sentence like:
+
+```text
+When the PR only touches test files, note that explicitly and skip the "things to watch" list.
+```
+
+Then recompile, push, and update the PR branch to trigger another run.
+
+## ✅ Checkpoint
+
+- [ ] I created `.github/workflows/pr-reviewer.md` with a `pull_request` trigger
+- [ ] `gh aw compile` completed without errors and `.lock.yml` is committed and pushed
+- [ ] I opened a test pull request and the workflow triggered automatically
+- [ ] The workflow posted exactly one comment on my pull request
+- [ ] I can explain why `safe-outputs: create-issue-comment: limit: 1` matters for an event-driven workflow
+
+<!-- journey: all -->
+**Next:** [What's Next? Keep Exploring](14-next-steps.md)
+<!-- /journey -->
+
+---
+
+## Go Further: PR Reviewer Patterns
+
+Ready to extend this workflow? These side quests each cover a popular PR reviewer pattern:
+
+- [Pattern: Auto-Label PRs by Content](side-quest-13-01-pr-labeler-pattern.md) — apply labels based on which files changed.
+- [Pattern: Generate a PR Summary Comment](side-quest-13-02-pr-summary-pattern.md) — post a structured summary that PR authors can use as a release note draft.
+- [Pattern: PR Review Checklist](side-quest-13-03-pr-checklist-pattern.md) — check PRs against a quality checklist and post results.
diff --git a/workshop/README.md b/workshop/README.md
@@ -26,6 +26,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo
 | 8b | [Interpret Your First Run](08b-interpret-your-run.md) |
 | 9 | [Refine Your Workflow with Agentic Editing](09-agentic-editing.md) |
 | 12 | [Test and Improve Your Workflow](12-test-and-iterate.md) |
+| 13 | [Build Your First Event-Driven Workflow: PR Auto-Reviewer](13-pr-reviewer-workflow.md) |
 | 14 | [What's Next? Keep Exploring](14-next-steps.md) |
 
 ## Curriculum — Part 2: Go Deeper
@@ -59,6 +60,9 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo
 - [Jailbreaking the Agent Brief](side-quest-10-02-jailbreak-brief.md) — explains how adversarial instructions embedded in repository content attempt to override the agent's task brief, and how the compiled brief, minimal `permissions:`, `safe-outputs`, and `network.allowed-domains` contain any partial success; branches from [Step 10](09-agentic-editing.md).
 - [Frontmatter Deep Dive — Part A](side-quest-11-01-frontmatter-deep-dive.md) — walkthrough of the opening, trigger, and permissions sections of `gh-aw` frontmatter, with predict-and-try activities; branches from [Step 11a](07-your-first-workflow.md).
 - [Frontmatter Deep Dive — Part B](side-quest-11-08-frontmatter-tools-outputs.md) — walkthrough of the tools, safe-outputs, closing fence, and agent body sections, with predict-and-try activities; continues from Part A.
+- [Pattern: Auto-Label PRs by Content](side-quest-13-01-pr-labeler-pattern.md) — apply labels automatically based on which files changed in a pull request; branches from [Step 13](13-pr-reviewer-workflow.md).
+- [Pattern: Generate a PR Summary Comment](side-quest-13-02-pr-summary-pattern.md) — post a structured, changelog-ready summary comment when a pull request opens; branches from [Step 13](13-pr-reviewer-workflow.md).
+- [Pattern: PR Review Checklist](side-quest-13-03-pr-checklist-pattern.md) — evaluate pull requests against a quality checklist and post a pass/fail table; branches from [Step 13](13-pr-reviewer-workflow.md).
 - [Fuzzy Schedule Expressions](side-quest-13-01-schedule-expressions.md) — quick reference for choosing between `daily`, `hourly`, `weekly`, and other fuzzy schedule expressions; branches from [Step 13](12-test-and-iterate.md).
 - [Evaluating and Iterating on Agent Output](side-quest-12-01-iterate-agent-output.md) — structured rubric for judging output quality, a five-row problem-to-fix reference table, and a one-change-at-a-time iteration loop; branches from [Step 12](12-test-and-iterate.md).
 - [GitHub Actions Expressions and Contexts](side-quest-15-01-expressions-and-contexts.md) — deep dive into `${{ }}` syntax, available context objects, output references, and `if:` conditions; branches from [Step 15](15-conditional-logic.md).
diff --git a/workshop/side-quest-13-01-pr-labeler-pattern.md b/workshop/side-quest-13-01-pr-labeler-pattern.md
@@ -0,0 +1,90 @@
+<!-- page-journey: all -->
+<!-- page-adventure: side-quest -->
+# Side Quest 13-01: Pattern — Auto-Label PRs by Content
+
+## 🎯 What You'll Do
+
+Extend your PR reviewer workflow to automatically apply GitHub labels based on the files that changed in a pull request.
+
+## Before You Start
+
+- Complete [Build Your First Event-Driven Workflow: PR Auto-Reviewer](13-pr-reviewer-workflow.md).
+- Your practice repository has at least one label already created. If not, go to **Issues → Labels** in your repository and create labels like `documentation`, `tests`, and `bug-fix`.
+
+## Why Auto-Labelling?
+
+Labels help teams filter and prioritise pull requests at a glance. Applying them manually is easy to forget, especially on busy repositories. An agentic labeller reads the list of changed files and applies the right labels before a human reviewer opens the PR.
+
+The pattern is simple: map file path patterns to label names in your workflow brief, then instruct the agent to pick and apply the matching labels.
+
+## The Labeller Workflow
+
+Create `.github/workflows/pr-labeler.md`:
+
+```markdown
+---
+name: PR Labeler
+on:
+  pull_request:
+    types: [opened, synchronize]
+permissions:
+  pull-requests: write
+  contents: read
+safe-outputs:
+  add-labels-to-pull-request:
+    limit: 5
+---
+
+You are a pull request labeller. When a pull request is opened or updated:
+
+1. Read the list of changed files from the pull request context.
+2. Apply labels to the pull request using these rules:
+   - If any changed file is under `docs/` or has a `.md` extension → apply `documentation`
+   - If any changed file is under `tests/` or has a `.test.` or `.spec.` pattern → apply `tests`
+   - If the PR title or description contains the word "fix" or "bug" (case-insensitive) → apply `bug-fix`
+3. Apply only the labels that match. Do not remove labels already present.
+4. If no rule matches, do not apply any label and do not post a comment.
+```
+
+Compile and push:
+
+```bash
+gh aw compile
+git add .github/workflows/pr-labeler.md .github/workflows/pr-labeler.lock.yml
+git commit -m "feat: add PR labeller workflow"
+git push
+```
+
+## Test It
+
+Open a test pull request that touches a Markdown file. After the workflow runs, check the pull request sidebar — the `documentation` label should appear automatically.
+
+Then open another PR that touches a test file and verify the `tests` label is applied.
+
+## Hands-On Exercise
+
+The current rules use simple path patterns. Extend the labeller to also apply a `config-change` label when any file under `.github/` or named `*.yaml` / `*.yml` changes.
+
+<details>
+<summary>Show one way to add this rule</summary>
+
+Add this rule to the workflow brief:
+
+```text
+- If any changed file is under `.github/` or has a `.yaml` or `.yml` extension → apply `config-change`
+```
+
+Compile, push, and test with a PR that changes a workflow file.
+
+</details>
+
+## ✅ Checkpoint
+
+- [ ] I created `.github/workflows/pr-labeler.md` with a `pull_request` trigger
+- [ ] `gh aw compile` completed without errors and `.lock.yml` is committed and pushed
+- [ ] I opened a test PR and the workflow applied the correct label automatically
+- [ ] I can explain why `safe-outputs: add-labels-to-pull-request` is the right surface for this pattern
+- [ ] I extended the labeller to handle at least one additional file-path rule
+
+<!-- journey: all -->
+<!-- /journey -->
diff --git a/workshop/side-quest-13-02-pr-summary-pattern.md b/workshop/side-quest-13-02-pr-summary-pattern.md
@@ -0,0 +1,88 @@
+<!-- page-journey: all -->
+<!-- page-adventure: side-quest -->
+# Side Quest 13-02: Pattern — Generate a PR Summary Comment
+
+## 🎯 What You'll Do
+
+Build a PR summary workflow that posts a structured, human-readable summary comment when a pull request is opened. The summary is written in a format that can be copied directly into a changelog or release note.
+
+## Before You Start
+
+- Complete [Build Your First Event-Driven Workflow: PR Auto-Reviewer](13-pr-reviewer-workflow.md).
+
+## Why a Structured Summary?
+
+A free-form review comment is useful, but a structured summary is re-usable. When every PR gets a summary in the same format, teams can scrape those comments to generate changelogs automatically, hand them to release managers as draft notes, or include them in sprint retrospectives.
+
+The key design choice here is the output template: you define the structure in the workflow brief, and the agent fills in the blanks.
+
+## The Summary Workflow
+
+Create `.github/workflows/pr-summary.md`:
+
+```markdown
+---
+name: PR Summary Generator
+on:
+  pull_request:
+    types: [opened]
+permissions:
+  pull-requests: write
+  contents: read
+safe-outputs:
+  create-issue-comment:
+    limit: 1
+---
+
+You are a changelog assistant. When a pull request is opened:
+
+1. Read the PR title, description, and list of changed files.
+2. Write a summary using exactly this template:
+
+   ## Summary
+   <!-- One sentence describing what this PR does. -->
+
+   ## Changes
+   <!-- Bullet list of the main areas touched, based on file paths. One bullet per distinct area. Maximum five bullets. -->
+
+   ## Notes for reviewers
+   <!-- One or two sentences flagging anything that needs special attention. If nothing stands out, write "No special concerns." -->
+
+3. Post the summary as a comment on the pull request.
+4. Do not add any text outside the template structure.
+```
+
+Compile and push:
+
+```bash
+gh aw compile
+git add .github/workflows/pr-summary.md .github/workflows/pr-summary.lock.yml
+git commit -m "feat: add PR summary generator workflow"
+git push
+```
+
+## Test It
+
+Open a test pull request. The workflow fires on `opened` only (not on every push), so you will see exactly one comment per new PR. Check that the output matches the three-section template.
+
+## Hands-On Exercise: Customise the Template
+
+The template above is generic. Adapt it to your team's actual workflow by changing one section.
+
+Ideas:
+- Replace **Notes for reviewers** with **Testing instructions** — ask the agent to suggest one manual test based on the changed file names.
+- Add a **Breaking changes** section — ask the agent to flag any file deletion or rename that might indicate a breaking change.
+- Replace **Summary** with **Ticket reference** — ask the agent to extract a ticket number from the PR title (for example `[PROJ-123]`) or write "No ticket found" if none is present.
+
+After making your change, recompile and open a fresh PR to see the updated output.
+
+## ✅ Checkpoint
+
+- [ ] I created `.github/workflows/pr-summary.md` with an `opened`-only `pull_request` trigger
+- [ ] `gh aw compile` completed without errors and `.lock.yml` is committed and pushed
+- [ ] I opened a test PR and the workflow posted a comment matching the three-section template
+- [ ] I customised at least one section of the template to fit a real use case
+- [ ] I can explain why triggering only on `opened` (not `synchronize`) is the right choice for a summary workflow
+
+<!-- journey: all -->
+<!-- /journey -->
diff --git a/workshop/side-quest-13-03-pr-checklist-pattern.md b/workshop/side-quest-13-03-pr-checklist-pattern.md
