elastic / elastic/ai-github-actions
[product-manager-impersonator] Quick-install filename convention guard
- 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
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