elastic / elastic/ai-github-actions

[information-architecture] Core Issue Triage setup promises labels without label configuration

Open
#1,520 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. Core Issue Triage setup promises automatic labels, but the label selector is only shown later as optional configuration
**Area:** Picker placement / Disclosure
**Component(s):** `docs/index.md`, `gh-agent-workflows/issue-triage/example.yml`, `docs/workflows/gh-agent-workflows/issue-triage.md`, `gh-agent-workflows/issue-triage/README.md`
**Problem:** The homepage positions Issue Triage as part of the 60-second core install flow and tells users that new issues are "automatically triaged, labeled, and given an implementation plan" (`docs/index.md:13-31`). But the workflow file copied by that install path leaves the label picker commented out (`gh-agent-workflows/issue-triage/example.yml:17-23`), and the workflow docs state that `classification-labels` defaults to an empty string and "If empty, no labels are applied" (`docs/workflows/gh-agent-workflows/issue-triage.md:23-31`; same source README at `gh-agent-workflows/issue-triage/README.md:25-33`).

Users following the primary onboarding path reasonably expect the core workflow to label issues, but they actually get comment-only triage unless they later discover and configure `classification-labels` plus label semantics. That required choice is separated from the setup action it affects, so the installed result does not match the stated outcome.

**Suggested improvement:** Put a label-selection step directly beside the core install command, include an uncommented placeholder in the Issue Triage setup flow that users must customize, or soften the homepage promise to say issues are triaged and optionally labeled when `classification-labels` is configured.

## Suggested Actions
- [ ] Update the homepage/core install flow so the Issue Triage label configuration appears before or next to the copy/paste command.
- [ ] Clarify that automatic labeling requires a non-empty `classification-labels` allowlist and corresponding semantics in `additional-instructions`.
- [ ] Align the homepage outcome text with the default installed behavior if labeling remains optional.

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

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

Contributor guide

Open the contributing guide

Research direction

Start by comparing the homepage copy in docs/index.md with the label configuration in gh-agent-workflows/issue-triage/example.yml, docs/workflows/gh-agent-workflows/issue-triage.md, and gh-agent-workflows/issue-triage/README.md. Align the install flow and outcome text so the required classification-labels allowlist and label semantics are visible, or make the optional behavior explicit. Done means the setup instructions and promised default behavior agree across these files.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions
Domain
ci-cd, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.