elastic / elastic/ai-github-actions

[information-architecture] Detector/fixer chaining quick-start hides required workflow permissions

Open
#887 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. Chaining quick-start snippet omits required permissions in the primary setup path
**Area:** Action placement / Progressive disclosure
**Component(s):** `docs/workflows/detector-fixer-chaining.md`, `gh-agent-workflows/bug-hunter/example-chained.yml`, `gh-agent-workflows/code-complexity-detector/example-chained.yml`, `gh-agent-workflows/code-duplication-detector/example-chained.yml`, `gh-agent-workflows/test-coverage-detector/example-chained.yml`

**Problem:** The first "How it works" chaining snippet is positioned as the primary copy/paste setup path, but it does not include a `permissions:` block. The required permission guidance is deferred to a late-page note, so users can complete setup from the top of the page and miss a control that governs whether the fixer can actually write PR changes.

**Evidence:**
- `docs/workflows/detector-fixer-chaining.md:18-35` shows the initial detector→fixer snippet without `permissions:`.
- `docs/workflows/detector-fixer-chaining.md:179` introduces required permission guidance much later ("union of both workflows' permissions").
- Chained examples in workflow directories place permissions near the top:
- `gh-agent-workflows/bug-hunter/example-chained.yml:7-11`
- `gh-agent-workflows/code-complexity-detector/example-chained.yml:7-11`
- `gh-agent-workflows/code-duplication-detector/example-chained.yml:7-11`
- `gh-agent-workflows/test-coverage-detector/example-chained.yml:7-11`

**Suggested improvement:** Move permission requirements into the first chaining snippet (or immediately adjacent callout) so the required control is in-context at the moment users copy setup instructions.

## Suggested Actions
- [ ] Add a `permissions:` block to the first chaining snippet in `docs/workflows/detector-fixer-chaining.md`.
- [ ] Add a brief in-context note before the snippet stating that chaining requires write scopes for both issue creation and PR creation.
- [ ] Keep the late-page note, but make it reinforcement instead of first disclosure.

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

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.