elastic / elastic/ai-github-actions

[information-architecture] Continuous-improvement workflow set is inconsistent across onboarding docs

Open
#1,699 0 comments 0 reactions 0 assignees View on GitHub
information-architecture
Dominant language
Python
Stars
11
Forks
16
Avg merge
22h 9m
Merged PRs (30d)
31

Description

## Information Architecture Findings

### 1. Continuous-improvement workflow set is defined inconsistently across primary setup paths
**Area:** Consistency
**Component(s):**
- `README.md` (top-level)
- `docs/workflows/gh-agent-workflows.md`
- `gh-agent-workflows/README.md`
- `scripts/quick-setup.sh`

**Problem:**
Users are shown two different definitions of what `--continuous-improvement` installs, depending on where they start. The top-level onboarding surfaces omit `product-manager-impersonator` and `refactor-opportunist`, while the workflow README and installer script include both. This creates a navigation/hierarchy mismatch between “what docs say this set is” and “what the setup action actually does,” which can surprise users with unexpected scheduled workflows after installation.

**Evidence:**
- `README.md:26` — continuous-improvement list omits `product-manager-impersonator` and `refactor-opportunist`.
- `docs/workflows/gh-agent-workflows.md:27` — same omission in the docs-site workflow overview.
- `gh-agent-workflows/README.md:67-80` — `--continuous-improvement` list includes both workflows.
- `scripts/quick-setup.sh:122-136` — installer behavior includes both workflows.

**Suggested improvement:**
Establish one canonical continuous-improvement set and keep all onboarding entry points aligned with it. At minimum, synchronize:
1. `README.md` continuous-improvement list
2. `docs/workflows/gh-agent-workflows.md` recommended set
3. `gh-agent-workflows/README.md` set description
4. `scripts/quick-setup.sh` install set (or adjust docs to match if behavior is intentional)

## Suggested Actions
- [ ] Decide the canonical `--continuous-improvement` workflow set (including whether `product-manager-impersonator` and `refactor-opportunist` are intended defaults).
- [ ] Update all three documentation entry points to match the canonical set.
- [ ] Add a lightweight consistency check in CI (or docs lint) so workflow-set lists stay synchronized with `scripts/quick-setup.sh`.

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

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.