[docs] Self-healing documentation fixes from issue analysis - 2026-06-23#40906
Conversation
github-actions
Bot
added
automation
documentation
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR #40906 does not have the 'implementation' label (has_implementation_label=false) and has 0 new lines of code in business logic directories (well below the 100-line threshold). Only 1 file changed. |
|
✅ Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. PR #40906 only modifies docs/src/content/docs/setup/quick-start.mdx (documentation fix). Test Quality Sentinel skipped. |
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
✅ PR Code Quality Reviewer completed the code quality review. |
There was a problem hiding this comment.
Pull request overview
This PR updates the Quick Start guide to remove two common onboarding “speed bumps”: clarifying what the generated .lock.yml file is, and giving newcomers a simple recommendation for which AI engine to start with.
Changes:
- Adds a one-line “start with Copilot if you already have it” recommendation in Prerequisites.
- Adds an inline explanation that
.lock.ymlis the compiled GitHub Actions workflow produced from the markdown workflow.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/setup/quick-start.mdx | Updates Quick Start prerequisites and Step 2 explanation to reduce confusion about engine choice and .lock.yml purpose. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 2
| Before installing, ensure you have: | ||
|
|
||
| - **AI Account** - [GitHub Copilot](https://github.com/features/copilot), [Anthropic Claude](https://www.anthropic.com/), [OpenAI Codex](https://openai.com/api/), or [Google Gemini](https://ai.google.dev/gemini-api) | ||
| - **AI Account** - [GitHub Copilot](https://github.com/features/copilot), [Anthropic Claude](https://www.anthropic.com/), [OpenAI Codex](https://openai.com/api/), or [Google Gemini](https://ai.google.dev/gemini-api). If you already have GitHub Copilot, start there — it requires no extra account setup. |
| 5. **Optionally trigger an initial run** - Starts the workflow immediately. | ||
|
|
||
| The wizard generates a compiled workflow file (`.lock.yml`) automatically — you don't need to edit it. See [Lock File](/gh-aw/reference/workflow-structure/#lock-file-header) for the full explanation. | ||
| The `.lock.yml` is the compiled GitHub Actions workflow generated from your markdown — it is what actually runs, and it is regenerated automatically, so you never edit it by hand. See [Lock File](/gh-aw/reference/workflow-structure/#lock-file-header) for the full explanation. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs — approving, no blocking issues found.
📋 Key Themes & Highlights
Positive Highlights
- ✅ The
.lock.ymlrewrite clearly communicates what the file is, why it exists, and what not to do — a significant improvement over the old passive wording. - ✅ The engine recommendation lands at exactly the right moment (in prerequisites) to reduce decision fatigue before users start the wizard — matches project vocabulary (
engine,GitHub Copilot). - ✅ PR description explains the root cause (bot-expiry vs. maintainer close) and references source issues (#40337, #40339).
/grill-with-docs Checklist
| Signal | Status |
|---|---|
| New concepts use existing project vocabulary | ✅ (compiled, .lock.yml, engine) |
| Change clearly explained in PR description | ✅ |
| No CONTEXT.md or ADR update needed | ✅ (prose-only, no architecture change) |
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 39 AIC · ⌖ 7.39 AIC · ⊞ 6.5K
There was a problem hiding this comment.
Review: Documentation-only, one accuracy concern
Changes are narrowly scoped to the Quick Start guide — no code touched. The engine recommendation (line 29) is accurate and the "start with Copilot" hint is the right default for existing GitHub users.
The .lock.yml rewrite (line 75) is more informative overall, but "regenerated automatically" is inaccurate: the file is regenerated when the user explicitly runs gh aw compile (or the wizard), not on its own. A user who edits their markdown workflow and pushes without recompiling will silently run a stale .lock.yml in CI.
💡 Suggested follow-up wording for line 75
Replace:
it is regenerated automatically, so you never edit it by hand
With:
it is regenerated by running
gh aw compile(or the add-wizard), so you never edit it by hand
The existing inline comment from copilot-pull-request-reviewer at line 75 already flagged this; a follow-up PR to tighten the wording is recommended.
🔎 Code quality review by PR Code Quality Reviewer · 34.2 AIC · ⌖ 6.79 AIC · ⊞ 5.1K
[docs] Self-healing Quick Start fixes: explain
.lock.ymlinline, add engine pick hintSummary
Documentation-only update to
docs/src/content/docs/setup/quick-start.mdx. Two targeted clarity improvements:.lock.ymldescription — rewrote the inline explanation to make it clear that.lock.ymlis the compiled GitHub Actions workflow produced bygh aw, runs automatically, and must never be edited by hand.Changes
docs/src/content/docs/setup/quick-start.mdx.lock.ymlinline descriptionImpact
Testing
No automated tests required. Verify by reading the updated Quick Start page and confirming:
.lock.ymldescription states it is auto-generated and should not be hand-edited.