Optimize Claude user docs review workflow with inline sub-agents for extractive phases#31416
Merged
Merged
Conversation
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Optimize Claude code user documentation review
Optimize Claude user docs review workflow with inline sub-agents for extractive phases
May 11, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Refactors the claude-code-user-docs-review workflow to offload extractive/scanning phases into inline “small” sub-agents, reducing main-prompt context and keeping synthesis in the primary agent path.
Changes:
- Enabled inline sub-agent usage in the workflow frontmatter.
- Replaced Phase 1/4/5/6 bash-based scanning instructions with sub-agent invocations.
- Added four inline sub-agent definitions (
doc-reader,engine-example-counter,tool-engine-classifier,auth-doc-extractor) and recompiled the lockfile.
Show a summary per file
| File | Description |
|---|---|
.github/workflows/claude-code-user-docs-review.md |
Adds inline sub-agents and rewires phases to use them for extractive tasks. |
.github/workflows/claude-code-user-docs-review.lock.yml |
Recompiled generated lockfile reflecting the workflow markdown changes. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (2)
.github/workflows/claude-code-user-docs-review.md:596
- This sub-agent is instructed to read
docs/src/content/docs/setup/quick-start.md, but the repo’s quick start isdocs/src/content/docs/setup/quick-start.mdx. As written, the agent will fail to read the intended file.
Read `docs/src/content/docs/setup/quick-start.md` and extract authentication details for:
- copilot
- claude
- codex
- custom
.github/workflows/claude-code-user-docs-review.md:601
- Like the other extractive agents, this one is used for factual “JSON output” in the main workflow. Consider tightening the output contract to require ONLY a single valid JSON object (no markdown fences / no additional text) to prevent downstream parsing or copy/paste errors.
Return compact JSON with:
- required_secrets_by_engine
- setup_steps_by_engine
- explicit_warnings_or_scope_notes
- auth_gaps_or_missing_instructions
- Files reviewed: 2/2 changed files
- Comments generated: 5
| - shared/observability-otlp.md | ||
| features: | ||
| copilot-requests: true | ||
| inline-agents: true |
Comment on lines
+539
to
+543
| Read these files: | ||
| - README.md | ||
| - docs/src/content/docs/setup/quick-start.md | ||
| - docs/src/content/docs/introduction/how-they-work.mdx | ||
| - docs/src/content/docs/introduction/architecture.mdx |
Comment on lines
+547
to
+553
| Return compact JSON with: | ||
| - engines_mentioned | ||
| - copilot_dependencies | ||
| - claude_or_codex_mentions | ||
| - prerequisites | ||
| - missing_setup_pieces_for_claude_users | ||
| - notable_quotes_with_file_refs |
Comment on lines
+560
to
+565
| Scan `.github/workflows/*.md` and count occurrences of: | ||
| - `engine: claude` | ||
| - `engine: copilot` | ||
| - `engine: codex` | ||
| - `engine: custom` | ||
|
|
| - codex-only | ||
| - unclear | ||
|
|
||
| Return a compact markdown table and JSON summary with counts by class and any ambiguous entries. |
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.
✨ Enhancement
The
claude-code-user-docs-reviewworkflow is a high-token claude run with multiple extractive phases that were executed in the main prompt context. This change extracts those mechanical phases into inlinesmallsub-agents while keeping synthesis/reporting in the main agent path.What does this improve?
Why is this valuable?
Implementation approach:
.github/workflows/claude-code-user-docs-review.md:doc-readerengine-example-countertool-engine-classifierauth-doc-extractor## agent:blocks at the end of the workflow withmodel: smalland constrained structured outputs:doc-reader: summarizes six core docs into compact factual JSONengine-example-counter: counts/listings byengine:*across workflow markdownstool-engine-classifier: tool compatibility classification table + summaryauth-doc-extractor: per-engine auth/secret extraction from quick-start docs.github/workflows/claude-code-user-docs-review.lock.yml.Example invocation change: