paulk-asert opened a new pull request, #146: URL: https://github.com/apache/airflow-steward/pull/146
## Title `RFC: contribute an issue-* skill family for general-issue-tracker work` ## Body I want to propose a contribution to the framework: a new `issue-*` skill family that parallels `pr-management-*` and `security-issue-*`, scoped to **general-issue-tracker** work (JIRA, GitHub Issues, Bugzilla, GitLab Issues, etc.). I've spiked the contribution locally — both the framework side (in a fork) and the adoption side (in `apache/groovy`) — to validate the shape. **Nothing has been pushed.** I want to align on the design choices before opening any PR. ### Why a new family Apache Groovy uses JIRA as our issue tracker and GitHub for PRs. The `pr-management-*` family covers our PR queue well; the `security-issue-*` family covers our security work. But there's no framework-shipped story for general-issue-tracker maintenance — triage of incoming issues, periodic reassessment of the resolved/EOL backlog, fix-drafting for triaged bugs, and the read-only dashboards that surface campaign state. We've been running this manually for a while. After a 4-issue reassessment pilot on May 13, I built out the family as standalone Groovy skills (in our `.agents/skills/` directory); the generalisation exercise turned that into framework-shaped skills that should work for any project with a general-issue tracker. ### What's in the spike Branch `magpieSpike` on my fork (<https://github.com/paulk-asert/airflow-steward/tree/magpieSpike>, **not pushed yet**) contains: **5 new skills in `.claude/skills/`:** - `issue-triage` — per-issue classification (BUG / FEATURE-REQUEST / NEEDS-INFO / DUPLICATE / INVALID / ALREADY-FIXED). Mode: Triage. Mirrors `security-issue-triage`'s structural shape. - `issue-reassess` — pool-level sweep of resolved / EOL issues. Mode: Triage. Companion-file split: `pool-selection.md` / `per-issue-flow.md` / `verdict-aggregation.md`. - `issue-reproducer` — per-issue code extraction + execution. No mode (mechanical, infrastructure-like). Companion-file split: `extraction.md` / `runtime-recipes.md` / `verification.md` / `probe-templates.md` / `verdict-composition.md`. Largest skill by content; was 518 lines standalone in our repo. - `issue-fix-workflow` — drafts a fix PR for a triaged issue (BUG or FEATURE-REQUEST). Mode: Drafting. Mirrors `security-issue-fix`'s pattern; **stricter on PR-opening** — default is "draft and stop", PR opening requires an explicit `--draft-pr` flag plus a confirmation step. - `issue-reassess-stats` — read-only dashboard. No mode. 4-companion split mirroring `pr-management-stats`. **4 new template files in `projects/_template/`:** - `issue-tracker-config.md` (tracker URL, project key, auth, default queries — distinct from the security `tracker_repo` in `project.md`). - `runtime-invocation.md` (build prerequisite + run-a-single-file recipe; resolved by a new `<runtime>` placeholder). - `reassess-pool-defaults.md` (named pool queries for `open-eol`, `reopened`, `stale-unresolved`, project-specific). - `reproducer-conventions.md` (evidence-package directory layout). **4 new placeholders** added to `AGENTS.md` (and to the `skill-validator` allowlist): - `<issue-tracker>` — URL of the project's general-issue tracker - `<issue-tracker-project>` — project key within the tracker - `<runtime>` — recipe for invoking the project's runtime - `<default-branch>` — upstream's default branch (master vs main) **3 new directories under `tools/`:** - `tools/probe-templates/` — cross-family probe templates, initially with `groovy/` subdirectory (3 templates: cross-type, GPath-cross-backend, operator-variants-safe-nav). The README explicitly invites per-runtime contributions (`python/`, `kotlin/`, etc.) — those are first-class subdirectories awaiting contribution. - `tools/dashboard-generator/` — reference Groovy implementation that renders the same dashboard as `issue-reassess-stats` (for adopters who want CI-rendered determinism). Python stub included as a parity-implementation placeholder. - `tools/jira/` — read-only JIRA REST bridge (search / issue / projects subcommands), written in Groovy with `@Grab` for HTTP. The bridge is read-only by design — comment posting and workflow transitions stay with the skills' apply phases (which use explicit user confirmation). **Family overview doc:** `docs/issue-management/README.md`, paralleling `docs/pr-management/README.md`. **Skill-validator:** passes 0 hard / 0 soft on every new file; 0 hard repo-wide. The new skills are at least as clean as the canonical exemplars. **Total:** ~5,750 lines across 31 new files + 4 modified files. ### What I validated locally On the Groovy adopter side, I ran a complete adoption against the local fork (snapshot at `.apache-steward/`, symlinks for `issue-*` into the snapshot, `.apache-steward-config/` with Groovy project facts, `.apache-steward-overrides/` with Groovy behaviour deltas), then re-ran our 4-issue pilot through the new framework. Result: **all 4 verdicts identical** to the standalone Groovy pilot, with reproducer stdout matching the original byte-for-byte. Generated dashboard from the 4 verdicts. The framework's parameterisation surface (config files + overrides) carries every Groovy-specific bit cleanly. I also did a paper exercise — sketching what the same skills would look like for (1) a hypothetical Kotlin-flavoured ASF project and (2) a real Apache Airflow adoption. Both sketches landed in under an hour each, without requiring any skill changes. The generalisation looks solid. ### Decisions I made — please bless or redirect Six choices that affect the contribution's shape. Happy to adjust any of these to match what you'd prefer: 1. **Family name: `issue-*`.** I chose this to mirror `security-issue-*`'s noun-first shape (security-issue + function-verb; for the new family: issue + function-verb). Alternative: `issue-management-*` to mirror `pr-management-*` literally. Either works; `issue-*` is shorter. **Your call?** 2. **Four new placeholders** (`<issue-tracker>`, `<issue-tracker-project>`, `<runtime>`, `<default-branch>`). The `AGENTS.md` hard rule says *"do not invent new placeholders"*, so the contribution explicitly adds them to the placeholder table + the skill-validator allowlist. The alternative would be to fold each into an existing placeholder by overloading (e.g., reuse `<tracker>` and rely on context to disambiguate security vs general). I think distinct placeholders are clearer, but if you prefer overloading I can collapse them. **Your preference?** 3. **`<runtime>` resolves to a recipe file, not a single string.** Existing placeholders resolve to one field in `project.md` (single string). `<runtime>` is different — it resolves to a multi-section recipe in `<project-config>/runtime-invocation.md` (Build prerequisite, Run a single file, Capture conventions, Network handling). The skill consults the file rather than substituting a value. I think this is the cleanest path for a per-project runtime recipe, but it's a slight precedent shift. **OK or refactor?** 4. **`issue-fix-workflow` is stricter on PR-opening than `security-issue-fix`.** Default is *"draft and stop"*; opening a draft PR requires `--draft-pr` + a confirmation. I went stricter because general-issue work doesn't carry the security family's *"PR is the natural endpoint"* assumption (a triaged general issue might need design discussion before a PR makes sense). **Reasonable, or align with `security-issue-fix`?** 5. **`issue-*` and `pr-management-*` are siblings**, not overlapping. The boundary in `docs/issue-management/README.md` positions `issue-*` = issue-tracker side, `pr-management-*` = merge-request side. Many adopters will use both with different trackers (issue-tracker like JIRA + merge-request side like GitHub PRs). **Boundary phrased OK, or want a different framing?** 6. **PR strategy.** Three options, in increasing fragmentation: - **(a)** One PR with everything. Easiest to review as a coherent whole; ~5,750 lines. - **(b)** Two PRs: foundation (placeholders + templates + family overview) and family (5 skills + 3 tool dirs + docs). - **(c)** Four PRs: foundation; `issue-triage` + `issue-reproducer`; `issue-reassess` + `issue-reassess-stats`; `issue-fix-workflow` + tools dirs. - I'd default to (b) — splits cleanly along the foundation-vs-features axis and keeps each PR reviewable-in-one-sitting. **Your preference?** ### Two small fixes I'd like to propose alongside While building this, I spotted two minor issues in the existing framework: - **`AGENTS.md` placeholder table for `<project-config>`** (line ~326) says it resolves to `.apache-steward/` (the gitignored snapshot). The body text at lines 237–262 is more accurate: `<project-config>` is an adopter-chosen path *alongside* the snapshot, not inside it. Happy to roll a fix into the contribution PR. - **`.claude/` is sometimes gitignored project-wide** (Apache Groovy does this for user-local Claude Code settings). This prevents `.claude/skills/setup-steward/` from being committed per the framework's design. Worth documenting in `setup-steward/adopt.md` as an adopter-friction caveat with a resolution path (override the gitignore, or use Pattern B's `.github/skills/` layout). ### Timing I noticed the rename-in-flight note in `README.md` and `AGENTS.md` ("`apache/airflow-steward`, **to be renamed**"). My contribution uses the `apache/airflow-steward` paths everywhere — I'm happy to: - Wait for the rename to land and rebase, OR - Land pre-rename and do a mechanical rename pass once the new name is chosen. **Whichever you prefer.** I have no schedule pressure on the Groovy side — the standalone `.agents/skills/groovy-*` skills work fine; this contribution is about making them reusable across ASF. ### Spike artefacts Happy to share more concrete artefacts if useful: - The 5 skill files (full content). - The new template files. - The Groovy-side adopter setup (config + overrides). - The 4-issue pilot re-run with comparison report and HTML dashboard. Just let me know what would be most useful for the conversation. I can also walk through the design choices on a call if that's preferred — particularly for the `<runtime>` recipe-resolution mechanism, which is the most architecturally novel piece. Thanks for considering — and thanks for the framework itself. The snapshot+symlink+override model is well-designed, and the fact that I could spike a full second adopter in a day without forking anything is a strong signal that the framework's core ideas are right. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
