[docs] Self-healing documentation fixes from issue analysis - 2026-06-16#39472
Conversation
|
✅ 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. PR #39472 is a pure documentation fix to docs/src/content/docs/setup/cli.md (2 additions, 2 deletions). 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 #39472 does not have the implementation label and has 0 new lines of code in business logic directories (threshold 100). Changes are limited to skill scripts and a shared MCP server file outside default business logic directories. |
There was a problem hiding this comment.
⚠️ Not ready to approve
The updated doc strings still don’t exactly match the corresponding CLI help lines they’re intended to align with, so the documented drifts may remain unresolved.
Pull request overview
This PR updates gh aw CLI documentation to reduce wording drift between docs and the CLI’s built-in help text, focusing on the init --codespaces example annotation and the forecast command description.
Changes:
- Adjusted the
init --codespaces repo1,repo2example comment wording. - Updated the
forecastcommand description terminology from “token usage” to “AI Credit (AIC)”.
File summaries
| File | Description |
|---|---|
| docs/src/content/docs/setup/cli.md | Aligns specific CLI doc strings/examples with current CLI help terminology. |
Copilot's findings
- Files reviewed: 1/1 changed files
- Comments generated: 2
Note
Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| gh aw init --no-agent # Skip custom agent creation | ||
| gh aw init --codespaces "" # Configure Codespaces for current repo only | ||
| gh aw init --codespaces repo1,repo2 # Configure devcontainer for additional repos | ||
| gh aw init --codespaces repo1,repo2 # Configure Codespaces with additional repos |
| #### `forecast` `[EXPERIMENTAL]` | ||
|
|
||
| Forecast token usage and costs for agentic workflows using recent run history and Monte Carlo simulation. | ||
| Forecast AI Credit (AIC) usage and costs for agentic workflows using recent run history and Monte Carlo simulation. |
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs — both terminology fixes are accurate and well-sourced against the CLI implementation files.
📋 Key Themes & Highlights
Verification
pkg/cli/init_command.go:72confirms:# Codespaces with additional repos— doc now aligned ✅pkg/cli/forecast_command.go:38–39confirms:AI Credit (AIC) usage— doc now aligned ✅- The
Configureprefix added to the--codespacescomment is consistent with the adjacent example comment (# Configure Codespaces for current repo only) and reads naturally in doc context.
Positive Highlights
- ✅ PR description clearly cites exact source file + line numbers for both fixes
- ✅ Scope is tightly limited — only the two drifted phrases are touched
- ✅ The DDUw improvement suggestions in the PR body are actionable and well-reasoned
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 129.8 AIC · ⌖ 13.7 AIC · ⊞ 29.4K
There was a problem hiding this comment.
Documentation alignment — two residual drifts remain
Both changed lines are improvements over the previous state, but neither fully matches the CLI source wording. Both issues have already been called out by the existing inline review; this confirms those findings.
Findings summary
Line 144 — init --codespaces example comment
The PR removed the confusing "devcontainer" wording, but kept a "Configure" prefix that the CLI source does not have. Source (init_command.go:72) reads # Codespaces with additional repos; the doc now reads # Configure Codespaces with additional repos.
Line 584 — forecast description
The PR correctly replaces "token usage" with "AI Credit (AIC)", but the resulting phrase blends the CLI Short help (which has and costs but no (AIC)) with the Long help (which has (AIC) but no and costs). The Long description is the canonical prose reference here, so dropping and costs — or aligning to the Short string verbatim — would fully close the drift.
No new issues beyond what is already flagged. No blockers found.
🔎 Code quality review by PR Code Quality Reviewer · 100.8 AIC · ⌖ 13.1 AIC · ⊞ 17.3K
Summary
Documentation-only fix aligning two CLI reference descriptions in
docs/src/content/docs/setup/cli.mdwith the CLI source-of-truth:--codespacesflag – corrected description wording from "devcontainer" → "Codespaces".forecastcommand – updated description to use "AI Credit (AIC) usage" instead of the stale "token usage" phrasing.Changes
docs/src/content/docs/setup/cli.mdDetails
Both edits are purely cosmetic documentation corrections — no code, schema, or generated files were touched. The changes close a terminology drift between the rendered CLI reference docs and the actual flag/command descriptions emitted by the CLI binary.
--codespaces: The flag configures Codespaces-specific behaviour; calling it "devcontainer" was misleading.forecast: The CLI now reports consumption in AI Credits (AIC), not raw tokens; the old wording was factually incorrect.Testing
No functional code changed. Doc correctness can be verified by:
grep -n "Codespaces\|AIC\|AI Credit\|forecast\|devcontainer\|token usage" \ docs/src/content/docs/setup/cli.mdChecklist