elastic / elastic/ai-github-actions

[information-architecture] Detector docs inconsistently place noop outcome outside Safe outputs

Open
#1,208 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. Detector pages describe a common no-findings outcome (`noop`) but hide it from the canonical output section
**Area:** Empty states / Consistency
**Component(s):** `docs/workflows/gh-agent-workflows/bugs.md`, `docs/workflows/gh-agent-workflows/code-complexity.md`, `docs/workflows/gh-agent-workflows/pr-actions-detective.md`

**Problem:**
Detector docs present `noop` as the expected empty-state outcome, but some pages do not include `noop` in their **Safe outputs** section (the section users rely on to understand possible run outcomes). This splits critical outcome information across disconnected sections and creates an onboarding mismatch for first-time users.

**Evidence:**
- `docs/workflows/gh-agent-workflows/bugs.md:5` says “Most runs end with `noop`”, but `docs/workflows/gh-agent-workflows/bugs.md:49-52` lists only `create-issue` under **Safe outputs**.
- `docs/workflows/gh-agent-workflows/code-complexity.md:5` says “Most runs end with `noop`”, but `docs/workflows/gh-agent-workflows/code-complexity.md:51-54` lists only `create-issue` under **Safe outputs**.
- `docs/workflows/gh-agent-workflows/pr-actions-detective.md:34-37` includes `noop` directly in **Safe outputs**, showing a conflicting pattern across similar detector-style docs.

**Suggested improvement:**
Standardize detector documentation so **Safe outputs** always includes the no-findings path (`noop`), or add a dedicated “No findings outcome” row directly adjacent to **Safe outputs** on every detector page.

## Suggested Actions
- [ ] Add `noop` to the **Safe outputs** section for detector pages that currently omit it (starting with Bug Hunting and Code Complexity).
- [ ] Apply one consistent detector-doc pattern for where no-findings behavior is documented.
- [ ] Audit other detector docs for the same mismatch and align them.

> [!NOTE]
>
> 🔒 Integrity filter blocked 2 items
>
> The following items were blocked because they don't meet the GitHub integrity level.
>
> - elastic/ai-github-actions#1067 `list_issues`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - elastic/ai-github-actions#1025 `list_issues`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
>
> To allow these resources, lower `min-integrity` in your GitHub frontmatter:
>
> ```yaml
> tools:
> github:
> min-integrity: approved # merged | approved | unapproved | none
> ```
>
>

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

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.