From 2de646e74ddf9a86a434c3fac6371dbb54043c91 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 2 Oct 2026 02:49:11 +0000 Subject: [PATCH] Trim environment reference side quest for cognitive load and activity density Merge verbose per-image captions into shorter table-aligned text, cut redundant prose in the glossary table, verify/note sections, and image alt text, and add a quick self-check question before the checkpoint. Brings the page from 1,433 words to under 900 while preserving all nine tool/environment entries and the checkpoint. Addresses curriculum-eval finding: side-quest-01-02-environment-reference.md scored 4.93/10.0 (lowest in corpus) for active_learning and cognitive_load due to excessive length relative to practice density. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../side-quest-01-02-environment-reference.md | 98 ++++++++----------- 1 file changed, 39 insertions(+), 59 deletions(-) diff --git a/workshop/side-quest-01-02-environment-reference.md b/workshop/side-quest-01-02-environment-reference.md index 52e261d5..954e1efc 100644 --- a/workshop/side-quest-01-02-environment-reference.md +++ b/workshop/side-quest-01-02-environment-reference.md @@ -2,34 +2,30 @@ # Side Quest: Environment Reference -> _Optional: use this quick glossary and visual reference to understand the environments and AI tools used throughout the workshop._ +> _Optional: a quick glossary and visual reference for the environments and AI tools used in this workshop._ -**What you'll learn:** By the end of this page you can name each tool and environment used in the workshop, match it to its role, and know when you'll use it. +**What you'll learn:** name each tool and environment, match it to its role, and know when you'll use it. ## :clipboard: Before You Start -This is a reference page — you can read it any time. Come back here whenever the workshop uses a term you want to clarify. No terminal required to read this page. - -When you're ready to verify your tools are working, see the [Checkpoint](#white_check_mark-checkpoint) section at the bottom. +Read this page any time you want to clarify a term. No terminal required — jump to the [Checkpoint](#white_check_mark-checkpoint) when ready to verify your tools. ## Environment and tool glossary -Knowing which name maps to which role helps you follow workshop instructions without stopping to wonder what "the terminal" or "Codespaces" means in context. - | Term | What it means in this workshop | When you use it | Official documentation | |------|------|------|------| -| **GitHub Codespaces** | Your cloud development environment when you choose the browser-based setup path. Pre-launched in golden-ticket workshops. | Steps 2–14: writing, compiling, and running workflows | [GitHub Codespaces docs](https://docs.github.com/en/codespaces) | -| **Visual Studio Code (VS Code)** | The editor experience inside Codespaces (and optionally on your local machine). | Editing workflow files and reading output | [Visual Studio Code docs](https://code.visualstudio.com/docs) | -| **Terminal (command line)** | The shell where you run workshop commands (`gh`, `gh aw`, `git`, and more). | Any step that shows a `bash` code block | [GitHub CLI manual](https://cli.github.com/manual/) | -| **GitHub CLI (`gh`)** | GitHub's official CLI, required for this workshop. Pre-installed in the Codespace. | Starting at Step 6 (install the extension) | [GitHub CLI docs](https://cli.github.com/manual/) | -| **`gh-aw` CLI extension** | The GitHub Agentic Workflows extension you install and use in the terminal to compile workflow files. | Step 6 onward | [Install `gh-aw`](https://github.com/github/gh-aw#readme) | -| **GitHub Copilot CLI** | Copilot in the terminal for AI-assisted command and development help. The primary AI surface in this workshop. | Any step that shows a `prompt` code block | [GitHub Copilot CLI docs](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-copilot-cli) | -| **GitHub Copilot app** | The GitHub Copilot desktop and web application where you can open repositories, start agent sessions, steer coding tasks, and manage pull requests. | Optional; side quests cover this surface | [GitHub Copilot app](https://github.com/features/ai/github-app) | -| **Claude** | Anthropic's AI model family available in some GitHub Copilot and agentic workflow contexts. | Steps that use a non-default model | [Claude documentation](https://docs.anthropic.com/) | -| **OpenAI Codex** | OpenAI coding model family that can be used in coding and agent workflows. | Steps that use a non-default model | [OpenAI Codex CLI repository](https://github.com/openai/codex#readme) | +| **GitHub Codespaces** | Your cloud dev environment for the browser-based setup path. | Steps 2–14 | [Docs](https://docs.github.com/en/codespaces) | +| **Visual Studio Code (VS Code)** | The editor inside Codespaces (or your local machine). | Editing and reading output | [Docs](https://code.visualstudio.com/docs) | +| **Terminal (command line)** | The shell running `gh`, `gh aw`, `git`, and more. | Any `bash` code block | [GitHub CLI manual](https://cli.github.com/manual/) | +| **GitHub CLI (`gh`)** | GitHub's official CLI, pre-installed in the Codespace. | Starting at Step 6 | [Docs](https://cli.github.com/manual/) | +| **`gh-aw` CLI extension** | The Agentic Workflows extension you use to compile workflow files. | Step 6 onward | [Install `gh-aw`](https://github.com/github/gh-aw#readme) | +| **GitHub Copilot CLI** | Copilot in the terminal; the primary AI surface in this workshop. | Any `prompt` code block | [Docs](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-copilot-cli) | +| **GitHub Copilot app** | Desktop/web app for repository sessions and pull requests. | Optional; side quests | [GitHub Copilot app](https://github.com/features/ai/github-app) | +| **Claude** | Anthropic's model family, available in some contexts. | Non-default-model steps | [Docs](https://docs.anthropic.com/) | +| **OpenAI Codex** | OpenAI's coding model family. | Non-default-model steps | [Codex CLI repo](https://github.com/openai/codex#readme) | > [!NOTE] -> **GitHub Enterprise (GHES/GHEC) users**: the same tools and commands apply in enterprise environments. Your Codespace URL and GitHub URLs will use your enterprise hostname instead of `github.com`. If your enterprise uses a self-hosted runner, the `gh aw compile` command still runs locally in your Codespace — see [Step 6](06-install-gh-aw.md) for any environment-specific install notes. +> **Enterprise (GHES/GHEC):** same tools and commands apply — Codespace and GitHub URLs use your enterprise hostname instead of `github.com`. See [Step 6](06-install-gh-aw.md) for runner-specific install notes. ### :white_check_mark: Verify your tools are ready @@ -40,12 +36,12 @@ gh --version git --version ``` -Both commands should print a version number. If either fails, see [Set Up a Codespace](02a-setup-codespace.md). +Both should print a version number. If either fails, see [Set Up a Codespace](02a-setup-codespace.md). > [!NOTE] -> `gh aw --version` only works after you complete [Install the gh-aw CLI Extension](06-install-gh-aw.md). Skip that check until you reach Step 6. +> `gh aw --version` only works after [Step 6](06-install-gh-aw.md). Skip it until then. -After you complete Step 6, also run: +After Step 6, also run: ```bash gh aw --version @@ -53,103 +49,87 @@ gh aw --version ## Conceptual screenshots -Recognizing what each environment looks like on screen helps you orient yourself quickly when workshop instructions say "open a terminal" or "use the Copilot app." - -These visuals are simplified mental models, not literal product screenshots. Use them to recognize what each name refers to when it appears in later steps. +Simplified mental models, not literal screenshots — use them to recognize each name later. Captions are short since the table above covers the role. ### Development environments -#### GitHub Codespaces - - Conceptual screenshot of GitHub Codespaces showing a browser-based editor, repository explorer, and integrated terminal + Conceptual screenshot of GitHub Codespaces with an editor, file explorer, and terminal -You use Codespaces when you want a ready-to-go development environment in your browser. - -#### Visual Studio Code (VS Code) +**GitHub Codespaces** — your browser-based dev environment. - Conceptual screenshot of Visual Studio Code showing the Explorer, open editor tabs, and integrated terminal + Conceptual screenshot of VS Code with the Explorer, editor tabs, and terminal -You use VS Code to browse files, edit workflows, and keep a terminal open beside your work. - -#### Terminal (command line) +**VS Code** — the editor inside Codespaces. - Conceptual screenshot of a terminal showing a prompt, commands, and command output + Conceptual screenshot of a terminal with a prompt and command output -You use the terminal whenever the workshop asks you to run `gh`, `gh aw`, or `git` commands. +**Terminal** — where you run `gh`, `gh aw`, and `git` commands. ### Workshop tools and model options -#### GitHub CLI (`gh`) - - Conceptual screenshot of GitHub CLI showing authentication, repository, and workflow commands in a terminal + Conceptual screenshot of GitHub CLI commands in a terminal -You use `gh` for GitHub-specific terminal tasks like authentication checks, repository shortcuts, and workflow commands. - -#### `gh-aw` CLI extension +**`gh`** — GitHub's CLI for auth, repo, and workflow commands. - Conceptual screenshot of the gh-aw CLI extension showing compile commands for an agentic workflow + Conceptual screenshot of gh-aw compile commands in a terminal -You use `gh aw` to compile agentic workflow files. - -#### GitHub Copilot CLI +**`gh aw`** — the extension that compiles agentic workflow files. - Conceptual screenshot of GitHub Copilot CLI showing a terminal prompt alongside AI-assisted command help + Conceptual screenshot of GitHub Copilot CLI giving AI help in a terminal -You use GitHub Copilot CLI when you want AI help inside the terminal. - -#### GitHub Copilot app +**GitHub Copilot CLI** — AI help inside the terminal. - Conceptual screenshot of the GitHub Copilot app showing a repository session, agent chat, and pull request view + Conceptual screenshot of the GitHub Copilot app with a session, chat, and pull request view -You use the GitHub Copilot app when you want to start and steer repository sessions, manage coding tasks, and review pull requests from a Copilot workspace. - -#### Claude +**GitHub Copilot app** — start sessions and review pull requests from a Copilot workspace. - Conceptual screenshot of a Claude-style workspace showing a prompt, reasoning path, and structured response + Conceptual screenshot of a Claude-style workspace with a prompt and response -You may see Claude as one of the AI model options that can read a brief, reason through a task, and produce an output. - -#### OpenAI Codex +**Claude** — an alternate AI model option for some steps. - Conceptual screenshot of an OpenAI Codex-style coding workspace showing repository files and a suggested patch + Conceptual screenshot of an OpenAI Codex-style workspace with files and a suggested patch -You may see OpenAI Codex as a coding-focused model option that reads files and suggests edits. +**OpenAI Codex** — another alternate AI model option for some steps. + +### Quick self-check + +Before moving on, cover the table above and try to answer: which tool do you use to *compile* a workflow file, and which do you use to *run* `git` commands? (Answers: `gh aw`; the terminal.) ## :white_check_mark: Checkpoint