AGENT SKILL

triage-issue

Triage a bug against Jira with atl before proposing a ticket. USE WHEN an error or stack trace comes with duplicate, prior-fix, or file-a-bug intent. DO NOT USE WHEN debugging code only, inspecting a known issue, or creating an ordinary task.

License 许可
Apache-2.0
所属仓库
isukharev/atl
最近更新
2026-09-14
Stars
★ 7
Forks
1

01 前言 Front Matter

name
triage-issue
description
Triage a bug against Jira with atl before proposing a ticket. USE WHEN an error or stack trace comes with duplicate, prior-fix, or file-a-bug intent. DO NOT USE WHEN debugging code only, inspecting a known issue, or creating an ordinary task.

03 SKILL.md 正文

<!-- Generated from skills-src/triage-issue/SKILL.md — edit the source and run 'make gen-plugins'. -->

Triage an issue with atl

Find duplicates before filing. Never create a ticket without first showing the user what already exists. Command details live in the jira skill.

Preflight: atl must be installed and configured. If command -v atl fails or a command exits 7 ("not configured"), run /atl:setup and stop.

Workflow

1. Extract the error signature

From the report, pull: the exception/error type, the failing class/function/endpoint, and the stable message words. Strip volatile parts — ids, timestamps, hostnames, line numbers — they poison text search. Build 2–3 query variants from specific to broad.

2. Search for duplicates (parallel, one message)

<!-- atl:read-only-shell -->

export ATL_READ_ONLY=1
atl jira issue search \
  --jql 'project = KEY AND text ~ "NullPointerException PaymentProcessor" AND type = Bug ORDER BY created DESC' \
  --limit 10 --columns key,summary,status,issuetype,updated
atl jira issue search \
  --jql 'project = KEY AND summary ~ "timeout checkout" ORDER BY updated DESC' \
  --limit 10 --columns key,summary,status,issuetype,updated

Useful refinements:

  • recent recurrence: AND created >= -30d
  • fixed before (regression check): AND status in (Done, Closed, Resolved) ORDER BY resolutiondate DESC
  • open neighbours: AND status not in (Done, Closed) AND component = "X"
  • Quote multi-word phrases inside text ~ "..."; JQL reserved words must be quoted too.

3. Classify and present — no writes yet

Compare promising hits before proposing any write:

<!-- atl:read-only-shell -->

export ATL_READ_ONLY=1
atl jira issue get KEY-123 \
  --fields summary,status,issuetype,description,labels,components,updated,resolution

Keep the search page qualification and compare only the fields required by the duplicate rule. A plausible positive hit can be inspected immediately, and only a confirmed open-duplicate/comment path may stop early. Before either create path—Regression or New—resume every search with its exact page.next_cursor until page.complete:true. If any search stays truncated or incomplete, report that duplicate absence is unproven and do not propose or create a new issue. Fetch comments separately only after an open duplicate is selected; do not pull comments or attachments into every candidate read.

For a closed candidate that may prove a regression, add one compact temporal check only after selecting it:

<!-- atl:read-only-shell -->

export ATL_READ_ONLY=1
atl jira issue history KEY-123 --field status --summary-only

Require complete:true and use last_changes; do not classify a regression from the current resolution alone or fetch raw history rows when the summary is sufficient.

Then tell the user which case this is and what you propose:

  • Duplicate (open) → offer to add a comment with the new occurrence and any new context.
  • Regression (was fixed) → offer a new bug linked to the old one (atl jira link-types lists the instance's link names).
  • New → offer to create a ticket.

Stop and wait for the user's choice.

4a. Comment on an existing issue

printf '%s' "$BODY_MD" | ATL_READ_ONLY=1 atl jira issue comment preview KEY-123 --from-md -
# After explicit approval, repeat the exact body once with:
printf '%s' "$BODY_MD" | env -u ATL_READ_ONLY atl jira issue comment add KEY-123 \
  --from-md - --apply --expected-proposal-hash '<reviewed-hash>'

4b. Create a new bug

Compose the description in markdown — Summary / Steps to reproduce / Expected / Actual / Environment / error excerpt in a code fence / links to similar issues — then:

atl jira issue create preview --project KEY --type Bug --summary '<Component>: <symptom> <condition>' --from-md desc.md
# After explicit review, repeat the exact parent command with the reviewed hash:
atl jira issue create --project KEY --type Bug --summary '<Component>: <symptom> <condition>' \
  --from-md desc.md --apply --expected-proposal-hash '<reviewed hash>'
ATL_READ_ONLY=1 atl jira issue link add preview NEW-1 --to OLD-9 --type Relates
# After explicit review, repeat without ATL_READ_ONLY and add --apply plus the proposal hash.

Title formula: component + observable symptom + triggering condition — not the raw exception line.

5. Report back

Return the created/updated key, what was linked, and the duplicate-search queries you ran, so a human can re-check the negative result.

Pitfalls

Symptom Cause / fix
exit 8 on create --from-md a markdown construct isn't convertible — the error names it; simplify that block
link add rejected link type names are instance-specific — check atl jira link-types first
assignee rejected Server/DC takes a username: find it with atl jira user search '<name>', set via --field 'assignee={"name":"<username>"}'
text ~ too noisy add type = Bug, a component, or created >= -90d

04 同仓库更多 Skills

isukharev
isukharev/atl

status-report

Draft an audience-oriented Jira status report with atl. USE WHEN the user wants a weekly/daily progress narrative, blocker summary, or period report. DO NOT USE WHEN the output is a visual dashboard, direct Jira query, knowledge search, or codebase summary.

★ 7
isukharev
isukharev/atl

sprint-dashboard

Build a visual read-only Jira sprint or board dashboard with atl. USE WHEN the user wants a standup view, WIP picture, or sprint snapshot. DO NOT USE WHEN the output is a narrative report, raw Jira list, or codebase dashboard.

★ 7
isukharev
isukharev/atl

spec-to-backlog

Convert a specification into a reviewed Jira epic and backlog with atl. USE WHEN decomposing requirements, RFCs, or designs into linked Jira work. DO NOT USE WHEN the source is meeting notes, only a summary is wanted, or the task is a direct service operation.

★ 7
isukharev
isukharev/atl

setup

Install and configure atl authentication, backends, and mirror defaults. USE WHEN the user explicitly requests install, authentication, setup repair, or /atl:setup. DO NOT USE WHEN handling normal Jira, Confluence, search, reporting, or mirror work; explicit-only.

★ 7
isukharev
isukharev/atl

search-knowledge

Answer from qualified Jira and Confluence evidence with atl. USE WHEN organizational knowledge is unknown or split across both services. DO NOT USE WHEN one exact resource is known, the task is a report/dashboard, or the answer belongs in the codebase.

★ 7
isukharev
isukharev/atl

onboarding

Build a reviewed private atl workflow profile from approved Jira/Confluence samples. USE WHEN the user explicitly asks to onboard, personalize atl, or refresh saved preferences. DO NOT USE WHEN handling ordinary service, search, report, or setup work; explicit-only.

★ 7