diff --git a/workshop/09-agentic-editing.md b/workshop/09-agentic-editing.md index 855b2b88..a81d3f4f 100644 --- a/workshop/09-agentic-editing.md +++ b/workshop/09-agentic-editing.md @@ -174,5 +174,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 -**Next:** [What's Next? Keep Exploring](14-next-steps.md) +**Next:** [Preview Safe Outputs Before They Run: Staged Mode](09b-preview-with-staged-mode.md) diff --git a/workshop/09b-preview-with-staged-mode.md b/workshop/09b-preview-with-staged-mode.md new file mode 100644 index 00000000..27117d77 --- /dev/null +++ b/workshop/09b-preview-with-staged-mode.md @@ -0,0 +1,126 @@ + + +# Preview Safe Outputs Before They Run: Staged Mode + +> _Every prompt tweak you tested in the last step created a real issue. Staged mode lets you see what a change would do before it actually happens._ + +## :dart: What You'll Do + +You'll enable [staged mode](https://github.github.com/gh-aw/reference/staged-mode/) on your `daily-report-status` workflow so its [`create-issue`](https://github.github.com/gh-aw/reference/safe-outputs/#issue-creation-create-issue) [safe output](https://github.github.com/gh-aw/reference/safe-outputs/) becomes a preview instead of a real write. By the end, you can iterate on your prompt as many times as you want, reading each preview in the Actions run summary, without cluttering your repository with test issues. + +## :clipboard: Before You Start + +- You completed [Refine, Test, and Improve Your Workflow](09-agentic-editing.md). +- Your `daily-report-status` workflow has a `safe-outputs:` block with `create-issue:`. +- You know how to trigger a run with **workflow_dispatch** from the **Actions** tab. + +## Steps + +### Understand the problem staged mode solves + +Every time you changed the workflow brief in the previous step and triggered a run, the agent created a real issue if the run succeeded. That's fine once you're confident in the prompt, but during rapid iteration it means cleaning up test issues after every experiment — or worse, losing track of which issue came from which prompt version. + +Staged mode skips every real write and replaces it with a detailed preview in the Actions step summary instead. The agent still runs fully — it reads data, reasons, and decides what to write — but nothing actually happens in your repository until you turn staged mode off. + +### Enable staged mode for your workflow + +In your Codespace terminal, run `gh copilot` and send: + +```prompt +/agentic-workflows update .github/workflows/daily-report-status.md to add +`staged: true` at the top of the `safe-outputs:` block so all outputs preview +instead of writing for real. +``` + +The skill adds the setting and recompiles. Review the diff before committing. + +
+:pencil2: Manual edit path + +Open `.github/workflows/daily-report-status.md` and add `staged: true` as the first line inside `safe-outputs:`: + +```markdown .github/workflows/daily-report-status.md +safe-outputs: + staged: true + create-issue: # the only write action the agent may perform +``` + +Run `gh aw compile`, then commit and push both files. + +
+ +:thinking: Pause and predict: With `staged: true` set globally, does the agent still call any tools to gather data, or does it stop before doing any work? + +### Trigger a run and read the preview + +Commit and push, then trigger a manual run from the **Actions** tab: + +```bash +git add . +git commit -m "test: enable staged mode for daily-report-status" +git push +``` + +Open the completed run and scroll to the step summary. Look for a heading marked with the 🎭 emoji — for example, **🎭 Staged Mode: Issue Creation Preview**. It shows the exact title, body, and labels the agent would have written, along with a summary line confirming no GitHub resources were created. + +:pencil2: Try it: Make one more prompt change (as you did in the previous step) and re-run. Compare the two previews side by side — you should see the difference in output without any new issues appearing in your **Issues** tab. + +### Scope staged mode to one output type + +If your workflow has more than one safe output and you only want to preview one of them, move `staged: true` under that specific output instead of the top-level setting: + +```markdown .github/workflows/daily-report-status.md +safe-outputs: + staged: false # default: everything else executes normally + create-issue: + staged: true # only issue creation previews +``` + +A type-level `staged` setting overrides the global one, so you can pilot a new or risky output type while trusted ones keep writing for real. + +### Turn staged mode off when you're ready + +Once your prompt produces the output you want in the preview, remove `staged: true` (or set it to `false`) and recompile: + +```prompt +/agentic-workflows update .github/workflows/daily-report-status.md to remove +`staged: true` from the safe-outputs block so the workflow writes for real again. +``` + +Trigger one final run and confirm a real issue appears in your **Issues** tab. + +## :white_check_mark: Checkpoint + +- [ ] Your workflow's `safe-outputs:` block includes `staged: true` +- [ ] A triggered run completed and showed a 🎭 preview in the Actions step summary instead of a real write +- [ ] You compared previews across two different prompt versions without creating extra issues +- [ ] You can explain the difference between a global `staged: true` and a type-scoped one +- [ ] You removed staged mode and confirmed a real issue was created on the final run +- [ ] `gh aw compile` succeeded and both workflow files are committed and pushed + + +**Next:** [What's Next? Keep Exploring](14-next-steps.md) + + + diff --git a/workshop/README.md b/workshop/README.md index 0d14b9a6..13f20132 100644 --- a/workshop/README.md +++ b/workshop/README.md @@ -19,6 +19,7 @@ A hands-on workshop that takes you from zero to a fully automated, AI-powered wo | 8 | [Run and Watch Your Workflow](08-run-your-workflow.md) | | 8b | [Interpret Your First Run](08b-interpret-your-run.md) | | 9 | [Refine, Test, and Improve Your Workflow](09-agentic-editing.md) | +| 9b | [Preview Safe Outputs Before They Run: Staged Mode](09b-preview-with-staged-mode.md) | | 14 | [What's Next? Keep Exploring](14-next-steps.md) | | 14b | [Build Your First Event-Driven Workflow: PR Auto-Reviewer](14b-pr-reviewer-workflow.md) |