This is an automated email from the ASF dual-hosted git repository.
paulk-asert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git
The following commit(s) were added to refs/heads/master by this push:
new ecd0bbe741 AI readiness: add draft triage skill
ecd0bbe741 is described below
commit ecd0bbe741d28637b81b4d32046549c60e149c51
Author: Paul King <[email protected]>
AuthorDate: Tue May 12 09:19:53 2026 +1000
AI readiness: add draft triage skill
---
.agents/skills/groovy-triage/SKILL.md | 154 ++++++++++++++++++++++++++++++++++
AGENTS.md | 2 +
2 files changed, 156 insertions(+)
diff --git a/.agents/skills/groovy-triage/SKILL.md
b/.agents/skills/groovy-triage/SKILL.md
new file mode 100644
index 0000000000..94dffecafd
--- /dev/null
+++ b/.agents/skills/groovy-triage/SKILL.md
@@ -0,0 +1,154 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+---
+name: groovy-triage
+description: Guidance for AI-assisted triage of Apache Groovy JIRA issues and
GitHub pull requests — reproducing reported bugs against `master`, finding
duplicates, checking that JIRA component / affected-version fields are
populated, and surfacing PR-readiness signals (linked JIRA, ASF license
headers, drive-by reformatting, CI status) without taking committer-only
actions. Use when grooming the JIRA backlog or doing a first-pass review on a
PR.
+license: Apache-2.0
+compatibility: claude, codex, copilot, cursor, gemini, aider
+metadata:
+ audience: contributors to apache/groovy
+ scope: issue-and-pr-triage
+---
+
+# Groovy triage
+
+Use this skill when the task is **triaging** — surfacing the state of
+a JIRA issue or a pull request and proposing next steps — rather than
+writing the fix itself. Triage output is *advisory*: it lands as a
+JIRA comment or PR review for a committer to act on. This skill never
+resolves a JIRA, sets a fix version, merges a PR, or closes anything
+without explicit committer instruction.
+
+For the JIRA *mechanics* the triage pass relies on — JQL recipes, the
+`Component/s` taxonomy, the field-ownership matrix, and the
+"don't transition workflow states" rule — load
+[`groovy-jira`](../groovy-jira/SKILL.md) alongside this skill.
+
+For the actual fix work, hand off to
+[`groovy-internals`](../groovy-internals/SKILL.md),
+[`groovy-tests`](../groovy-tests/SKILL.md),
+[`groovy-build`](../groovy-build/SKILL.md), or
+[`groovysh`](../groovysh/SKILL.md) depending on where the change lands.
+
+## When to use this skill
+
+**Use it for:**
+
+- Walking a JIRA issue: reading the report, attempting reproduction on
`master`, searching for duplicates / related issues, checking that
`Component/s`, `Affects Version/s`, `Priority`, and `Issue Type` are populated,
and drafting a comment with findings.
+- First-pass review on a GitHub pull request: checking the PR links a JIRA,
that new files carry the ASF header, that the diff matches the stated scope,
and that CI is green — then drafting review comments.
+- Bulk grooming: producing a short, structured report across N issues or N PRs
(one bullet per item) for a committer to scan.
+
+**Don't use it for:**
+
+- Actually fixing the bug — once triage points at a real defect, switch to the
relevant area skill.
+- Setting JIRA workflow state (`In Progress`, `Resolved`, `Fix Version/s`) —
that's a committer action; surface a recommendation instead.
+- Security reports. Suspected vulnerabilities go to
<[email protected]> per the ASF process, *not* into a public JIRA or
PR comment. If a public issue or PR appears to disclose a vulnerability, flag
privately to a committer and stop.
+- Anything outside `apache/groovy` — sister repos (`groovy-website`, etc.)
have their own conventions.
+
+## Read first
+
+- [`GOVERNANCE.md`](../../../GOVERNANCE.md) — where JIRA sits in the project's
communication channels and what it's the canonical record of.
+- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) — JIRA reference convention in
commits (`GROOVY-NNNNN: …`) and the regression-test contract that fixes are
expected to satisfy.
+- [`AGENTS.md`](../../../AGENTS.md) — ASF licensing / provenance rules, the
`Assisted-by:` trailer, and the "what *not* to do" list (drive-by reformat,
speculative abstractions) — these are the signals to flag on PR triage.
+
+## Top failure modes
+
+These are the recurring mistakes when AI tooling triages Groovy issues and PRs:
+
+1. **Treating the reporter adversarially.** The default tone for JIRA comments
is helpful and specific. Don't dismiss a report as "works for me" without
showing what you ran. Don't suggest closing as "Cannot Reproduce" without a
documented reproduction attempt against a stated `master` revision and the JDK
noted in the issue.
+2. **Asking for a reproducer that's already inline.** Before requesting "a
minimal example," check the description, comments, and any attachments. A
surprising fraction of issues have a complete reproducer the LLM skipped past.
+3. **Not actually reproducing against `master`.** A report against `4.0.x` may
already be fixed on `master`. Run the reproducer (or a stub of it) on `master`
with the targeted Gradle test invocation before commenting. If it passes on
`master`, say so explicitly and name the revision and JDK — that's the useful
signal, not a guess.
+4. **Missing the duplicate.** `git log --grep='GROOVY-NNNN'` finds prior
commits referencing a JIRA; a JIRA text search finds similar wording. Spend the
search budget *before* writing a long analysis — a one-line "duplicate of
GROOVY-XXXX, fixed in 4.0.Y" beats a 500-word root-cause summary of a known bug.
+5. **Confusing "the test passes" with "the bug is fixed."** A reporter's
snippet may need adaptation to run as a `@Test`. If your adapted version passes
but the original snippet (as a script) still fails, the bug isn't fixed — note
the discrepancy.
+6. **Drive-by closure of stale issues.** The Groovy JIRA holds long-tail
reports that remain valid even after years of silence. "Last activity 2019" is
*not* sufficient grounds to recommend closure. Only recommend closure with a
concrete reason: reproduction now passes on `master`, the affected version is
past end-of-life, or the report duplicates a resolved issue (cite the JIRA).
+7. **PR triage that ignores the AGENTS.md "what *not* to do" list.** The list
(drive-by reformatting, unsolicited refactors, hallucinated APIs, speculative
abstractions, scratch files) is exactly what a first-pass reviewer should be
flagging. If a PR diff is 80% whitespace, that's the headline finding.
+8. **Missing the JIRA reference on a bug-fix PR.** `CONTRIBUTING.md` calls for
`GROOVY-NNNNN: …` in the commit message for issue-linked changes. If a PR
claims to fix a bug but doesn't reference a JIRA, the triage comment should ask
for one (or point out that pure refactors / docs PRs may legitimately have
none).
+9. **Approving without an ICLA check on first-time contributors.** New
external contributors need an ICLA on file for non-trivial changes. Don't
assert ICLA status — the bot or a committer confirms it — but do flag
"first-time contributor, ICLA status unknown" so the committer can check.
+10. **Conflating CI red with PR bad.** GitHub Actions on this repo include
long-running and occasionally flaky jobs (joint-validation, JMH). Distinguish a
genuine failure in `groovy-build-test` from a transient timeout in
`grails-joint-validation`; quote the failing job name and the first failing
test rather than just "CI red."
+11. **Writing an `Assisted-by:` trailer the contributor didn't ask for.** The
trailer is the *contributor's* call to make on their own commit. Triage output
is a comment, not a commit — don't suggest editing someone else's commit
message to add the trailer; just point at [`AGENTS.md`](../../../AGENTS.md) if
AI involvement is obvious and undisclosed.
+
+For the JIRA-mechanics failure modes that used to live here — inventing `Fix
Version/s`, transitioning workflow states, fabricating components, malformed
JQL — see [`groovy-jira`](../groovy-jira/SKILL.md).
+
+## Procedure for JIRA-issue triage
+
+For each issue you triage:
+
+1. **Read the full thread.** Description, all comments, attachments. Note the
reported Groovy version, JDK, and OS. If the reporter included a stack trace,
identify the top non-JDK frame — that's usually the entry point for "where in
the code?"
+2. **Search for duplicates / related work.**
+
+ ```
+ git log --grep='GROOVY-<NNNN>' # commits referencing this JIRA
+ git log --grep='<short distinctive phrase>' -- src/
+ ```
+
+ Plus a JQL text search — see the "Duplicate hunting by error string" recipe
in [`groovy-jira`](../groovy-jira/SKILL.md). If you find a duplicate, stop and
draft a "duplicate of …" comment.
+
+3. **Attempt reproduction on `master`.**
+ - If the reporter gave a script: drop it into a temp file and run via
`./gradlew run` or paste it into the relevant test class as a `@Test`. Capture
the exact output.
+ - If the reporter gave a `@Test`-shaped snippet: follow
[`groovy-tests`](../groovy-tests/SKILL.md) for placement and run targeted
(`:test --tests <FQN>`).
+ - Record: the `master` revision (`git rev-parse --short HEAD`), the JDK
(`java -version`), the targeted command, and the outcome.
+
+4. **Locate the code, lightly.** If the reproducer reaches the
runtime/compiler, identify the package or class the failure flows through (top
non-JDK frame in the trace, or `git log -p -S '<unique string>'` to find recent
edits). Don't go deeper than "this lives under
`org.codehaus.groovy.transform.stc.*`" unless asked — pointing the right area
skill at it is the goal.
+
+5. **Check JIRA fields.** Note (don't edit) what's missing or wrong.
Field-ownership rules and `Component/s` suggestion guidance live in
[`groovy-jira`](../groovy-jira/SKILL.md); apply them here.
+
+6. **Draft the comment.** Structure it as: state of repro (passed / failed /
could not run, with revision + JDK), duplicate search result, likely area of
the code, suggested missing JIRA fields, recommended next action (e.g. "needs a
minimal reproducer," "looks fixed on master — propose closing as Cannot
Reproduce after a second pair of eyes," "appears to need a fix in `<area>`").
Keep it factual; don't editorialise.
+
+7. **Don't transition the issue.** Even when the recommendation is clear,
leave the workflow state to a committer (see
[`groovy-jira`](../groovy-jira/SKILL.md)).
+
+## Procedure for PR triage
+
+For each PR:
+
+1. **Read the PR description and the linked JIRA (if any).** A bug-fix PR
without a `GROOVY-NNNNN` reference is the first thing to flag; a docs /
build-housekeeping PR without one is fine.
+2. **Scan the diff for shape, not just substance.**
+ - **New files:** every `.java`, `.groovy`, `.gradle`, `.xml` must carry the
ASF license header. Missing header → flag.
+ - **Drive-by reformatting:** large whitespace-only hunks, end-of-line
changes, or reordered imports outside the touched method signal a `what *not*
to do` violation. Quote a representative file:line range.
+ - **Hallucinated identifiers:** API methods or flags that grep doesn't find
in the codebase. Search `git grep` before assuming a name is real.
+ - **Scope creep:** does the diff match what the description and the JIRA
say it should do? Surrounding refactors get called out.
+3. **Check for the regression test.** If the PR claims to fix a JIRA-tracked
bug, [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) calls for an accompanying
test. Confirm the new test exists, follows `Groovy<NNNN>` or `//
GROOVY-<NNNN>`-comment naming (see [`groovy-tests`](../groovy-tests/SKILL.md)),
and lives in a sensible location. Confirm it would fail without the production
change — easiest check: revert just the production hunk, run the test, expect
failure.
+4. **Look at CI.** Identify the *first* failing job and the *first* failing
test in that job; quote them. Don't say "CI red" without specifics. Note
known-flaky jobs (joint-validation, JMH) separately from core test failures.
+5. **Note ICLA / first-time-contributor signal.** Surface it as a note for the
committer; don't gate review on it.
+6. **Draft the review.** Order findings by what would block merge first:
license-header / scope / test, then style / drive-by reformat, then nits. Use
the file-path:line format from this repo's conventions so committers can jump
to each finding.
+
+## Validation checklist
+
+Before posting the triage output:
+
+- [ ] The comment / review is grounded in something you *ran* or *searched* —
not speculation. Each non-trivial claim cites either a command output, a `git
grep` hit, or a JIRA / file reference.
+- [ ] JIRA-mechanics checks pass — see the validation checklist in
[`groovy-jira`](../groovy-jira/SKILL.md) (no workflow transitions, no invented
`Fix Version/s`, suggested components are real, JQL leads with `project =
GROOVY`).
+- [ ] No suggested edit to someone else's commit message (including
`Assisted-by:` trailer).
+- [ ] If recommending closure of an old JIRA: a concrete reason (revision +
JDK on which it now passes, or the duplicate JIRA-ID).
+- [ ] If recommending duplicate: the duplicate JIRA is linked.
+- [ ] CI claims name the specific failing job and first failing test.
+- [ ] No security-sensitive detail in a public comment — if any suspicion of a
vulnerability, route to <[email protected]> and stop the public triage.
+- [ ] Reviewer / triage tone is helpful and specific; the comment would read
fine to the reporter or PR author.
+- [ ] If AI tooling did substantive analysis, the *human* posting the comment
is the one making the call; the triage output is a draft for them to review.
+
+## References
+
+- [`GOVERNANCE.md`](../../../GOVERNANCE.md) — JIRA's role as the canonical
record; mailing list and Slack as the discussion channels.
+- [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) — commit-message JIRA
reference convention, regression-test requirement for JIRA-tracked fixes.
+- [`AGENTS.md`](../../../AGENTS.md) — ASF licensing / provenance,
`Assisted-by:` convention, and the "what *not* to do" list that drives most
PR-triage findings.
+- `.agents/skills/groovy-jira/SKILL.md` — JIRA mechanics (JQL, components,
field ownership, workflow-state rule); pair with this skill on every triage
pass.
+- `.agents/skills/groovy-tests/SKILL.md` — regression-test naming and
placement; pair with this skill when the triage produces a "needs regression
test" finding.
+- `.agents/skills/groovy-internals/SKILL.md` — hand off to this skill when
triage points at a compiler/runtime defect.
+- `.agents/skills/groovy-build/SKILL.md` — hand off when triage points at a
build / packaging defect.
+- `.agents/skills/groovysh/SKILL.md` — hand off when triage points at the REPL
subproject.
+- ASF Generative Tooling guidance:
<https://www.apache.org/legal/generative-tooling.html>.
diff --git a/AGENTS.md b/AGENTS.md
index a35f2094f5..4cd926df27 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -129,7 +129,9 @@ into the human-facing docs above.
|---|---|
| [`groovy-build`](.agents/skills/groovy-build/SKILL.md) | Gradle build
changes — convention plugins, build files, dependency verification, ASM/ANTLR
repackaging, OSGi, release pipeline |
| [`groovy-internals`](.agents/skills/groovy-internals/SKILL.md) | Compiler
and runtime work — parser, AST, type checker, transforms, class generation |
+| [`groovy-jira`](.agents/skills/groovy-jira/SKILL.md) | JIRA mechanics — JQL
recipes, `Component/s` taxonomy, field ownership, and the "don't transition
workflow states" rule for AI tooling |
| [`groovy-tests`](.agents/skills/groovy-tests/SKILL.md) | Adding or modifying
tests, including JIRA regression tests and executable AsciiDoc examples |
+| [`groovy-triage`](.agents/skills/groovy-triage/SKILL.md) | First-pass triage
of JIRA issues and GitHub PRs — reproducing reports against `master`, finding
duplicates, surfacing PR-readiness signals; advisory only, no committer actions
|
| [`groovysh`](.agents/skills/groovysh/SKILL.md) | Work in
`subprojects/groovy-groovysh/` — REPL commands, JLine integration, vendored
forks, terminal-aware test stack |
## Subproject guides
