elastic / elastic/ai-github-actions

[product-manager-impersonator] Shared fragment inventory lint

Open
#1,399 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 lint that keeps the shared `gh-aw-fragments` inventory aligned with actual fragment files and workflow imports.

## Why a Customer Would Want This
Maintainers who add or modify GitHub Agent Workflows need a reliable map of reusable fragments. Today the fragment catalog is manually maintained, so new contributors and agentic implementers can miss existing building blocks or leave stale architecture docs behind.

## Rough Implementation Sketch
- Add a small script such as `scripts/check-gh-aw-fragments.py` that scans `.github/workflows/gh-aw-fragments/*.md`.
- Parse workflow `imports:` entries in `.github/workflows/gh-aw-*.md` and compare them with the documented fragment table in `gh-agent-workflows/DEVELOPING.md`.
- Report undocumented fragments, documented-but-missing fragments, and optionally unused fragments.
- Wire the check into `make lint` next to the existing documentation/catalog checks.

## Why It Won't Be That Hard
This is a local file inventory check: no compiler or runtime behavior needs to change. The repository already has the pattern of Python-backed lint checks in `make lint`, and the relevant data lives in predictable Markdown files and frontmatter import lists.

## Evidence
- `gh-agent-workflows/DEVELOPING.md:82-105` documents a manual shared-fragment catalog.
- `gh-agent-workflows/DEVELOPING.md:143-148` tells maintainers to edit workflows, triggers, and fragments as part of the normal workflow-editing path.
- `Makefile:266-267` currently runs workflow/action lint plus `scripts/check-nav-catalog.py`, but there is no fragment inventory check in that lint path.
- The repository currently has 35 files under `.github/workflows/gh-aw-fragments/`, while only 19 are referenced in the `DEVELOPING.md` catalog. Missing catalog entries include `runtime-setup.md`, `network-ecosystems.md`, `pr-context.md`, and `safe-output-code-review.md`.
- `.github/workflows/gh-aw-pr-review.md:5-18` imports several undocumented fragments, including `runtime-setup.md`, `pr-context.md`, `safe-output-code-review.md`, and `network-ecosystems.md`.

Duplicate check: Existing product-manager findings cover workflow scaffolding, scoped compile, artifact parity, example-trigger linting, and docs input-table sync, but I found no open issue for a shared-fragment catalog/import inventory lint.

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

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

Contributor guide

Open the contributing guide

Research direction

Start with the fragment catalog in gh-agent-workflows/DEVELOPING.md:82-105, the imports in .github/workflows/gh-aw-pr-review.md:5-18, and the existing lint wiring at Makefile:266-267. Compare the files under .github/workflows/gh-aw-fragments/ with documented and imported entries, then run make lint; done means the check reports discrepancies clearly and passes when the inventory is aligned.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.