elastic / elastic/ai-github-actions
[information-architecture] Detective quick install buries required workflow selector customization
- Dominant language
- Python
- Stars
- 11
- Forks
- 16
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 31
Description
## Information Architecture Findings
### 1. Required `workflow_run.workflows` customization is separated from the primary install action
**Area:** Picker placement / Progressive disclosure
**Component(s):** `docs/workflows/gh-agent-workflows/pr-actions-detective.md`, `docs/workflows/gh-agent-workflows/branch-actions-detective.md`, `gh-agent-workflows/pr-actions-detective/example.yml`, `gh-agent-workflows/branch-actions-detective/example.yml`
**Problem:**
The primary setup action is the Quick install copy/paste command, but the critical selector users must customize (`on.workflow_run.workflows`) is only documented later in a Trigger note. Users can complete install from the top section and miss the required selector edit, which leads to a workflow that never triggers when repository CI names differ from the hard-coded examples.
**Evidence:**
- `docs/workflows/gh-agent-workflows/pr-actions-detective.md:7-13` presents Quick install command as the setup path.
- `docs/workflows/gh-agent-workflows/pr-actions-detective.md:23-24` places required `workflows` customization after install in a note.
- `gh-agent-workflows/pr-actions-detective/example.yml:3-5` hard-codes workflow names (`Internal: CI`, `Internal: Tests`, `CI`, `Build`, `Test`).
- `docs/workflows/gh-agent-workflows/branch-actions-detective.md:7-13` uses the same Quick install-first structure.
- `docs/workflows/gh-agent-workflows/branch-actions-detective.md:23-24` also defers required customization to a later note.
- `gh-agent-workflows/branch-actions-detective/example.yml:3-5` also hard-codes workflow names.
**Suggested improvement:**
Move the `workflow_run.workflows` customization requirement into the Quick install section for both detective docs (for example, an explicit “must edit before first run” step immediately after the curl command), and mark example values as placeholders.
## Suggested Actions
- [ ] Add an explicit required post-install step in both detective pages to edit `on.workflow_run.workflows` before first run.
- [ ] Update detective example snippets to label workflow names as repository-specific placeholders.
---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Information Architecture](https://github.com/elastic/ai-github-actions/actions/runs/23861616390)
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Contributor guide
Assessment
This issue has not been assessed yet.