elastic / elastic/ai-github-actions

[information-architecture] Workflow catalog links route Bug Hunter and Docs Patrol to missing pages

Open
#891 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
11
Forks
16
Avg merge
22h 9m
Merged PRs (30d)
31

Description

## Information Architecture Findings

### 1. Scheduled workflow catalog links use non-canonical page paths that dead-end
**Area:** Navigation / Consistency
**Component(s):** `docs/workflows/gh-agent-workflows.md`, `docs/workflows/gh-agent-workflows/bugs.md`, `docs/workflows/gh-agent-workflows/docs-patrol-overview.md`, `docs/index.md`, `mkdocs.yml`

**Problem:**
The central workflow catalog sends users to `bug-hunter.md` and `docs-patrol.md`, but those pages do not exist. Elsewhere in the product hierarchy (homepage and nav), the same features are exposed at different paths (`bugs.md` and `docs-patrol-overview.md`). This breaks navigation expectations and creates dead-end documentation paths from the authoritative catalog.

**Evidence:**
- `docs/workflows/gh-agent-workflows.md:75` links **Bug Hunter** to `gh-agent-workflows/bug-hunter.md` (missing).
- `docs/workflows/gh-agent-workflows.md:78` links **Docs Patrol** to `gh-agent-workflows/docs-patrol.md` (missing).
- Existing targets are at different paths:
- `docs/workflows/gh-agent-workflows/bugs.md` (exists; title "Bug Hunting").
- `docs/workflows/gh-agent-workflows/docs-patrol-overview.md` (exists).
- Other IA surfaces already point to those existing paths:
- `mkdocs.yml:48` uses `workflows/gh-agent-workflows/bugs.md`.
- `mkdocs.yml:52` uses `workflows/gh-agent-workflows/docs-patrol-overview.md`.
- `docs/index.md:94` links Bug Hunting to `workflows/gh-agent-workflows/bugs.md`.
- `docs/index.md:98` links Docs Patrol to `workflows/gh-agent-workflows/docs-patrol-overview.md`.

**Suggested improvement:**
Align the workflow catalog to the canonical page paths already used by nav/home (`bugs.md`, `docs-patrol-overview.md`), or add canonical aliases/redirect pages so all entry points resolve consistently.

## Suggested Actions
- [ ] Update `docs/workflows/gh-agent-workflows.md` links for Bug Hunter and Docs Patrol to the existing canonical docs pages.
- [ ] Standardize naming/path conventions across nav, homepage, and workflow catalog (for example, one canonical slug per workflow).
- [ ] Add redirects or alias pages if old slugs must remain externally referenced.

---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Information Architecture](https://github.com/elastic/ai-github-actions/actions/runs/24095018077)

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.