[oblt-aw][agent-suggestions] Agent suggestions - 2026-07-02

[github-actions]

Agent Suggestions

Date: 2026-07-02

1. docs-aw-source-change-drift-detector

Trigger: Daily schedule plus workflow_dispatch; optionally add source-repo merge events later for allowlisted repositories once signal quality is proven.

Purpose: Detect recently merged user-facing product or support changes that have no linked docs follow-up, or whose docs issue/PR is stale. The first rollout should be report-only and scoped to configured source repos and docs repos.

Proposed safe outputs: noop by default; otherwise create_issue or add-comment with one deduplicated report containing the source PR, impacted docs area, existing or missing docs follow-up, age of the gap, and suggested owner. Do not auto-edit docs or open PRs initially.

Current pain points and supporting evidence:

• elastic/kibana#267660 merged on 2026-05-13 and shipped user-facing Fleet agentless changes: a new "Copy support info" action and relocation of the "Show agentless resources" toggle. Its checklist left documentation unchecked.
• elastic/docs-content#7175 was opened on 2026-07-01 to document those same changes, about seven weeks after the source PR merged. The issue explicitly points back to elastic/kibana#267660, identifies the support workflow impact, and asks where the docs should live.
• elastic/docs-content#6502 aggregated six Kibana PRs for Alerting v2 docs work, showing this is not a one-PR pattern: source product changes often need consolidated docs follow-through across multiple PRs.
• elastic/opentelemetry#632 is an active docs follow-up "based on feedback from support" and changes the Managed Prometheus Remote Write docs to clarify a product distinction and Serverless recommendation.
• The current Docs control-plane registry only exposes interactive menu workflows (config/docs/workflow-registry.json:5-23 lists docs-issue-ai-menu and docs-pr-ai-menu).
• The Docs PR menu route runs on-demand review only after a user-triggered menu selection (.github/workflows/docs-aw-pr-ai-menu.yml:180-195 calls gh-aw-docs-review when docs_review_triggered == 'true').

Why not covered already: Existing Docs workflows and docs-actions sweeps focus on reviewing or improving existing docs content: issue/PR AI menus, review, typos, style, frontmatter, openings, coherence, staleness, issue scope, and size. They do not correlate merged product/source PRs with missing or delayed documentation follow-up. Existing oblt-aw workflows cover issue triage/fixing, dependency review, automerge, security, duplicate issues, Buildkite failures, resource-not-accessible failures, autodoc, and agent suggestions, but none audits source-change-to-docs lag. This is also distinct from #1373 (docs-aw-cross-repo-nav-coordinator), which coordinates live cross-repo navigation/link-index PR chains rather than detecting missing docs for product changes.

Expected benefits:

• Engineering productivity: reduce manual discovery of source PRs that need docs work.
• Review quality: give Docs reviewers direct source PR context, impacted behavior, and existing follow-up links in one place.
• Cycle time: shorten the lag between product merges and documentation updates.
• Risk reduction: catch support-affecting changes before users and support engineers rely on stale docs.

Potential trade-offs and rollout considerations:

• Start with a narrow allowlist of source repos/labels, such as Kibana/Fleet or Observability-owned docs-impacting labels, to avoid broad noisy scans.
• Require high-confidence signals: merged source PRs with docs checklist unchecked, docs/release-note labels, explicit support/user-facing language, or links from approved docs issues.
• Dedupe by source PR URL plus docs follow-up issue/PR so scheduled runs do not repeatedly report the same gap.
• Treat issue/PR text as untrusted context; use it only as evidence for maintainers, not as instructions for the workflow.

Duplicate Checks

• Reviewed existing workflow inventory in README.md, docs/workflows/README.md, .github/workflows/, and config/docs/workflow-registry.json.
• Reviewed previous findings in /tmp/previous-findings.json, including [oblt-aw][agent-suggestions] Agent suggestions - 2026-07-01 #1373, [oblt-aw][agent-suggestions] Add safe-output contract auditor workflow #1363, [oblt-aw][agent-suggestions] Add compatibility matrix drift auditor workflow #1351, [oblt-aw][agent-suggestions] Add agent provider health auditor workflow #1332, [oblt-aw][agent-suggestions] Add control-plane rollout drift auditor #1288, [oblt-aw][agent-suggestions] Agent suggestions - 2026-06-20 #1263, and [oblt-aw][agent-suggestions] Add an AI credit guardrail auditor workflow #1233.
• Searched elastic/oblt-aw issues for source-to-docs, docs-aw-source-change-drift-detector, source change, docs drift, product change, and documentation lag; no matching open agent-suggestion was found.
• Three independent investigations were run: control-plane and Observability downstream both recommended noop; the Docs downstream investigation identified this as the only concrete non-duplicate candidate.

Downstream Signals

• [Fleet] Show cluster info for support in agentless integration page kibana#267660
• [Internal]: Document new "Copy support info" button for agentless integrations + update agentless resources toggle location docs-content#7175
• [Alerting V2] [DOCS] [M2] Create Alerting v2 rules and action policies using the AI agent builder docs-content#6502
• Refine Prometheus Remote Write page and Managed inputs naming opentelemetry#632

Suggested Next Steps

• Prototype docs-aw-source-change-drift-detector.yml as a report-only scheduled workflow with noop / create_issue outputs.
• Define a narrow source-repo and label/path allowlist for the first rollout.
• Add deduplication by source PR plus docs follow-up URL before enabling recurring reports.

---

What is this? | From workflow: Observability Agentic Workflow — Schedule

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

• expires on Jul 9, 2026, 7:32 AM UTC