[side-quest] Extract failure-modes primer from Step 22 into optional side quest - #2949
Merged
Merged
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
github-actions
Bot
added
documentation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
pelikhan
approved these changes
Sep 5, 2026
pelikhan
marked this pull request as ready for review
September 5, 2026 15:39
Copilot stopped reviewing on behalf of
pelikhan due to an error
September 5, 2026 15:39
There was a problem hiding this comment.
Note
Copilot could not run the full agentic suite for this review because it was automatically requested on a bot-authored pull request. Request a review from Copilot under Reviewers to retry with the full agentic suite. Improved support for bot-authored pull requests is coming soon.
Pull request overview
Adds a new “Side Quest” document that teaches common agentic workflow failure modes, and updates the main Step 22 doc + workshop index to reference it.
Changes:
- Added a new side-quest markdown page covering four failure modes + a practice exercise.
- Linked the side quest from the Step 22 resilience lesson via an optional callout.
- Added the side quest to the workshop README side-quest list.
Show a summary per file
| File | Description |
|---|---|
| workshop/side-quest-22-01-failure-modes.md | New side quest doc introducing four failure modes, visuals, and a practice section |
| workshop/README.md | Adds the new side quest to the side-quest index list |
| workshop/22-error-handling-and-resilience.md | Replaces the embedded failure-mode table/diagram with a TIP linking to the new side quest |
Review details
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Files reviewed: 3/3 changed files
- Comments generated: 5
- Review effort level: Lite
Comment on lines
+23
to
+28
| > <details> | ||
| > <summary><b>Optional Side Quest:</b> Want a worked example of each failure mode and practice matching failures to fixes before you dive in?</summary> | ||
| > | ||
| > Work through [Side Quest: Recognizing Common Agentic Workflow Failure Modes](side-quest-22-01-failure-modes.md), then come back here. | ||
| > | ||
| > </details> |
Comment on lines
106
to
+109
| - [Self-Hosted Runner Infrastructure Deep Dive](side-quest-24-01-runner-infrastructure.md) — enterprise infrastructure primer covering ephemeral and JIT runners, proxy configuration, and network isolation for air-gapped environments; branches from [Step 24](24-self-hosted-runners.md). | ||
| - [Project Future AI Credit Costs with `gh aw forecast`](side-quest-26-01-forecast-costs.md) — full walkthrough of `gh aw forecast`: reading P10/P50/P90 output, using `--period week` and `--days 7`, forecasting all workflows, and deriving a `max-daily-ai-credits` value from the P90 figure; branches from [Step 26](26-manage-costs-and-budgets.md). | ||
| - [Skill Injection Strategies — Hint, Fusion, and Inline](side-quest-29-01-skill-injection-strategies.md) — decision table, code examples, and a practice exercise for the hint, fusion, and inline strategies for wiring a `SKILL.md` into a workflow prompt; branches from [Step 29](29-skills-and-domain-knowledge.md). | ||
| - [Recognizing Common Agentic Workflow Failure Modes](side-quest-22-01-failure-modes.md) — worked examples of empty data, tool error, timeout, and prompt drift failures with a match-the-fix practice exercise; branches from [Step 22](22-error-handling-and-resilience.md). |
|
|
||
| | Failure type | Example | Effect | | ||
| |---|---|---| | ||
| | **Empty data** | No open issues to summarise | Agent produces a vague or empty report | |
| | **Timeout** | Complex reasoning takes too long | Workflow job is cancelled by Actions | | ||
| | **Prompt drift** | Instructions are ambiguous | Agent takes an unexpected code path | | ||
|
|
||
| Recognising these patterns helps you write instructions that stay on track — most workflow bugs are one of these four things, not something exotic. |
Comment on lines
+31
to
+51
| The diagram below shows how these failure modes map to three mitigations: a defensive brief, a `timeout-minutes` setting, and a fallback [safe-output](https://github.github.com/gh-aw/reference/safe-outputs/). | ||
|
|
||
| <picture> | ||
| <source media="(prefers-color-scheme: dark)" srcset="images/22-resilience-techniques-dark.svg"> | ||
| <source media="(prefers-color-scheme: light)" srcset="images/22-resilience-techniques-light.svg"> | ||
| <img alt="Four failure modes — prompt drift, timeout, tool error, and empty data — each mapped to one of three mitigations: defensive brief, timeout-minutes, and fallback safe-output, which together produce a reliably running workflow" src="images/22-resilience-techniques-light.svg"> | ||
| </picture> | ||
|
|
||
| ### Practice: match the failure to the mitigation | ||
|
|
||
| Before checking your answer, decide which mitigation (defensive brief, `timeout-minutes`, or fallback safe-output) best addresses each scenario: | ||
|
|
||
| 1. A run consistently takes 18 minutes to finish reasoning about a large diff, and Actions cancels it. | ||
| 2. A run finishes cleanly but never calls a safe-output tool because the repository had no activity that day. | ||
| 3. A run's summary is technically correct but ignores the instruction to flag blockers, because the brief never defined what a "blocker" is. | ||
|
|
||
| <details> | ||
| <summary>Reveal the answers</summary> | ||
|
|
||
| 1. **Timeout.** Set `timeout-minutes` to a value that gives the agent headroom, or reduce the size of the input it reasons over. | ||
| 2. **Empty data.** Add a defensive brief instruction that tells the agent to write a "no activity" report — and always call the safe output — even when nothing changed. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Caution
Protected files were modified in this change.
This pull request is in
request_reviewmode and requires explicit human scrutiny before merge.Protected files:
README.mdSource file mined:
workshop/22-error-handling-and-resilience.md("Make Your Workflows Resilient to Failure")Side quest extracted: The step's "Understand common failure modes" section — a self-contained primer covering the four common agentic workflow failure modes (empty data, tool error, timeout, prompt drift), their effects, and the resilience diagram — was hidden inside a longer resilience-techniques walkthrough. It now lives as its own optional detour:
workshop/side-quest-22-01-failure-modes.md, expanded with a match-the-fix practice exercise and a self-check prompt against the learner's own workflow runs.Routing changes for learners:
workshop/README.md's "Optional Side Quests" section now lists the new side quest, noting it branches from Step 22.The main path in Step 22 (apply the three mitigations, compile, push, verify) is unchanged and still works standalone without visiting the side quest.
Warning
Firewall blocked 1 domain
The following domain was blocked by the firewall during workflow execution:
registry.npmjs.orgTo allow these domains, add them to the
network.allowedlist in your workflow frontmatter:See Network Configuration for more information.