elastic / elastic/ai-github-actions

[information-architecture] Quick-install docs separate required agentics-maintenance from install steps

Open
#872 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 maintenance workflow is separated from the install actions it affects
**Area:** Progressive disclosure / Action placement
**Component(s):** `docs/index.md`, `docs/workflows/gh-agent-workflows.md`, `scripts/quick-setup.sh`
**Problem:** The add-on quick-install snippets on the homepage present a complete-looking setup flow but omit `agentics-maintenance.yml`, while a later section on a different page states that workflows using expiring safe outputs require it. Users can follow the visible install path and miss a required workflow because the control is disclosed out of context.
**Suggested improvement:** Place the `agentics-maintenance.yml` install command adjacent to each quick-install snippet (or add a prominent prerequisite block directly above those snippets).

**Evidence**
- `docs/index.md:72-84` and `docs/index.md:100-116` show add-on install commands without `agentics-maintenance.yml`.
- `docs/workflows/gh-agent-workflows.md:147-155` states the maintenance workflow is required for workflows using expiring safe outputs.
- `scripts/quick-setup.sh:206-213` always installs `agentics-maintenance.yml`, indicating this is part of the expected setup path.

## Suggested Actions
- [ ] Add `agentics-maintenance.yml` installation to homepage add-on quick-install snippets.
- [ ] Add a short “required once per repo” prerequisite callout immediately before those snippets linking to the maintenance requirement section.

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

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.