elastic / elastic/ai-github-actions

[information-architecture] Claude workflow variant selection is hidden from the top-level entrypoint

Open
#1,147 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. Claude permission variants are not discoverable from the first Claude workflow entrypoint
**Area:** Navigation
**Component(s):** `claude-workflows/README.md` (lines 1-9), `claude-workflows/DEVELOPING.md` (lines 3-10), `docs/workflows/claude-workflows.md` (lines 50-56)
**Problem:** The top-level Claude workflows entry page tells users to use per-action docs but does not surface how to choose permission variants (`ro`/`rwx`/`rwxp`). The variant model is documented in contributor-facing `DEVELOPING.md`, while the public docs page shows only a single `pr-review/rwx` usage example. This splits a core setup decision across disconnected locations and makes first-time setup easy to misconfigure.
**Suggested improvement:** Add a "Choose your permission variant" section to `claude-workflows/README.md` (and mirror in docs) with a compact matrix that explains `ro`/`rwx`/`rwxp` and links directly to variant paths/examples for each workflow.

## Suggested Actions
- [ ] Add an explicit variant-selection matrix to `claude-workflows/README.md` with direct links to variant directories/examples.
- [ ] Update `docs/workflows/claude-workflows.md` usage section to show how to select variants consistently (not only `pr-review/rwx`).
- [ ] Keep variant terminology (`ro`, `rwx`, `rwxp`) consistent between user docs and contributor docs.

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

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.