[docs] Self-healing documentation fixes from issue analysis - 2026-06-27#41816
Conversation
…series gloss Closes #40806
github-actions
Bot
added
automation
documentation
|
✅ PR Code Quality Reviewer completed the code quality review. |
|
✅ Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. The only change is a documentation fix to docs/src/content/docs/setup/quick-start.mdx (+1/-1). Test Quality Sentinel skipped. |
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR does not have the 'implementation' label and has ≤100 new lines of code in business logic directories. |
There was a problem hiding this comment.
Pull request overview
Documentation-only update intended to address issue #40806 by making the “Peli’s Agent Factory” reference in the Quick Start more descriptive for newcomers.
Changes:
- Replaced the “Peli’s Agent Factory” link text in Quick Start with a descriptive label and short explanation of what the link contains.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/setup/quick-start.mdx | Updates the “What’s next?” section to use a clearer, more descriptive label for the Agent Factory link. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Low
| ## What's next? | ||
|
|
||
| There are hundreds of other ways to use GitHub Agentic Workflows! Explore some of these in [Peli's Agent Factory](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/). | ||
| There are hundreds of other ways to use GitHub Agentic Workflows! Explore the [Agent Factory blog series](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/) — a 19-part tour of real-world agentic workflows authored by the gh-aw maintainers — for examples covering issue triage, releases, quality checks, and more. |
![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 — the core fix is a solid UX improvement; two small accuracy/consistency issues worth addressing.
📋 Key Themes & Highlights
Key Themes
- Attribution accuracy: "authored by the gh-aw maintainers" doesn't match the blog series' own credits (GitHub Next, Microsoft Research and collaborators). A factually correct attribution avoids confusion for readers who click through.
- Terminology consistency:
faq.mdstill uses "Peli's Agent Factory" — if the goal is to phase out the personal-branded name, the FAQ reference should follow suit.
Positive Highlights
- ✅ The change correctly identifies and addresses the UX problem (opaque personal reference in a high-traffic onboarding page)
- ✅ The replacement text "Agent Factory blog series" is cleaner, more discoverable, and better calibrated for a newcomer
- ✅ The PR description is thorough and provides clear reasoning, root-cause analysis, and DDUw improvement notes
- ✅ Skipped issues are documented with clear rationale — good hygiene for an automated workflow
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 52.6 AIC · ⌖ 7.56 AIC · ⊞ 6.6K
| ## What's next? | ||
|
|
||
| There are hundreds of other ways to use GitHub Agentic Workflows! Explore some of these in [Peli's Agent Factory](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/). | ||
| There are hundreds of other ways to use GitHub Agentic Workflows! Explore the [Agent Factory blog series](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/) — a 19-part tour of real-world agentic workflows authored by the gh-aw maintainers — for examples covering issue triage, releases, quality checks, and more. |
There was a problem hiding this comment.
[/grill-with-docs] The attribution "authored by the gh-aw maintainers" conflicts with the blog series' own credits — the welcome post attributes the work to "GitHub Next, Microsoft Research and collaborators, including Peli de Halleux, Don Syme, Mara Kiefer, Edward Aftandilian, Russell Horton, Jiaxiao Zhou." Framing it as "gh-aw maintainers" misrepresents the provenance.
💡 Suggested fix
Replace:
authored by the gh-aw maintainers
With:
by GitHub Next and collaborators
This matches the language in the welcome post itself (2026-01-12-welcome-to-pelis-agent-factory.md) and avoids narrowing the credit to just one team.
@copilot please address this.
| ## What's next? | ||
|
|
||
| There are hundreds of other ways to use GitHub Agentic Workflows! Explore some of these in [Peli's Agent Factory](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/). | ||
| There are hundreds of other ways to use GitHub Agentic Workflows! Explore the [Agent Factory blog series](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/) — a 19-part tour of real-world agentic workflows authored by the gh-aw maintainers — for examples covering issue triage, releases, quality checks, and more. |
There was a problem hiding this comment.
[/grill-with-docs] The FAQ still refers to the series by its original name — docs/src/content/docs/reference/faq.md line 504 uses [Peli's Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/). A reader clicking through from Quick Start will land on a page titled "Welcome to Peli's Agent Factory!", creating a mismatch with the new "Agent Factory blog series" label.
💡 Suggested fix
For full consistency, update faq.md line 504:
# Before
See [Peli's Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/).
# After
See [Agent Factory blog series](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/).Alternatively, leave the FAQ as-is and accept that both names co-exist — but the PR description's stated goal is to remove the personal-branded reference, which would benefit from being applied consistently.
@copilot please address this.
There was a problem hiding this comment.
Non-blocking observation — docs copy improvement is welcome
This is a net positive: removing the personal-branded link text and adding descriptive context is the right call. One non-blocking concern noted inline.
📋 Review summary
Changed: docs/src/content/docs/setup/quick-start.mdx — 1 line
What it does: Replaces opaque Peli's Agent Factory link text with a descriptive gloss explaining what the linked series contains.
Concern (non-blocking): The new copy hardcodes 19-part — a count that will silently drift as the series is updated. Suggest replacing with multi-part or similar.
No blocking issues found. The URL is unchanged, attribution to gh-aw maintainers is plausible given the blog is on the official github.github.com/gh-aw/blog domain.
🔎 Code quality review by PR Code Quality Reviewer · 65.8 AIC · ⌖ 10.4 AIC · ⊞ 5.2K
| ## What's next? | ||
|
|
||
| There are hundreds of other ways to use GitHub Agentic Workflows! Explore some of these in [Peli's Agent Factory](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/). | ||
| There are hundreds of other ways to use GitHub Agentic Workflows! Explore the [Agent Factory blog series](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/) — a 19-part tour of real-world agentic workflows authored by the gh-aw maintainers — for examples covering issue triage, releases, quality checks, and more. |
There was a problem hiding this comment.
Hardcoded series count will go stale: 19-part is a fixed factual claim that will silently become incorrect as the blog series grows.
💡 Suggested fix
Drop the count or phrase it as approximate:
Explore the [Agent Factory blog series](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/) — a multi-part tour of real-world agentic workflows authored by the gh-aw maintainers — for examples covering issue triage, releases, quality checks, and more.A blog series that grows beyond 19 (or is restructured) will make this sentence quietly wrong with no build-time signal.
| ## What's next? | ||
|
|
||
| There are hundreds of other ways to use GitHub Agentic Workflows! Explore some of these in [Peli's Agent Factory](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/). | ||
| There are hundreds of other ways to use GitHub Agentic Workflows! Explore the [Agent Factory blog series](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/) — a 19-part tour of real-world agentic workflows authored by the gh-aw maintainers — for examples covering issue triage, releases, quality checks, and more. |
There was a problem hiding this comment.
Link text mismatches the actual page title: the linked blog post is titled "Welcome to Peli's Agent Factory" — readers who click "Agent Factory blog series" will land on a page with a noticeably different name, eroding trust and causing confusion.
💡 Details
The target URL resolves to a page whose <title> and H1 are Welcome to Peli's Agent Factory. The new link text Agent Factory blog series diverges from that canonical title. A reader who clicks the link expecting a series index will instead land on a single introductory article whose title doesn't match what they clicked.
Additionally, the series actually contains 20 posts (1 welcome + 19 "meet the workflows" entries), so the 19-part count is already incorrect — not merely a future-staleness risk.
A closer and more accurate rephrasing:
Explore [Peli's Agent Factory](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/) — a blog series walking through real-world agentic workflows covering issue triage, releases, quality checks, and more.This preserves the canonical series name while still adding the descriptive context that Issue #40806 asked for.
Summary
Updates the "What's next?" section of the quick-start guide to replace a personal-brand link with a descriptive reference to the blog series.
Changes
docs/src/content/docs/setup/quick-start.mdxPeli's Agent Factory(personal brand) toAgent Factory blog series(descriptive label).https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/).Impact