elastic / elastic/ai-github-actions
[information-architecture] Detector/fixer chaining quick-start hides required workflow permissions
- 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
Assessment
This issue has not been assessed yet.