elastic / elastic/ai-github-actions
[information-architecture] Workflow overview taxonomy does not match homepage or nav entry points
- Dominant language
- Python
- Stars
- 11
- Forks
- 16
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 31
Description
## Area
Documentation navigation flow for GitHub Agent Workflows.
## Components
- `docs/index.md` lines 40-50, 54-62, 80-90, 110: homepage introduces Core Workflows, Repository Maintenance, and Codebase Maintenance, then sends users to the workflow overview.
- `mkdocs.yml` lines 28-71: left nav uses those same task-oriented buckets, with Base Workflows placed after the feature categories.
- `docs/workflows/gh-agent-workflows.md` lines 29-100: overview switches to a different taxonomy: Base workflows, Human-coordinated workflows, Event-driven workflows, Scheduled workflows, and Elastic-specific workflows.
## Evidence
The homepage and nav set user expectations around task-oriented categories. The overview page immediately reclassifies the catalog by implementation/trigger model and puts Base workflows first. The five homepage core workflows are split across Human-coordinated (`Mention in Issue`, `Mention in PR`) and Event-driven (`Issue Triage`, `PR Actions Detective`, `PR Review`) instead of appearing as a recognizable Core Workflows set.
## User impact
Users who click “Browse all 40+ workflows” from the homepage lose the category context they just used to orient themselves. They must translate between two competing taxonomies to find core/repository/codebase workflows, which creates a navigation dead end for the primary recommended path.
## Suggested improvement
Make the workflow overview’s primary sections match the homepage/nav buckets first: Core Workflows, Repository Maintenance, Codebase Maintenance, Planning & Insights, Base Workflows, Advanced, and Elastic-specific. Trigger/implementation groupings can remain as secondary metadata or subsections.
## Duplicate check rationale
This is distinct from already-tracked missing docs/nav links and the PR Actions Detective Core nav issue. The problem is the overview-level taxonomy mismatch across the main entry flow, not a missing page or single misplaced workflow.
---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Information Architecture](https://github.com/elastic/ai-github-actions/actions/runs/29037891258)
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Contributor guide
Research direction
Read the workflow references in docs/index.md, mkdocs.yml, and docs/workflows/gh-agent-workflows.md, starting with the cited line ranges. Compare the homepage and nav buckets with the overview taxonomy and map the catalog into a consistent primary structure. Done means the overview matches the homepage and nav entry points, while any trigger or implementation grouping remains secondary.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100