elastic / elastic/ai-github-actions
[information-architecture] Create Comment On Issue is mis-grouped under Codebase Maintenance
- Dominant language
- Python
- Stars
- 11
- Forks
- 16
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 31
Description
## Information Architecture Findings
### 1. Create Comment On Issue is categorized in a way that hides its primary use
**Area:** Grouping
**Component(s):** `mkdocs.yml`, `docs/workflows/gh-agent-workflows/create-comment-on-issue.md`, `docs/upgrading.md`, `docs/workflows/gh-agent-workflows.md`
**Problem:** The docs navigation places **Create Comment On Issue** under **Codebase Maintenance**, alongside detector content (`mkdocs.yml` lines 45-48). But the workflow page describes it as a general `workflow_call` utility and a direct alternative to Mention in Issue (`docs/workflows/gh-agent-workflows/create-comment-on-issue.md` lines 3-6, 42-47, 65-69). Upgrading guidance also points to it as the preferred migration target for deprecated mention-by-id behavior (`docs/upgrading.md` lines 90-103). This mismatch makes users look in the wrong place when searching for commenting/composition primitives.
**Suggested improvement:** Move **Create Comment On Issue** (and optionally **Detector / Fixer Chaining**) into a neutral section such as **Workflow Composition** (or **Base Workflows**) and keep cross-links from mention/migration pages.
## Suggested Actions
- [ ] Reclassify `Create Comment On Issue` in `mkdocs.yml` to a composition-oriented section.
- [ ] Add/retain cross-links from Mention and Upgrading pages to the new location.
- [ ] Keep detector pages referencing it as a chaining option, but not as its primary category.
---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Information Architecture](https://github.com/elastic/ai-github-actions/actions/runs/26969704142)
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Contributor guide
Assessment
This issue has not been assessed yet.