elastic / elastic/ai-github-actions

[product-manager-impersonator] Quick-install filename convention guard

Open
#2,054 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

## Feature Idea

**Summary:** Add a lightweight docs lint that enforces one canonical quick-install output filename convention (`trigger-.yml`) across all workflow docs and per-workflow READMEs.

## Why a Customer Would Want This
Copy-paste install commands are the first touchpoint for new adopters. Today, the same workflow is documented with different output filenames depending on which page you read, which creates avoidable confusion during setup, duplicate workflow files, and extra support/debug time.

## Rough Implementation Sketch
- Add `scripts/lint-install-snippets.py` (or extend an existing docs checker) to parse markdown install snippets and validate `-o .github/workflows/trigger-.yml` naming.
- Run it from `make lint` and CI alongside existing docs/navigation checks.
- Start with the highest-traffic workflow docs (`issue-triage`, `mention-in-pr`, `pr-review`) and expand to all `gh-agent-workflows/*/README.md` plus `docs/workflows/gh-agent-workflows/*.md`.
- Emit a clear diff-style failure message so maintainers can fix drift quickly.

## Why It Won't Be That Hard
The repo already uses script-based docs validation (`scripts/check-nav-catalog.py`) and has a stable workflow naming model (`trigger-.yml` generated by `scripts/dogfood.sh`). This proposal is mostly deterministic text parsing and CI wiring with a small surface area.

## Evidence
- `gh-agent-workflows/DEVELOPING.md:38` documents generated trigger naming as `trigger-.yml`.
- `gh-agent-workflows/pr-review/README.md:14` uses `-o .github/workflows/pr-review.yml` while `docs/workflows/gh-agent-workflows/pr-review.md:12` uses `-o .github/workflows/trigger-pr-review.yml`.
- `gh-agent-workflows/issue-triage/README.md:14` uses `-o .github/workflows/issue-triage.yml` while `docs/workflows/gh-agent-workflows/issue-triage.md:12` uses `-o .github/workflows/trigger-issue-triage.yml`.
- `gh-agent-workflows/mention-in-pr/README.md:14` uses `-o .github/workflows/mention-in-pr.yml` while `docs/workflows/gh-agent-workflows/mention-in-pr.md:12` uses `-o .github/workflows/trigger-mention-in-pr.yml`.
- `scripts/check-nav-catalog.py` already enforces cross-doc consistency patterns, so there is precedent for adding another targeted docs integrity check.

---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Product Manager Impersonator](https://github.com/elastic/ai-github-actions/actions/runs/34464157926)

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

Contributor guide

Open the contributing guide

Research direction

Start with scripts/check-nav-catalog.py, scripts/dogfood.sh, and the three cited workflow README and documentation files to understand existing validation and filename conventions. Add the targeted lint and wire it into make lint and CI as described, then run the docs checks against all listed workflow paths. Done means inconsistent output filenames produce a clear diff-style failure while canonical trigger-.yml snippets pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
ci-cd, documentation, tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.