elastic / elastic/ai-github-actions
[information-architecture] Public Watchdogs page advertises internal Downstream Health workflow
- Dominant language
- Python
- Stars
- 11
- Forks
- 16
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 31
Description
## Information Architecture Findings
### 1. Public Watchdogs onboarding points users to an internal-only workflow
**Area:** Grouping / Empty states and onboarding
**Component(s):** `docs/blog/posts/meet-the-watchdogs.md`, `docs/workflows/gh-agent-workflows.md`, `mkdocs.yml`, `gh-agent-workflows/README.md`, `gh-agent-workflows/internal-downstream-health/README.md`
**Problem:** The public Watchdogs blog post presents Downstream Health alongside the public Watchdog workflows, then tells users they can configure and deploy all of these agents from the GitHub Agent Workflows docs. However, the docs catalog and navigation do not expose Downstream Health, while the repository workflow index classifies it as an internal, unsupported workflow. A user following the public onboarding path is encouraged to look for an agent that is not available in the public docs, with no explanation that it is internal-only.
Evidence:
- `docs/blog/posts/meet-the-watchdogs.md:37-39` introduces **Downstream Health** as one of the Watchdog agents.
- `docs/blog/posts/meet-the-watchdogs.md:47-49` says all of these Watchdog agents can be configured and deployed using the GitHub Agent Workflows documentation.
- `docs/workflows/gh-agent-workflows.md:84-99` lists the standalone scheduled workflows exposed in the public workflow catalog, but omits Downstream Health.
- `mkdocs.yml:61-80` exposes Planning & Insights, Base, Advanced, and Elastic-specific workflow nav groups, but no Downstream Health entry.
- `gh-agent-workflows/README.md:92-96` places Downstream Health under **Internal Workflows** and says those workflows are for internal use and not officially supported.
- `gh-agent-workflows/internal-downstream-health/README.md:1-17` still contains a quick install path for the internal workflow, so the missing public docs distinction is not because the workflow lacks setup material.
**Suggested improvement:** Either remove Downstream Health from the public Watchdogs post, or add a clearly labeled internal/unsupported section in the public workflow catalog and navigation so users understand why it differs from the other Watchdog agents before they try to configure it.
## Suggested Actions
- [ ] Decide whether Downstream Health should be public-facing or internal-only.
- [ ] If internal-only, remove it from `docs/blog/posts/meet-the-watchdogs.md` or label it as internal there.
- [ ] If it should be discoverable, add a clearly labeled internal/unsupported entry to the workflow catalog and docs navigation.
---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Information Architecture](https://github.com/elastic/ai-github-actions/actions/runs/28675318239)
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Contributor guide
Research direction
Read the cited sections in docs/blog/posts/meet-the-watchdogs.md, docs/workflows/gh-agent-workflows.md, mkdocs.yml, gh-agent-workflows/README.md, and gh-agent-workflows/internal-downstream-health/README.md. Confirm whether Downstream Health is internal-only, then align the public post, workflow catalog, and navigation with that decision. Done means users can tell whether it is available and supported without following an ambiguous onboarding path.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, markdown, yaml
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100