elastic / elastic/ai-github-actions
[refactor-opportunist] Extract shared docs-patrol data-gathering fragment across base and ESTC variants
- Dominant language
- Python
- Stars
- 11
- Forks
- 16
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 31
Description
## 🏗️ Refactor Proposal
**Summary:** Extract the duplicated Docs Patrol data-gathering instructions into a shared fragment and import it from both base and ESTC external workflow sources.
## Problem
Two workflow sources duplicate the same lookback-window and docs-inventory data-gathering block, so edits must be mirrored manually:
- `.github/workflows/gh-aw-docs-patrol.md` (previously around lines 102-107)
- `.github/workflows/gh-aw-estc-docs-patrol-external.md` (previously around lines 112-117)
This is structural duplication in paired workflow families (`base` + `estc-*`) and contributes to drift risk as these files repeatedly change together.
Concrete coupling evidence from the last 60 days:
- Docs Patrol pair co-changed in **7 commits**
- Newbie Contributor Patrol pair co-changed in **7 commits**
- Recent docs-patrol pair commit examples: `17f7a24`, `fa79dff`, `91477ff`, `5e6f124`, `aa4d10c`, `f374aab`, `36593c8`
## Proposed Approach
Introduce one shared fragment for the common data-gathering scaffold, then import it from both docs patrol variants.
What changes:
- Shared block moved to a fragment file.
- Both workflow wrappers import that fragment and remove duplicate inline text.
What stays the same:
- Workflow IDs, inputs, permissions, tools, and variant-specific analysis sections.
- External-only logic for elastic-docs/applies_to/backports remains in the ESTC workflow.
## Proof of Concept
I partially implemented this refactor on one representative slice (Docs Patrol base + ESTC external) to verify viability.
**Files changed:**
- `.github/workflows/gh-aw-fragments/docs-patrol-data-gathering.md` (new)
- `.github/workflows/gh-aw-docs-patrol.md`
- `.github/workflows/gh-aw-estc-docs-patrol-external.md`
- `.github/workflows/gh-aw-docs-patrol.lock.yml` (compiled output)
- `.github/workflows/gh-aw-estc-docs-patrol-external.lock.yml` (compiled output)
- `gh-agent-workflows/DEVELOPING.md`
**Before → After:**
- Before:
- `gh-aw-docs-patrol.md` and `gh-aw-estc-docs-patrol-external.md` both embedded the same `### Data Gathering` section inline.
- After:
- Shared section lives once in `.github/workflows/gh-aw-fragments/docs-patrol-data-gathering.md:1-6`.
- Both workflow sources now import `gh-aw-fragments/docs-patrol-data-gathering.md`:
- `.github/workflows/gh-aw-docs-patrol.md:5-10`
- `.github/workflows/gh-aw-estc-docs-patrol-external.md:5-10`
- Duplicate inline section removed in both workflow sources:
- `.github/workflows/gh-aw-docs-patrol.md:100-103` now transitions directly to `### What to Look For`
- `.github/workflows/gh-aw-estc-docs-patrol-external.md:110-113` now transitions directly to `### What to Look For`
**Verification:**
- `make compile` → success (`0 error(s), 3 warning(s)`)
- `make lint` → success
- `UV_CACHE_DIR=/tmp/gh-aw/agent/uv-cache make test` → success (`53 passed`)
## Incremental Rollout Plan
This refactor can be completed incrementally:
1. **Completed:** docs-patrol pair now uses shared data-gathering fragment.
2. Apply the same extraction pattern to other `base` + `estc-*` pairs where sections are verbatim (for example, Newbie Contributor Patrol pair).
3. Continue consolidating repeated shared sections into focused fragments, while keeping variant-specific behavior in thin wrappers.
## Risks and Mitigations
- **Risk:** Shared fragment import changes prompt ordering unexpectedly.
- **Mitigation:** keep the fragment narrowly scoped to one section and verify compiled lock outputs.
- **Risk:** Over-consolidation could hide variant-specific requirements.
- **Mitigation:** only extract verbatim shared blocks; leave variant-only sections in wrapper workflows.
## Evidence
- Duplicate block now centralized: `.github/workflows/gh-aw-fragments/docs-patrol-data-gathering.md:1-6`
- Imports added in both source workflows:
- `.github/workflows/gh-aw-docs-patrol.md:5-10`
- `.github/workflows/gh-aw-estc-docs-patrol-external.md:5-10`
- Fragment catalog updated: `gh-agent-workflows/DEVELOPING.md:86-90`
- Compiled workflow outputs include the shared section:
- `.github/workflows/gh-aw-docs-patrol.lock.yml`
- `.github/workflows/gh-aw-estc-docs-patrol-external.lock.yml`
- Co-change signal verified from local git history (`--since='60 days ago'`): 7 co-change commits for docs patrol pair, 7 for newbie pair.
> [!NOTE]
>
> 🔒 Integrity filter blocked 55 items
>
> The following items were blocked because they don't meet the GitHub integrity level.
>
> - [#359](https://github.com/elastic/ai-github-actions/issues/359) `search_issues`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#937](https://github.com/elastic/ai-github-actions/pull/937) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#537](https://github.com/elastic/ai-github-actions/pull/537) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#697](https://github.com/elastic/ai-github-actions/pull/697) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#851](https://github.com/elastic/ai-github-actions/pull/851) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#767](https://github.com/elastic/ai-github-actions/pull/767) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#640](https://github.com/elastic/ai-github-actions/pull/640) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#599](https://github.com/elastic/ai-github-actions/pull/599) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#504](https://github.com/elastic/ai-github-actions/pull/504) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#616](https://github.com/elastic/ai-github-actions/pull/616) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#312](https://github.com/elastic/ai-github-actions/pull/312) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#600](https://github.com/elastic/ai-github-actions/pull/600) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#687](https://github.com/elastic/ai-github-actions/pull/687) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#643](https://github.com/elastic/ai-github-actions/pull/643) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#703](https://github.com/elastic/ai-github-actions/pull/703) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#676](https://github.com/elastic/ai-github-actions/issues/676) `search_issues`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - ... and 39 more items
>
> 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 Refactor Opportunist](https://github.com/elastic/ai-github-actions/actions/runs/25001798309)
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Contributor guide
Assessment
This issue has not been assessed yet.