elastic / elastic/ai-github-actions

[product-manager-impersonator] Bidirectional nav/catalog drift guard

Open Beginner friendly
#1,830 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:** Extend the existing docs nav/catalog consistency check to also fail when workflows appear in nav/docs but are missing from the catalog.

## Why a Customer Would Want This
Maintainers and downstream users rely on docs navigation and the workflow catalog to discover supported workflows. Today the check is one-way, so reverse drift can slip in and create confusing docs where workflows are visible in one place but absent in another.

## Rough Implementation Sketch
- Update `scripts/check-nav-catalog.py` to compute and report reverse drift (`reachable - catalog_slugs`) in addition to the current forward drift check.
- Keep Elastic-specific exclusions consistent with the current `estc-` handling.
- Add focused tests in `tests/test_check_nav_catalog.py` for reverse-drift failure and message output.
- Keep CI wiring unchanged since `.github/workflows/ci.yml` already runs this script.

## Why It Won't Be That Hard
The script already parses catalog slugs, nav slugs, and transitive doc mentions into sets, then performs a set-difference check. This is a small extension of existing logic plus a couple of tests in an established test file.

## Evidence
- Current check intent is one-way (catalog → nav reachability): `scripts/check-nav-catalog.py` lines 2-13.
- Current implementation only computes `catalog_slugs - reachable`: `scripts/check-nav-catalog.py` lines 147-157.
- Success message confirms only that one direction: `scripts/check-nav-catalog.py` line 159.
- CI already enforces this script, so feature lands in existing guardrail path: `.github/workflows/ci.yml` lines 30-36.
- Existing tests cover forward-missing behavior but not reverse drift: `tests/test_check_nav_catalog.py` lines 138-173.
- No close match found in `/tmp/previous-findings.json` (related-but-different items include #449 docs input table sync, #719 docs category conflict, #1695 quick-setup docs sync, #1809 rename parity).

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

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, especially the existing catalog_slugs and reachable set-difference check, then read the related cases in tests/test_check_nav_catalog.py. Run that focused test file first. Done means reverse drift is detected with consistent estc- handling, the failure message reports it, and the existing CI invocation remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
84/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.