[side-quest] Extract PR reviewer troubleshooting side quest

workshop/14b-pr-reviewer-workflow.md

@@ -134,19 +134,9 @@ In the run log, confirm that the parent calls `pr-reviewer` and that the reviewe
 
 To test the manual path, add a `/review` comment to the pull request. After pushing another commit, use `/review` again instead of moving the pull request back to draft.
 
-> [!NOTE]
-> If no run starts, confirm that the workflow is on your default branch and that you changed the pull request from draft to ready. Opening a pull request as ready does not emit the `ready_for_review` event.
+If something doesn't look right (no run started, or the review doesn't cite changed lines or mention `pr-review-standards`), the fix is usually quick.
 
-If the run completes but the review does not mention the `pr-review-standards` skill or does not cite changed files and lines, the reviewer likely could not find the skills directory. Use this checklist to recover:
-
-1. Confirm `.github/skills/agentic-workflows/` exists and was pushed. Run `ls .github/skills/` in your terminal. If the directory is missing, run `gh aw init`, commit the generated files, and push.
-2. If the directory exists but the skill was still not applied, ask the agent to reinforce the instruction:
-
-```prompt
-/agentic-workflows Update .github/workflows/pr-reviewer.md so the pr-reviewer agent explicitly searches for and applies the pr-review-standards skill before returning findings.
-```
-
-1. Compile, commit, and re-trigger `/review` to confirm the skill is now applied.
+> **Optional Side Quest:** Stuck, or just curious how to diagnose a missing run or a skipped skill? Work through [Side Quest: Troubleshoot Your PR Reviewer Run](side-quest-14-01-pr-reviewer-troubleshooting.md), then come back here.
 
 ## Improve One Layer
 

workshop/README.md

@@ -72,6 +72,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo
 - [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 14b](14b-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 14b](14b-pr-reviewer-workflow.md).
 - [Observe and Reduce Token Costs](side-quest-13-04-token-optimization.md) — hands-on optimization activity for building an AIC baseline, auditing expensive runs, identifying cost drivers, and testing one token-reduction change at a time; branches from [Step 14b](14b-pr-reviewer-workflow.md).
+- [Troubleshoot Your PR Reviewer Run](side-quest-14-01-pr-reviewer-troubleshooting.md) — checklist for runs that never start and reviews that skip the `pr-review-standards` skill; branches from [Step 14b](14b-pr-reviewer-workflow.md).
 - [Fuzzy Schedule Expressions](side-quest-09-02-schedule-expressions.md) — quick reference for choosing between `daily`, `hourly`, `weekly`, and other fuzzy schedule expressions; branches from [Step 9](09-agentic-editing.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 9](09-agentic-editing.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).

workshop/side-quest-14-01-pr-reviewer-troubleshooting.md

@@ -0,0 +1,49 @@
+<!-- page-journey: all -->
+<!-- page-adventure: side-quest -->
+# Side Quest: Troubleshoot Your PR Reviewer Run
+
+> _Find out why your PR reviewer didn't run, or why its review ignored the skill, and fix it in a few minutes._
+
+## :dart: What You'll Do
+
+You'll diagnose the two most common problems with the PR reviewer from [Build a PR Reviewer with an Agent and Skill](14b-pr-reviewer-workflow.md): no run starts, or the run completes but the review doesn't apply the `pr-review-standards` skill.
+
+## :clipboard: Before You Start
+
+- You created and pushed `.github/workflows/pr-reviewer.md` and its `.lock.yml` in [Build a PR Reviewer with an Agent and Skill](14b-pr-reviewer-workflow.md).
+- You tried the ready-for-review trigger or the `/review` command at least once.
+
+## Steps
+
+### No run started
+
+Confirm each of these:
+
+1. The workflow and its `.lock.yml` are on your default branch.
+2. You changed the pull request from **draft** to **Ready for review**.
+
+> [!NOTE]
+> Opening a pull request as ready does not emit the `ready_for_review` event. Open it as a draft first, or use `/review` in a comment.
+
+### The review doesn't use the skill
+
+If the run completes but the review doesn't mention the `pr-review-standards` skill or doesn't cite changed files and lines, the reviewer likely could not find the skills directory.
+
+1. Confirm `.github/skills/agentic-workflows/` exists and was pushed. Run `ls .github/skills/` in your terminal. If the directory is missing, run `gh aw init`, commit the generated files, and push.
+2. If the directory exists but the skill was still not applied, ask your agent to reinforce the instruction:
+
+```prompt
+/agentic-workflows Update .github/workflows/pr-reviewer.md so the pr-reviewer agent explicitly searches for and applies the pr-review-standards skill before returning findings.
+```
+
+3. Compile, commit, and push, then comment `/review` on the pull request to confirm the skill is now applied.
+
+## :white_check_mark: Checkpoint
+
+- [ ] You can explain why opening a pull request as ready doesn't trigger `ready_for_review`
+- [ ] You confirmed `.github/skills/` exists in your repository
+- [ ] A fresh `/review` run cites changed files and lines
+
+<!-- journey: all -->
+**Return to the main adventure:** [Build a PR Reviewer with an Agent and Skill](14b-pr-reviewer-workflow.md)
+<!-- /journey -->