Repository navigation
Description
Context
The 2026-04-19 doc-healer run analyzed 13 closed documentation issues from the last 7 days (since 2026-04-12). All were fully resolved. However, a recurring systemic pattern was identified that causes DDUw to do unnecessary re-scanning work on every subsequent run.
The Pattern
Spec-librarian workflow files an issue (e.g., #27110 — "API drift in pkg/constants: 6 undocumented symbols"). Within minutes, the Copilot agent creates and merges a fix PR (e.g., #27111 — "docs(constants): sync README with newly exported guard-policy, BYOK, and AWF version constants"). The fix PR correctly resolves the issue, but does not include closes #27110, fixes #27110, or resolves #27110 in its body.
DDUw's step 1c then:
- Finds Specification Audit — 2026-04-18 — 1 issue found: API drift in
pkg/constants#27110 as a "closed as completed" documentation issue. - Searches for a
[docs]-labeled PR referencing it — not found. - Searches for any merged PR with
closes #27110/fixes #27110/resolves #27110— not found (Copilot's PR didn't include this). - Proceeds to "normal Step 2 flow" — reads
pkg/constants/README.md, confirms the 6 constants are now documented. - Correctly skips the issue, but only after unnecessary file reads.
This pattern repeated for multiple spec-librarian issues this week:
| Spec Audit Issue | Fix PR | PR references issue? |
|---|---|---|
| #27110 (constants: 6 missing constants) | #27111 | ❌ No |
| #26758 (workflow: 6 missing functions) | spec-extractor PRs | ❌ No |
| #26329 (console: 21 missing functions) | #26330 | likely no |
Root Cause
Step 1c of DDUw relies on explicit issue reference patterns (closes #NNN, fixes #NNN, resolves #NNN) in PR bodies. The Copilot agent that fixes spec-librarian issues writes descriptive PR bodies ("The package spec audit reported API drift...") but does not emit these references.
This is a refinement of the pattern reported in #26442, which covered general non-[docs] PR closures. The fix for that issue (add closes/fixes/resolves #NNN search) works for issues that are explicitly closed by a PR, but not when the Copilot PR omits the issue number entirely.
Which DDUw Step Failed
Step 1c — the closed-issue scan cannot match Copilot's spec-fix PRs to the spec audit issues they resolve, because those PRs don't include issue reference keywords.
Evidence from This Run
- Artifact constant check (Step 2 mandatory): All 9
*ArtifactNameconstants confirmed indocs/src/content/docs/reference/artifacts.md✅ - All 13 recently closed documentation issues resolved; 0 unaddressed gaps found
- All confirmed gaps verified against current source and README files
Suggested DDUw Improvements
Option A (preferred — fix at source): Configure the Copilot spec-fix workflow (or the spec-librarian issue template) to instruct Copilot to always include Closes #NNN in fix PR bodies. This is the most reliable fix.
Option B (DDUw-side heuristic): In step 1c, after failing to find explicit issue references, also check: "Was a PR merged within 60 minutes of this issue being closed that modifies the same package's README?" If yes, treat it as the fix. This is implementable as:
repo:github/gh-aw is:pr is:merged merged:>=[issue_closed_at - 60min] path:pkg/{package}/README.md
Option C (low-effort mitigation): Add a note to the spec-librarian issue template asking Copilot to reference the issue when opening a fix PR (e.g., "When creating a fix PR, include Closes #NNN in the description").
References:
- §24630042941
- Related: [doc-healer] DDUw improvement: recognize non-[docs] PR closures in step 1c to avoid redundant re-scanning #26442 (DDUw improvement for non-[docs] PR closures — partially overlapping)
Generated by Daily Documentation Healer · ● 485.9K · ◷
- expires on Apr 22, 2026, 1:29 PM UTC
Activity