[docs] Self-healing documentation fixes from issue analysis - 2026-05-15

[github-actions]

Self-Healing Documentation Fixes

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

Gaps Fixed

• emoji frontmatter field missing from frontmatter-full.md — PR Add emoji frontmatter field #32200 added the emoji top-level field to the JSON schema and to frontmatter.md, but the auto-generated companion reference docs/src/content/docs/reference/frontmatter-full.md was not regenerated. Added the entry in the position the generator would have placed it (between description and source), matching the surrounding comment-wrapping style.
• gh aw update --repo flag missing from docs/src/content/docs/setup/cli.md — PR Add gh aw update --repo support with isolated shallow checkout and target-repo PR flow #32213 added cross-repository targeting to gh aw update (isolated shallow checkout under .github/aw/updates/<sanitized-repo-id> and target-repo PR creation when combined with --create-pull-request), but the CLI reference was not updated. Added the new flag to the example block, added the target-repo execution note, and appended --repo/-r to the Options list.

Class of issue this matches: the gaps follow the same pattern as #31968 — schema/source change ships, but the canonical reference doc drifts.

Root Cause

DDUw's Step 2 ("Analyze Changes") only inspects the PR body to decide whether docs were updated. When a PR ships a user-facing surface change but its own diff does not modify the matching reference file, DDUw has no mechanism to detect that omission unless it independently audits the schema or CLI surface against the documented surface.

Specifically:

1. frontmatter-full.md is generated by scripts/generate-schema-docs.js, so a schema change that adds a new top-level field requires regenerating that file. DDUw does not currently run or compare against the generator output.
2. gh aw update --repo was added in Go source (pkg/cli/update_command.go) without a paired edit to docs/src/content/docs/setup/cli.md. DDUw scans documentation files but does not currently diff the CLI's --help surface against the **Options:** line in cli.md.

Also noted: DDUw's Step 3 instructs cat .github/instructions/documentation.instructions.md. That path does not exist in this repo — the documentation style guide actually lives at .github/skills/documentation/SKILL.md. Any DDUw run that depends on the cat output for style guidance is silently operating without it.

💡 DDUw Improvement Suggestions

DDUw Improvement Suggestions

Proposed changes to .github/workflows/daily-doc-updater.md:

1. Add a schema/full-reference drift check (new sub-step in Step 4)

   After loading recent commits, list top-level property names in pkg/parser/schemas/main_workflow_schema.json and grep for each in docs/src/content/docs/reference/frontmatter-full.md. Any schema property missing from frontmatter-full.md is a confirmed gap that requires either regenerating the file (preferred — node scripts/generate-schema-docs.js) or adding the entry manually matching the generator's comment style. Treat this as the analogue of the existing artifact-constant check the Healer runs.

2. Add a CLI surface drift check (new sub-step in Step 4)

   For each top-level subcommand under pkg/cli/*_command.go, parse the registered Cobra flags and confirm each appears in the **Options:** line of the corresponding section in docs/src/content/docs/setup/cli.md. A flag in source but not in cli.md is a confirmed CLI documentation gap.

3. Fix the broken documentation guidelines path

   Update Step 3 in .github/workflows/daily-doc-updater.md:

   - cat .github/instructions/documentation.instructions.md
   + cat .github/skills/documentation/SKILL.md

   The current path does not exist and is silently being skipped on every run, which means DDUw is not actually loading the style guide it claims to follow.

4. Strengthen the "Features Modified" sweep (Step 2)

   Currently Step 2 lists features to analyze but does not include an explicit instruction to confirm a paired documentation edit landed in the same PR. Add: "For each new flag, frontmatter field, or CLI command, after analyzing the PR, run a follow-up check: does the same PR's diff include an edit to the matching reference file (cli.md for CLI flags, frontmatter.md/frontmatter-full.md for frontmatter fields, etc.)? If not, treat the missing reference edit as a confirmed gap regardless of the PR body's claims."

These changes prevent the specific class of gap fixed here (schema/CLI surface ships in source, reference doc untouched) from recurring without adding heavy new scanning logic.

Related Issues

• Pattern follows the same shape as [deep-report] Add inline-sub-agents and max-effective-tokens to canonical frontmatter reference #31968 (schema-vs-canonical-reference asymmetry), which was already fixed by [deep-report] Add missing top-level inline-sub-agents and max-effective-tokens to canonical frontmatter references #32010 but did not generalize to subsequent additions.
• Source PRs whose doc fallout this PR resolves: Add emoji frontmatter field #32200 (emoji frontmatter), Add gh aw update --repo support with isolated shallow checkout and target-repo PR flow #32213 (gh aw update --repo).

References:

• §25892603434

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

• expires on May 18, 2026, 12:15 AM UTC

---

Note

This was originally intended as a pull request, but the git push operation failed.

Workflow Run: View run details and download bundle artifact

The bundle file is available in the agent artifact in the workflow run linked above.

To create a pull request with the changes:

# Download the artifact from the workflow run
gh run download 25892603434 -n agent -D /tmp/agent-25892603434

# Fetch the bundle into a temporary ref, then update the local branch
git fetch /tmp/agent-25892603434/aw-docs-self-healing-2026-05-15.bundle refs/heads/docs/self-healing-2026-05-15:refs/bundles/create-pr-docs-self-healing-2026-05-15-310cf3b5de99a40e-0ec90867
git update-ref refs/heads/docs/self-healing-2026-05-15-310cf3b5de99a40e refs/bundles/create-pr-docs-self-healing-2026-05-15-310cf3b5de99a40e-0ec90867
git checkout docs/self-healing-2026-05-15-310cf3b5de99a40e
# Ensure the working tree matches the updated branch
git reset --hard
# Remove the temporary bundle ref
git update-ref -d refs/bundles/create-pr-docs-self-healing-2026-05-15-310cf3b5de99a40e-0ec90867

# Push the branch to origin
git push origin docs/self-healing-2026-05-15-310cf3b5de99a40e

# Create the pull request
gh pr create --title '[docs] Self-healing documentation fixes from issue analysis - 2026-05-15' --base main --head docs/self-healing-2026-05-15-310cf3b5de99a40e --repo github/gh-aw

[pelikhan]

/q investigate safe-outputs failure

[github-actions]

🎩 Mission equipment ready! Q has optimized your workflow. Use wisely, 007! 🔫

[github-actions]

Q Investigation Report: Safe-Outputs Failure Analysis

Run investigated: #25892603434
Workflow: daily-doc-healer

Root Cause: Transient GitHub Infrastructure Failure

The safe-outputs create_pull_request failed in two sequential stages:

Stage 1: Signed GraphQL Push Failed (403)

POST /repos/github/gh-aw/git/refs - 403
Resource not accessible by integration

The safe-outputs handler tried to create the new branch ref via the REST API. This returned 403 despite the job's GITHUB_TOKEN having contents: write (confirmed in the runner permissions log). This suggests a repository ruleset or the GitHub API was temporarily unavailable for this integration.

Stage 2: Git Push Fallback Failed (Timeout)

! [remote rejected] docs/self-healing-2026-05-15-310cf3b5de99a40e (Unable to determine if workflow can be created or updated due to timeout; `workflows` scope may be required.)

GitHub's pre-receive push protection hook timed out while checking if the commit modified workflow files. Since the commit only touched docs/ files (not .github/workflows/), this is a transient GitHub server-side issue, not a permissions gap.

Workflow Configuration Analysis

The daily-doc-healer workflow is correctly configured:

• Safe-outputs job has contents: write, pull-requests: write, issues: write (verified in lock file)
• The GITHUB_TOKEN at runtime confirmed Contents: write in the runner permissions log
• The fallback mechanism worked correctly: issue [docs] Self-healing documentation fixes from issue analysis - 2026-05-15 #32229 was created with the bundle artifact
• Patch is small (67 lines, 2 doc files) — well within max_patch_size: 1024 and max_patch_files: 100 limits
• strict: true mode correctly prevents the agent job from having write permissions (safe-outputs handles all writes)

No workflow configuration changes are needed.

Recovery: Applying the Patch

The agent's changes are preserved in the bundle artifact from run #25892603434. The patch applies these documentation fixes:

• Added emoji field to docs/src/content/docs/reference/frontmatter-full.md
• Added --repo flag documentation to docs/src/content/docs/setup/cli.md

To apply: download the agent artifact from the run, extract the .bundle file, and git fetch it to create the branch.

Verdict: No workflow changes required. The failure was a transient GitHub server-side issue (pre-receive hook timeout). The safe-outputs fallback worked as designed by creating this issue with the bundle. The daily-doc-healer will retry these fixes on the next scheduled run.

🎩 Equipped by Q · ● 29.7M · ◷