[docs] Self-healing documentation fixes from issue analysis - 2026-04-02

[github-actions]

Self-Healing Documentation Fixes

This PR was automatically created by the Daily Documentation Healer workflow.

Gaps Fixed

• status-comment: decoupling from reaction: — triggers.md described emoji reactions as automatically creating a status comment with the workflow run link. The schema now explicitly states status-comment: true must be set independently — "there is no automatic bundling with ai-reaction." Three changes made:
  1. Removed the incorrect sentence "For issues/PRs, a comment with the workflow run link is created" from the reaction: section.
  2. Added a new Status Comments (status-comment:) section explaining the field must be explicitly enabled and showing a usage example.
  3. Updated the Activation Token section (two locations) to note status comments are conditional on status-comment: true.
• frontmatter.md — Added status-comment: to the on: field bullet list; it was listed alongside reaction: in frontmatter-full.md but absent from the summary reference.

Root Cause

DDUw runs at 6am UTC. The status-comment decoupling change landed in the large refactoring PR #24100 (merged 2026-04-02 at ~13:16 UTC), after DDUw's daily window. The doc-healer caught it by cross-referencing the schema description (status-comment: "Must be explicitly set to true… no automatic bundling with ai-reaction") against triggers.md which still described the old automatic behavior.

💡 DDUw Improvement Suggestions

DDUw Improvement Suggestions

Pattern: Large refactoring PRs (3,000+ files, title not mentioning "docs") that replace schema files and documentation files as new-mode additions are not picked up by DDUw's commit-scanning heuristic. PR #24100's title is "refactor: extract standard repo-memory configuration" — no "docs" keyword, no feature name — so DDUw's PR title scan would not flag it for deeper inspection.

Suggestion: DDUw could add a schema-diff step: when a PR modifies pkg/parser/schemas/*.json, scan for description changes that contradict existing documentation. Specifically, if a schema property's description changes to include "must be explicitly set" or removes "defaults to", flag the corresponding docs file for review.

Second suggestion: Step 1d (cookie-labeled issues scan) is now in place and effective. The recurring pattern of DDUw missing late-day merges could be addressed by scheduling an additional DDUw run at ~18:00 UTC to catch afternoon PRs.

Related Issues

• No closed issues directly tracked this gap; it was identified by comparing the schema against documentation after cross-referencing today's commits.

References:

• §23902438540

Generated by Daily Documentation Healer · ◷

• expires on Apr 5, 2026, 1:34 PM UTC

[Copilot]

Pull request overview

Updates documentation to reflect that status-comment: is an independent on: configuration (not implicitly enabled by reaction:), aligning the reference docs with the current schema behavior.

Changes:

• Removes incorrect reaction: documentation implying it automatically creates a workflow-run status comment.
• Adds a dedicated status-comment: section to triggers.md with guidance and an example.
• Updates frontmatter.md trigger summary list to include status-comment: and clarify it must be explicitly enabled.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
docs/src/content/docs/reference/triggers.md	Clarifies reaction: vs status-comment: behavior; adds status-comment: documentation and updates activation token notes.
docs/src/content/docs/reference/frontmatter.md	Adds status-comment: to the on: field summary list with explicit-enable guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The sentence attributes both creating and updating the status comment to the activation job. In the generated workflow, the activation job can post the initial status comment, but the completion update happens later (e.g., via the conclusion/notify job). Consider rewording to describe this as a workflow-level behavior (posts at start, updates on completion) without implying the activation job performs the update step itself.

Suggested change

	When `status-comment: true`, the activation job posts a comment when the workflow starts and updates it when the run completes. This must be **explicitly enabled** — setting `reaction:` alone does not create status comments.
	When `status-comment: true`, the workflow posts a comment when it starts and updates that comment when the run completes (for example, the activation job may create the comment and a later job updates it). This must be **explicitly enabled** — setting `reaction:` alone does not create status comments.