elastic / elastic/ai-github-actions

[information-architecture] Create Comment On Issue is mis-grouped under Codebase Maintenance

Open
#1,226 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. 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

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.