[doc-healer] DDUw improvement: detect and respect docs-PR rejection signals before re-attempting same fix

[github-actions]

Self-Healing Documentation Healer Report — 2026-06-21

This issue is filed by the Daily Documentation Healer (DDUh) after analyzing closed documentation issues from the last 7 days. Two confirmed documentation gaps were detected, but both trip the workflow's explicit rejection-signal rule: a prior docs-only fix PR was closed unmerged by a repository collaborator (@pelikhan). Per the workflow instructions, DDUh must NOT re-attempt the same docs fix and instead surfaces this issue for an explicit next-step decision.

---

Confirmed gap #1 — gh secret set ... < /path/to/token.txt in Quick Start

Source issue: #40096 (closed 2026-06-18 by @pelikhan)

Drift still present: docs/src/content/docs/setup/quick-start.mdx lines 81 and 87 still contain:

gh secret set COPILOT_GITHUB_TOKEN < /path/to/token.txt
gh secret set ANTHROPIC_API_KEY  < /path/to/key.txt

Rejected fix: PR #40171 (auto-merged DDUw [docs] PR, healer-created) was closed unmerged by @pelikhan on 2026-06-19 without comment. It proposed switching to the echo "..." | gh secret set ... form.

Inverse fix direction (code change instead of docs change):

• Add a new gh aw secrets set <NAME> --value <value> helper subcommand (one already exists per the auth.mdx reference) and update the Quick Start to invoke it, so the user never has to know about file redirects or here-docs.
• Or, document only the GitHub UI flow in the [!NOTE] block (since the file-redirect form is the friction point), and move CLI-only forms to the Authentication reference page.

Confirmed gap #2 — CLAUDE_CODE_OAUTH_TOKEN unsupported is invisible in Quick Start

Source issue: #39601 (auto-closed 2026-06-18 by expiry)

Drift still present: docs/src/content/docs/setup/quick-start.mdx does not mention CLAUDE_CODE_OAUTH_TOKEN or surface the --engine claude flag for gh aw init. The caveat lives only in docs/src/content/docs/reference/auth.mdx:199 and docs/src/content/docs/reference/faq.md:368.

Rejected fix: Copilot PR #39638 ("docs: clarify Claude quick-start auth + initialization path") was closed unmerged by @pelikhan on 2026-06-16 without comment. It proposed adding a [!NOTE] to Quick Start surfacing both facts.

Inverse fix direction (code change instead of docs change):

• Detect CLAUDE_CODE_OAUTH_TOKEN at gh aw run/compile time and emit a clear [error] CLAUDE_CODE_OAUTH_TOKEN is not supported — set ANTHROPIC_API_KEY instead message. The runtime knows when this token is set as a repo secret (it shows up in the env), so the friction moves to the failure path where the user is already debugging.
• Or, change gh aw add-wizard to surface engine choice prominently so the Claude path is obvious without quick-start changes.

@pelikhan — please pick a direction for each gap (or close this issue if you'd rather leave the drift as-is). Both prior docs-only PRs were silently closed, so DDUh is escalating instead of re-creating a third one.

---

💡 DDUw improvement suggestions

Root cause

DDUw's Step 1c (recently closed documentation issues) handles three branches well:

1. issue has a merged docs PR → skip
2. issue has a fallback heuristic match → skip
3. issue's referenced gaps are already in the files → skip

But it has no branch for the rejection-signal case: when a docs-only fix PR exists, is closed unmerged by a collaborator, and the drift is still in the file. DDUw silently re-attempts the same fix on the next run, which is exactly how #40171 (the healer's own previous PR) landed unmerged. The same fix should not be tried a third time.

Proposed addition to .github/workflows/daily-doc-updater.md

Add a new bullet under Step 1c branch list, just before the "fallback heuristic" branch:

  - **Closed-unmerged docs PR by a collaborator (rejection signal)**: If a `[docs]` PR (label `documentation`, label `automation`, or known DDUw/healer bot author) referencing this issue exists in state `closed`, `merged: false`, and `closed_by` is a member of `list_repository_collaborators`, treat this issue as **deliberately not addressed by docs change**. Do NOT include it in this run's PR. Surface it in the **Skipped Issues** section with the closed PR's number and the closer's login, and stop processing the issue.

This would have:

• prevented [docs] Self-healing documentation fixes from issue analysis - 2026-06-19 #40171 from being created in the first place (a previous healer would have noticed PR docs: clarify Claude quick-start auth + initialization path #39638 was closed by pelikhan, and not opened the same fix as [docs] Self-healing documentation fixes from issue analysis - 2026-06-19 #40171),
• prevented today's DDUh from re-creating the [deep-report] Docs: replace beginner-hostile < /path/to/token.txt with an echo-pipe in Quick Start #40096 / [deep-report] Quick-start docs: note CLAUDE_CODE_OAUTH_TOKEN unsupported + surface gh aw init --engine claude #39601 fixes after the healer's own PR was closed.

Secondary improvement

For pre-flight Step 3 (recently closed documentation issues), instruct DDUw to capture each issue's closed_by user and check for a closed-unmerged PR referencing the issue, so the rejection signal is computed once during the batch fetch rather than re-derived per issue.

---

References:

• DDUh run §27887859209
• Source issues: [deep-report] Docs: replace beginner-hostile < /path/to/token.txt with an echo-pipe in Quick Start #40096, [deep-report] Quick-start docs: note CLAUDE_CODE_OAUTH_TOKEN unsupported + surface gh aw init --engine claude #39601
• Rejected fix PRs: [docs] Self-healing documentation fixes from issue analysis - 2026-06-19 #40171, docs: clarify Claude quick-start auth + initialization path #39638

Generated by 📝 Daily Documentation Healer · 430 AIC · ⊞ 6.7K · ◷

• expires on Jun 23, 2026, 4:15 PM UTC-08:00

[copilot-swe-agent]

The agent encountered an error and was unable to start working on this issue: Please try again later, or contact support if the problem persists. (Request id: 11A0:2E7CD7:A399DA:25B65AD:6A372D3C)