elastic / elastic/ai-github-actions
[refactor-opportunist] Extract shared newbie docs-audit rubric fragment for base and ESTC workflows
- Dominant language
- Python
- Stars
- 11
- Forks
- 16
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 31
Description
## 🏗️ Refactor Proposal
**Summary:** Extract the duplicated newbie-docs audit rubric into one shared fragment and keep only workflow-specific deltas in each workflow source.
## Problem
`gh-aw-newbie-contributor-patrol.md` and `gh-aw-estc-newbie-contributor-patrol-external.md` duplicated the same baseline docs-audit instructions (data gathering, core checks, and reporting bar), so prompt updates required synchronized edits in two files.
Concrete evidence:
- Shared imports/config shape in both files, now both importing the new fragment:
- `.github/workflows/gh-aw-newbie-contributor-patrol.md:5-16`
- `.github/workflows/gh-aw-estc-newbie-contributor-patrol-external.md:5-16`
- Extracted duplicated baseline prompt sections from both workflows into:
- `.github/workflows/gh-aw-fragments/newbie-contributor-docs-core.md:1-21`
- Both workflows changed together recently (coupling signal):
- `17f7a24` (“disable stale checks”)
- `fa79dff` (“update workflow versions”)
- `91477ff` (“remove stale check for remote workflows”)
## Proposed Approach
Create one shared fragment for the baseline newbie-docs rubric and import it in both workflows. Keep ESTC-specific behavior local (Elastic docs MCP cross-reference + contradictions-as-blockers rule), and keep issue format text per workflow.
## Proof of Concept
I partially implemented this refactor on one representative slice to verify viability:
**Files changed:**
- `.github/workflows/gh-aw-fragments/newbie-contributor-docs-core.md` (new)
- `.github/workflows/gh-aw-newbie-contributor-patrol.md`
- `.github/workflows/gh-aw-estc-newbie-contributor-patrol-external.md`
- `.github/workflows/gh-aw-newbie-contributor-patrol.lock.yml` (generated)
- `.github/workflows/gh-aw-estc-newbie-contributor-patrol-external.lock.yml` (generated)
**Before → After:**
- **Before:** both workflow sources contained copied baseline sections (`### Data Gathering`, `### What to Look For`, `### Reporting Bar`).
- **After:** shared baseline lives in `gh-aw-fragments/newbie-contributor-docs-core.md`; each workflow now imports it, and ESTC keeps only its extra sections:
- `.github/workflows/gh-aw-estc-newbie-contributor-patrol-external.md:105-116`
Snippet (new shared core):
```md
### Data Gathering
1. Discover documentation files ...
2. Follow the quick start ...
### What to Look For
- Missing prerequisites ...
- Inconsistent instructions ...
...
### Reporting Bar
Only report **blocking** or **high-impact** ...
```
**Verification:**
- `make compile` completed successfully (updated lock files).
- `make lint` completed successfully.
- `PATH=$HOME/.local/bin:$PATH UV_CACHE_DIR=/tmp/gh-aw/agent/uv-cache make test` completed successfully (`53 passed`).
## Incremental Rollout Plan
This refactor can be completed incrementally:
1. Extract shared baseline rubric and migrate the two newbie workflows (completed in this POC).
2. Apply the same pattern to other workflow pairs that share a baseline + variant deltas.
3. Keep variant-specific checks local; evolve shared fragment only for true baseline behavior.
## Risks and Mitigations
- **Risk:** Over-centralizing could hide variant-specific requirements.
**Mitigation:** Keep only baseline checks in the shared fragment; preserve variant-only sections in source workflows.
- **Risk:** Prompt behavior drift after extraction.
**Mitigation:** Compile lock files on every change and keep workflow-specific issue format blocks local.
## Evidence
- `.github/workflows/gh-aw-fragments/newbie-contributor-docs-core.md:1-21`
- `.github/workflows/gh-aw-newbie-contributor-patrol.md:5-16,93-117`
- `.github/workflows/gh-aw-estc-newbie-contributor-patrol-external.md:5-16,103-141`
- Co-change commits: `17f7a24`, `fa79dff`, `91477ff`
> [!NOTE]
>
> 🔒 Integrity filter blocked 28 items
>
> The following items were blocked because they don't meet the GitHub integrity level.
>
> - [#1128](https://github.com/elastic/ai-github-actions/pull/1128) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#378](https://github.com/elastic/ai-github-actions/pull/378) `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".
> - [#700](https://github.com/elastic/ai-github-actions/pull/700) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#608](https://github.com/elastic/ai-github-actions/pull/608) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#764](https://github.com/elastic/ai-github-actions/pull/764) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#490](https://github.com/elastic/ai-github-actions/pull/490) `search_pull_requests`: 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".
> - [#589](https://github.com/elastic/ai-github-actions/pull/589) `search_pull_requests`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#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".
> - [#794](https://github.com/elastic/ai-github-actions/pull/794) `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".
> - [#354](https://github.com/elastic/ai-github-actions/issues/354) `search_issues`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#420](https://github.com/elastic/ai-github-actions/issues/420) `search_issues`: 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".
> - ... and 12 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/26407120613)
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Contributor guide
Assessment
This issue has not been assessed yet.