Context
The CLI Consistency Checker keeps surfacing real drifts between the gh aw binary and docs/src/content/docs/setup/cli.md, but these issues are repeatedly closed without merging the corresponding fix:
| Issue |
Closed by |
State |
Notes |
| #39576 (2026-06-16) |
@pelikhan |
not_planned |
4 medium + 7 low drifts, no resolution comment |
| #39401 (2026-06-15) |
github-actions[bot] |
not_planned |
Copilot assignment errored, auto-expired |
| #38846 (2026-06-12) |
@pelikhan |
completed |
Forecast terminology fix landed separately |
| #38386 (2026-06-10) |
github-actions[bot] |
not_planned |
Cookie-only auto-expired |
Rejection signal
The prior Daily Documentation Healer run produced PR-intent #38981 (2026-06-13) targeting the forecast-terminology drift from #38386. @pelikhan closed it without merging. Per the doc-healer spec this is a strong rejection signal for the docs-only fix direction on this class of issue, and the healer must not re-attempt the same fix.
Meanwhile, the drifts called out in #39576 still exist today:
- M1 —
gh aw outcomes history subcommand (pkg/cli/outcomes_history.go:87) is fully implemented but absent from docs/src/content/docs/setup/cli.md line 538–549.
- M2/M3 —
forecast --days and health --days advertise (allowed values: 7, 30) / (7, 30, or 90) in --help but the docs lists --days with no constraint.
- M4 —
new, compile, run, enable, disable, remove, version render Examples: before Usage: because the examples live in cobra Long rather than the Example field — a code-side fix, not a docs fix.
- L1–L7 — minor wording/flag-listing mismatches.
Inverse direction proposed
Rather than retry docs-side patches, ask the maintainer to choose ONE policy:
- Code-side normalisation — fix M4 in
cmd/gh-aw/main.go (move Examples: into the cobra Example field for the seven affected commands) so --help output matches the convention every other command uses. Same idea for L3/L4/L5 (CLI string drift within itself).
- Docs-side acceptance with maintainer sign-off — explicitly allow the healer to land M1/M2/M3 (subcommand + allowed-values additions) as standalone PRs without waiting for a triggering code change. Today DDUw Step 1c blocks this path because the issue was closed
not_planned and no commit touched the affected commands in the 7-day window.
- Suppress the checker — if these drifts are intentional, retire the CLI Consistency Checker workflow or move it off the
documentation label so it stops generating issues the team will not act on.
Suggested DDUw improvement
Extend Step 1c (closed as not_planned) with explicit handling for documentation+cookie+cli issues that have a prior closed-unmerged healer PR in the same family: skip the docs-fix path, emit a [doc-healer] decision issue (this template), and do not retry until the maintainer responds. The current Step 1c rule routes through the cross-reference path, which produces the same rejected docs-only attempt every run.
Ask
@pelikhan — which of (1), (2), or (3) should the healer adopt going forward?
Generated by 📝 Daily Documentation Healer · ◷
Context
The CLI Consistency Checker keeps surfacing real drifts between the
gh awbinary anddocs/src/content/docs/setup/cli.md, but these issues are repeatedly closed without merging the corresponding fix:@pelikhannot_plannednot_planned@pelikhancompletednot_plannedRejection signal
The prior Daily Documentation Healer run produced PR-intent #38981 (2026-06-13) targeting the forecast-terminology drift from #38386.
@pelikhanclosed it without merging. Per the doc-healer spec this is a strong rejection signal for the docs-only fix direction on this class of issue, and the healer must not re-attempt the same fix.Meanwhile, the drifts called out in #39576 still exist today:
gh aw outcomes historysubcommand (pkg/cli/outcomes_history.go:87) is fully implemented but absent fromdocs/src/content/docs/setup/cli.mdline 538–549.forecast --daysandhealth --daysadvertise(allowed values: 7, 30)/(7, 30, or 90)in--helpbut the docs lists--dayswith no constraint.new,compile,run,enable,disable,remove,versionrenderExamples:beforeUsage:because the examples live in cobraLongrather than theExamplefield — a code-side fix, not a docs fix.Inverse direction proposed
Rather than retry docs-side patches, ask the maintainer to choose ONE policy:
cmd/gh-aw/main.go(moveExamples:into the cobraExamplefield for the seven affected commands) so--helpoutput matches the convention every other command uses. Same idea for L3/L4/L5 (CLI string drift within itself).not_plannedand no commit touched the affected commands in the 7-day window.documentationlabel so it stops generating issues the team will not act on.Suggested DDUw improvement
Extend Step 1c (
closed as not_planned) with explicit handling fordocumentation+cookie+cliissues that have a prior closed-unmerged healer PR in the same family: skip the docs-fix path, emit a[doc-healer]decision issue (this template), and do not retry until the maintainer responds. The current Step 1c rule routes through the cross-reference path, which produces the same rejected docs-only attempt every run.Ask
@pelikhan— which of (1), (2), or (3) should the healer adopt going forward?