elastic / elastic/ai-github-actions

[information-architecture] Detective quick install buries required workflow selector customization

Open
#858 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. 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

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.