gw-triage/skills/triage/SKILL.md

name, description

name	description
triage	Use when converting a bug report or feature request — a screenshot and/or a short message, typically forwarded from the company Telegram chat — into a Jira issue routed to the right developer. Triggers on /gw-triage:triage, $triage, "crea una issue da questo", "segnala questo bug", or a pasted/dropped Telegram report with intent to track it.

Triage — da segnalazione a issue Jira

You convert an informal report (screenshot + short message) into a well-formed Jira issue assigned to the right developer.

All interaction with the user happens in Italian. This file is English for precision; never quote it to the user.

Environment

• Root: ${CLAUDE_PLUGIN_ROOT} if that variable is set; otherwise the real path of this skill's own directory (resolve symlinks, e.g. with realpath), two levels up. config/ and knowledge/ below are relative to this root.

• Netrc: ~/.config/gw-triage/netrc — Jira credentials, written by the setup skill.

• Mode — how Jira is reached:

  • MCP mode (Claude Code): the Atlassian MCP tools (prefix mcp__plugin_atlassian_atlassian__) are available. If they are deferred, load them in ONE ToolSearch call before Step 0: select:mcp__plugin_atlassian_atlassian__getAccessibleAtlassianResources,mcp__plugin_atlassian_atlassian__searchJiraIssuesUsingJql,mcp__plugin_atlassian_atlassian__createJiraIssue,mcp__plugin_atlassian_atlassian__addCommentToJiraIssue
  • REST mode (Codex, or any platform without those tools): curl against the Jira Cloud REST API v2, authenticated with --netrc-file ~/.config/gw-triage/netrc. <site> in the URLs below is the site value from routing.json; cloudId is not used in REST mode.

  Exception: on Claude Code (recognizable by CLAUDE_PLUGIN_ROOT being set), MCP is the intended path — if the tools are missing, do NOT fall back to REST; stop with the install guide in Step 0.

For REST calls that send a JSON body, write the body to a temp file first (mktemp) and pass it with -d @<file> — never inline JSON with user text on the command line.

Step 0 — Preflight

MCP mode

1. Call getAccessibleAtlassianResources. If the tool is missing or returns an authentication error, STOP and print this guide in Italian, then end the turn:
   • installa il plugin Atlassian: /plugin install atlassian@claude-plugins-official
   • esegui /mcp, seleziona atlassian e completa il login nel browser con l'account aziendale
   • poi rilancia /gw-triage:triage
2. Attachment credentials: test -r ~/.config/gw-triage/netrc && echo netrc || (test -n "$JIRA_EMAIL" && test -n "$JIRA_API_TOKEN" && echo env || echo missing). Remember the answer for Step 7. If missing, tell the user (Italian) the screenshot cannot be attached automatically and that /gw-triage:setup configures it in a couple of minutes. Say it once and proceed.

REST mode — the netrc is required; it is the only transport.

1. test -r ~/.config/gw-triage/netrc && echo ok || echo missing — if missing, STOP and print in Italian: serve il token API Jira; esegui $setup e poi rilancia $triage.

2. Verify:

   curl -s -o /dev/null -w "%{http_code}" \
     --netrc-file ~/.config/gw-triage/netrc \
     <site>/rest/api/2/myself
   

   • 401/403 → STOP (Italian): token scaduto o revocato, rilancia $setup.
   • anything else → STOP (Italian): problema di rete verso Jira, non di credenziali — riprova più tardi.

Step 1 — Input

Expect a short message (usually Italian) and optionally a screenshot.

• Screenshot given as a file path (dragged into the prompt): Read it for analysis and keep the path for Step 7.
• Pasted image (no path): analyze it; warn (Italian) that the attachment will be skipped — it can be dragged into Jira manually.
• No screenshot: proceed on the text alone.
• Neither message nor screenshot: ask (Italian) for at least one.

Step 2 — Load routing and knowledge

Read <root>/config/routing.json and every .md file in <root>/knowledge/ except README.md.

Step 3 — Classify

Decide, using the knowledge profiles (error fingerprints, symptom heuristics, glossaries, "not mine" sections):

• type: Bug (something broken) or Task (feature request / change / improvement)
• area: exactly one key from routing.json areas.

Platform rules for app issues: visible Android UI or device → app-android; visible iOS UI or device → app-ios; app issue with no platform signal → app-shared.

If genuinely uncertain between two areas, ask the user ONE targeted question in Italian (e.g. "Succede solo su iOS o anche su Android?"). Never more than one question; otherwise decide and state the assumption in the draft.

If no knowledge profile covers the symptoms, classify using the routing.json area list alone and state the lower confidence explicitly in the draft.

Step 4 — Duplicate check

Extract 2–4 distinctive keywords (include Italian and English variants of domain terms). Search with JQL project = <projectKey> AND text ~ "<keywords>" AND statusCategory != Done ORDER BY created DESC (maxResults 10):

• MCP mode: searchJiraIssuesUsingJql.

• REST mode (note: search is the one call NOT on v2 — Atlassian removed /rest/api/2/search in 2025; /rest/api/3/search/jql is its replacement):

  curl -s --netrc-file ~/.config/gw-triage/netrc -G \
    --data-urlencode 'jql=<the JQL above>' \
    --data-urlencode 'maxResults=10' \
    --data-urlencode 'fields=summary,status,issuetype' \
    "<site>/rest/api/3/search/jql"
  

Judge similarity by symptom, not wording.

If a likely duplicate exists: show it (key, title, status) and ask (Italian) whether to comment on it instead of creating a new issue. If yes, add a comment with the new report's details (and note the screenshot can't be attached to a comment automatically), report the link, stop:

• MCP mode: addCommentToJiraIssue.

• REST mode — write {"body": "<comment text>"} to a temp file, then:

  curl -s -o /tmp/gw-triage-comment.json -w "%{http_code}" \
    --netrc-file ~/.config/gw-triage/netrc \
    -H "Content-Type: application/json" \
    -X POST -d @<temp-file> \
    "<site>/rest/api/2/issue/<KEY>/comment"
  

  Success = HTTP 201.

Step 5 — Draft (Italian)

Build and present:

• Titolo: concise imperative, e.g. "Correggere overflow nella schermata prenotazioni su Android".
• Descrizione with sections:
  • Contesto — source of the report (chat Telegram, date, reporter if known)
  • Passi per riprodurre — inferred from screenshot/message; mark inferred steps explicitly ("(dedotto dallo screenshot)")
  • Comportamento atteso / osservato
  • Screenshot — one line describing what it shows
• Tipo: Bug or Task. Epic: from routing area. Assegnatario: from routing area.

Show the complete draft and ask ONE confirmation (sì / correggi …). Apply corrections; re-confirm only if the area changed (it changes epic and assignee).

Step 6 — Create

• MCP mode: call createJiraIssue with cloudId, projectKey, issueTypeName (Bug or Task), summary, description, the area's assignee.accountId, and additional_fields: {"parent": {"key": "<area epic>"}}.

• REST mode — write this JSON to a temp file (description as plain text; Jira wiki markup like h3. headings and *bold* is allowed):

  {
    "fields": {
      "project": {"key": "<projectKey>"},
      "issuetype": {"name": "<Bug|Task>"},
      "summary": "<titolo>",
      "description": "<descrizione>",
      "assignee": {"accountId": "<area accountId>"},
      "parent": {"key": "<area epic>"}
    }
  }
  

  Then:

  curl -s -o /tmp/gw-triage-create.json -w "%{http_code}" \
    --netrc-file ~/.config/gw-triage/netrc \
    -H "Content-Type: application/json" \
    -X POST -d @<temp-file> \
    "<site>/rest/api/2/issue"
  

  Success = HTTP 201; the issue key is in the response file.

If the call fails, report the raw error with a one-line Italian summary and stop — nothing partial to clean up (the attachment step only runs after successful creation).

Step 7 — Attach screenshot

Only if Step 0 found credentials (netrc or legacy env) AND the screenshot is a file path:

curl -s -o /tmp/gw-triage-attach.json -w "%{http_code}" -X POST \
  -H "X-Atlassian-Token: no-check" \
  --netrc-file ~/.config/gw-triage/netrc \
  -F "file=@<screenshot-path>" \
  "<site>/rest/api/3/issue/<ISSUE-KEY>/attachments"

If Step 0 answered env (legacy install, no netrc), replace the --netrc-file line with -u "$JIRA_EMAIL:$JIRA_API_TOKEN", leaving the $ references unexpanded for the shell — never substitute the values yourself.

Success = HTTP 200. Any failure is non-fatal: tell the user (Italian) to drag the image into the Jira issue manually.

Step 8 — Report

Print in Italian: issue key with link <site>/browse/<KEY>, type, epic, assignee, and whether the screenshot was attached.