AGENT SKILL

groovy-jira

暂无简介

License 许可
Apache-2.0
所属仓库
apache/groovy
最近更新
2026-11-15
Stars
★ 5.5k
Forks
1.9k

02 资源文件 4

03 SKILL.md 正文

<!-- 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-jira description: AI-tooling guardrails for working with JIRA on the GROOVY project — points at the project's JIRA conventions in CONTRIBUTING.md (states, fields, components, JQL recipes, the commit ↔ JIRA link), and adds the AI-specific constraints on top: never propose a workflow transition, never set committer-owned fields, never post comments or open formal issue links autonomously, refetch live state rather than citing trained memory, hand drafts back to a human for review. Use when constructing a JQL query, suggesting a Component, drafting a JIRA comment, or producing any AI output that touches JIRA. license: Apache-2.0 compatibility: claude, codex, copilot, cursor, gemini, aider metadata: audience: contributors to apache/groovy scope: ai-tooling-jira-guardrails

Groovy JIRA

This skill is the AI-tooling layer over the project's JIRA conventions. The conventions themselves — states, fields, components, JQL recipes, the commit ↔ JIRA link — live in CONTRIBUTING.md's "Working with JIRA" section. This skill cites them and adds the AI-specific guardrails: no autonomous comments, no proposed transitions, no fabricated field values, no trained-memory citations of live state. The output is a draft a human committer reviews and posts.

  • groovy-triage — sister skill that drives a full triage pass; pair with this one.
  • groovy-fix-workflow — hand off to once a triage finding becomes a fix in flight.
  • CONTRIBUTING.md — the canonical source for every JIRA convention this skill cites; load alongside this skill.

When to use this skill

Use it for:

  • Drafting JIRA-related output (comments, field suggestions, query results) that a human will review before posting.
  • Constructing a JQL query for grooming, duplicate hunting, release-notes mining, or a triage pass.
  • Suggesting a Component/s value or interpreting one already set.
  • Producing or reading a GROOVY-NNNNN reference in a commit, branch name, or comment.

Don't use it for:

  • Posting to JIRA on the project's behalf, transitioning workflow state, setting committer-owned fields, or opening formal issue links. The hand-back contract (below) is firm.
  • Triage workflow itself (reproducing, drafting findings, PR-readiness checks) — that's groovy-triage.
  • Security-sensitive issues. Suspected vulnerabilities are reported privately per SECURITY.md, not into JIRA or a public comment. If a public JIRA appears to disclose a vulnerability, flag privately to a committer and stop.
  • Workflow administration (creating versions, renaming components, editing the workflow itself) — that's a project-admin action.

Read first

  • CONTRIBUTING.md "Working with JIRA" — fields, states, components, JQL recipes, commit-reference convention. The canonical source for everything below; the skill restates only what AI tooling specifically needs.
  • GOVERNANCE.md — JIRA's role as the project's canonical record.
  • Live JIRA project page: https://issues.apache.org/jira/projects/GROOVY — components, versions, and the workflow are configured there, not in this repo.

Top failure modes

These are the recurring mistakes when AI tooling reaches for JIRA:

  1. Proposing a workflow transition. State changes are committer actions tied to actual code shipping. AI tooling never recommends or performs a transition — surface a recommendation in a comment instead: "appears fixed on master at <rev> — proposing a committer close this as Cannot Reproduce after a second look." The contributor norm is "comment, don't transition" (see CONTRIBUTING.md); for AI tooling it tightens to "never."

  2. Setting or proposing a committer-owned field. Fix Version/s, Resolution, and Priority are committer territory; AI tooling does not propose values for them. Affects Version/s is the reporter's domain; ask if missing, don't fabricate. Component/s AI may suggest — but only from a real area of the codebase, not a plausible-sounding name. See the field-ownership table in CONTRIBUTING.md for who sets what.

  3. Fabricating a Component. AI tooling reaches for plausible-sounding component names that aren't in the live list. Refetch the components page rather than guessing. If the bug doesn't map cleanly to an existing component, say so in the comment — don't manufacture one.

  4. Posting a comment, link, or assignment without explicit instruction. Even when the draft is clean and the recommendation obvious, AI tooling produces drafts; humans post. Formal "Linked Issues" relationships are committer territory regardless; AI cross-references stay in comment text only.

  5. Quoting a stale JIRA snapshot. Trained memory and cached search results lag the live project. For decisions that hinge on current state (open vs. closed, latest comment, current Fix Version/s on a related issue), refetch — don't cite from memory. This bites AI tooling harder than humans, because humans typically load JIRA in a browser before commenting.

  6. JQL that drops project = GROOVY or mis-quotes values. The contributor rules (lead with project = GROOVY, quote multi-word values, use in for multi-value fields) are in CONTRIBUTING.md — AI output is held to them too. A query that's "right in principle but produces cross-project noise" is wrong output.

  7. Bare or malformed JIRA references in drafted output. Commits, comments, and branch names use GROOVY-NNNNN — uppercase, no brackets, no prefix. Drafts that emit #12345, JIRA-12345, or lowercase groovy-12345 break the search-by-grep workflow contributors and tooling rely on.

Helper scripts

Three vetted helpers ship in this skill's directory so the agent does not re-derive the ASF JIRA REST calls on every run — per the Helper mechanisms and token economy policy (the JIRA REST v2 API is stable and these change rarely; the curl + jq inside each script is the documented manual equivalent if you need to adapt it):

  • jira-search.sh — jira-search.sh '<JQL>' [max] → tab-separated candidate list (key, dates, type, attachment count, components, summary). Use for the candidate-set selection in groovy-reassess and the duplicate / related-issue scans in triage.
  • jira-issue.sh — jira-issue.sh GROOVY-NNNNN [out-dir] → issue.json + a rendered description.md (fields, description, every comment), and lists attachment URLs for manual download.
  • jira-recent.sh — jira-recent.sh [days] → unresolved issues updated in the last days (default 30), each linked to the GitHub PRs whose title names its key, grouped as merged-PR-but-still-open / open PR / no open PR, plus open PRs in the window naming none of the listed issues. The merged group also shows each issue's affects versions and which of GROOVY_4_0_X, GROOVY_5_1_X, GROOVY_6_0_X and master mention its key (read from the local remote-tracking refs, so git fetch first). Needs an authenticated gh and a clone of the repo in addition to curl and jq.
  • pr-shortlist.sh — pr-shortlist.sh [max-size] → open GitHub PRs grouped by how close they are to merging: approved / approved-but-pushed-since / small and waiting for a reviewer (yours vs. others') / open discussion / CI failing or pending / larger than max-size lines (default 600); drafts and conflicting PRs are only counted. Each row's since-commit: column names who has commented since the PR's last commit (author and automated accounts left out; (replied) when the author answered after them). Use it to pick which PRs to progress next. Needs an authenticated gh and jq (no JIRA call).

All are read-only (no mutation, and anonymous against JIRA) — they do not change the read-only / hand-back posture this skill enforces. Prefer them over an ad-hoc curl; fall back to the inline command only if a script is unavailable or the query needs a field they don't request.

Drafting a JIRA comment

When the task is to produce a JIRA comment a human will review and post:

  1. Refetch live state for any factual claim. The issue's current status, the latest comments, the Component/s and Fix Version/s fields, related issues — pull from the live JIRA, not from training memory or stale cache.
  2. Use plain GROOVY-NNNNN for any cross-reference; let JIRA auto-link.
  3. Surface recommendations, not directives. "Looks fixed on master at <rev> — may be a candidate for closing as Cannot Reproduce" reads as a recommendation; "Closing this as Cannot Reproduce" reads as an action. The committer makes the call.
  4. Cite evidence. A reproduction outcome on master cites the revision and JDK (see groovy-reproducer); a duplicate citation names the linked JIRA; a Component/s suggestion names the package path it derives from.
  5. No security-sensitive content in a public JIRA comment. Vulnerabilities are reported privately per SECURITY.md.
  6. Stop at the draft. Output is text for a human to review and post. The human assesses tone, accuracy, and timing.

Hand-back contract

AI tooling working with JIRA produces drafts; it does not act on JIRA. Specifically, AI tooling does not:

  • Post comments to JIRA.
  • Transition workflow state (any of Open / In Progress / Resolved / Closed / Reopened).
  • Set or change any field (Fix Version/s, Resolution, Priority, Component/s, Affects Version/s, Assignee, Labels, Summary, Description).
  • Create formal "Linked Issues" relationships.
  • Assign issues to anyone, including the user.

With explicit instruction, AI tooling may:

  • Produce a draft comment, draft Component/s suggestion, or draft cross-reference for the human to post.
  • Run a JQL query and return the result set (read-only).
  • Cite a GROOVY-NNNNN in a commit message or branch name the human is authoring.

The committer / contributor decides what gets posted and when.

Validation checklist

Before declaring a JIRA-related output ready for human review:

  • [ ] No proposed workflow transition; recommendations only.
  • [ ] No proposed Fix Version/s, Resolution, or Priority.
  • [ ] Any suggested Component/s maps to a real area of the codebase and matches a component on the live list (refetched, not from memory).
  • [ ] Any Affects Version/s ask routes back to the reporter; no fabricated value.
  • [ ] If the output relies on issue state: refetched from the live JIRA in this session, not cited from memory.
  • [ ] Any JIRA reference uses the full GROOVY-NNNNN key (uppercase, no brackets, no prefix).
  • [ ] Any JQL leads with project = GROOVY, quotes multi-word values, and uses the right operator for multi-value fields.
  • [ ] No security-sensitive content in a draft destined for a public comment.
  • [ ] The output is a draft for a human to review and post — not a payload to be sent automatically.

References

  • CONTRIBUTING.md "Working with JIRA" — the canonical source for every convention restated above (states, fields, components, JQL recipes, commit references). Update this skill if a divergence appears.
  • GOVERNANCE.md — JIRA as the project's canonical record.
  • .agents/skills/groovy-triage/SKILL.md — sister skill; drives a full triage pass and defers to this skill for the AI-specific JIRA bits.
  • .agents/skills/groovy-fix-workflow/SKILL.md — hand off to once a triage finding becomes a fix in flight.
  • Live JIRA project: https://issues.apache.org/jira/projects/GROOVY — components, versions, workflow.

04 同仓库更多 Skills