[doc-healer] DDUw / doc-healer improvement: skip re-attempting fixes from closed-unmerged prior [docs] PRs

[github-actions]

Summary

The Daily Documentation Healer's Step 1 currently treats an issue as "addressed" only when a [docs] PR was merged. It does not learn from prior [docs] PRs that the maintainer closed without merging. This causes the healer to re-attempt the same rejected fix on subsequent runs — wasted bot effort and churn for the maintainer who has to keep closing duplicate PRs.

Observed Case

On 2026-05-19 the healer filed PR #33172 to address the engine.bare half of issue #33081. The PR changed docs/src/content/docs/reference/engines.md:

• Engine Feature Comparison: changed ✅ → ❌ for Codex / Gemini on the engine.bare row
• Bare Mode effects table: removed Codex / Gemini rows

The PR was closed unmerged by @pelikhan ~20 minutes after creation, with no review comments. The underlying docs/code drift is still observable today (verified on 2026-05-22 at HEAD):

• pkg/workflow/copilot_engine.go:46 and pkg/workflow/claude_engine.go:34 declare BareMode: true
• pkg/workflow/codex_engine.go and pkg/workflow/gemini_engine.go do not declare BareMode
• pkg/workflow/engine_config_test.go TestSupportsBareMode asserts Codex and Gemini return BareMode: false
• pkg/workflow/agent_validation.go:229 emits "Bare mode is only supported for the 'copilot' and 'claude' engines"
• docs/src/content/docs/reference/engines.md:43 still shows ✅ for Codex and Gemini
• docs/src/content/docs/reference/engines.md:329-334 still describes --no-system-prompt and GEMINI_SYSTEM_MD=/dev/null injections that the compiler never performs

Why This Matters

Without a "previously rejected" check, the healer will re-file PR #33172 every day until either (a) the maintainer adds bare-mode support to Codex/Gemini in code (matching the docs), or (b) the maintainer accepts a docs change. The maintainer's silent closure is a deliberate signal that the docs-only fix direction is not wanted; the workflow should respect it and switch tactics.

Proposed Change

Add a sub-step to .github/workflows/daily-doc-healer.md Step 1, after the merged-PR check:

Additionally, search for [docs] PRs (label documentation automation, author github-actions[bot]) that reference the same issue body or file path and were closed without merging within the last 30 days. A closed-unmerged healer PR is a strong signal that the maintainer rejected the proposed fix direction. Do not re-attempt the same fix; instead, file a [doc-healer] improvement issue that:

1. Names the rejected PR and the unresolved drift.
2. Proposes the inverse fix direction (e.g., a code change rather than a docs change).
3. Tags the maintainer for a deliberate next-step decision.

Concrete query the workflow can run after identifying a not_planned issue with a real drift:

gh api "search/issues?q=repo:${{ github.repository }}+is:pr+is:closed+is:unmerged+label:documentation+label:automation+<DRIFT_KEYWORD>&per_page=20"

💡 Why filed as an issue, not a PR this run

This healer run identified the same engine.bare drift PR #33172 attempted to fix. Re-filing the same edit today would create the exact churn this issue describes. Instead, this issue raises the proposal directly and leaves the next-step decision to the maintainer.

All other documentation issues closed in the last 7 days (#33079, #32423, #32421, #32418) were already resolved by prior PRs (#32889, #32915, #32496, #32714). Artifact constants in pkg/constants/ are all listed in docs/src/content/docs/reference/artifacts.md. No fresh docs edits are needed today.

Related

• Closed-unmerged healer PR: [docs] Self-healing documentation fixes from issue analysis - 2026-05-19 #33172
• Source drift report: [deep-report] Reconcile schema/parser/compiler drift: tools.serena (x-removed but accepted) and engine.bare (docs claim ✅, compiler warns [Content truncated due to length] #33081
• Prior healer PRs that did land (for contrast): [docs] Self-healing documentation fixes from issue analysis - 2026-05-16 #32496, [docs] Self-healing documentation fixes from issue analysis - 2026-05-17 #32714, [docs] Self-healing documentation fixes from issue analysis - 2026-05-18 #32915

References:

• §26260272921

Generated by 📝 Daily Documentation Healer · ● 15.9M · ◷

• expires on May 25, 2026, 12:11 AM UTC