[doc-healer] DDUw improvement: Step 1c should verify file content directly before falling back to Step 2

[github-actions]

Context

Today's doc-healer run (2026-04-23, workflow §24837628557) analyzed 20 recently closed documentation issues from the last 7 days. All were fully resolved. No documentation gaps were found and no PR was needed.

However, a recurring inefficiency pattern in DDUw Step 1c was identified — a successor to the pattern fixed in #27191.

---

The Pattern

Spec-librarian issues are closed manually by pelikhan before the spec-enforcer's automated fix commits arrive. Example from today:

Event	Time (UTC)
Issue #27928 created (spec audit: pkg/actionpins, pkg/parser, pkg/workflow)	Apr 22 23:47
Issue #27928 closed as completed by pelikhan	Apr 23 01:48
Spec-enforcer fix commit Enforce specifications for actionpins, cli (#28026)	Apr 23 12:09

The 60-minute fallback heuristic (added per #27191) looks for merged PRs within ±60 minutes of issue closure. The fix commit landed 10+ hours later, outside the window. DDUw would fail to match the fix PR and proceed to the "normal Step 2 flow" — unnecessarily scanning recent commits and existing docs.

Despite this, the content was already present in all referenced files when checked:

• GetContainerPin ✅ in pkg/actionpins/README.md
• IsWorkflowSpec ✅ in pkg/parser/README.md
• CrushEngine, OpenCodeEngine, EngineCatalog, etc. ✅ in pkg/workflow/README.md

This means the issue was either a false-positive from the spec-librarian (content already existed at filing time) or was fixed by a commit in the 01:48–12:09 window that isn't visible in the commit list.

---

Which DDUw Step Is Affected

Step 1c — the closed-issue scan falls through the fallback heuristic to the expensive Step 2 path when:

1. Issues are manually closed before their fix PRs land (window too narrow)
2. Issues are false positives (content was already present when the spec-librarian filed them)

---

Suggested DDUw Improvement

Add a direct content-verification check in Step 1c between the fallback heuristic and the Step 2 fallback:

After the fallback heuristic fails to find a fix PR, parse the issue body for specific missing symbols or file paths. Read the referenced file(s) directly and check whether the listed gaps are still present. If all listed gaps are resolved, treat the issue as already addressed and skip it — without proceeding to Step 2.

In pseudocode for Step 1c:

# 1. Search for [docs] PR referencing issue → found? skip
# 2. Search for PR with closes/fixes #NNN → found? verify and skip
# 3. Fallback heuristic: PR within ±60min modifying pkg/<package>/README.md → found? verify and skip
# 4. [NEW] Direct content check: read the file(s) mentioned in the issue body,
#          verify listed symbols/constants are present → present? skip
# 5. Otherwise: treat as unaddressed gap → proceed to Step 2

This approach is:

• More robust than the heuristic: works regardless of PR window size or whether a PR existed at all
• More efficient than Step 2: avoids scanning recent commits for spec-audit issues where the gap is already resolved
• Low risk: a direct read of 1–3 files costs less than a full commit scan

---

Supporting Evidence

• Artifact constant check (Step 2 mandatory): All 9 *ArtifactName constants confirmed in docs/src/content/docs/reference/artifacts.md ✅
• OpenCode integration (OpenCode integration guide: MCP, permissions, and API routing gotchas #27450): All 6 gotchas from the issue are documented in docs/src/content/docs/troubleshooting/common-issues.md ✅
• All 20 recently closed documentation issues: resolved; 0 unaddressed gaps found

---

Related Issues

• [doc-healer] DDUw improvement: spec-librarian fix PRs (Copilot) omit issue references, causing redundant step-1c re-scanning #27191 — Prior doc-healer run identified the 60-minute heuristic gap; the heuristic was implemented but doesn't cover all cases
• Specification Audit — 2026-04-22 — 3 packages with API drift found #27928 — Spec audit issue (Apr 22) that illustrates this pattern

References:

• §24837628557

Generated by Daily Documentation Healer · ● 382.3K · ◷

• expires on Apr 26, 2026, 1:32 PM UTC