221 lines
8.9 KiB
Markdown
221 lines
8.9 KiB
Markdown
---
|
||
name: triage
|
||
description: 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
|
||
|
||
Anything but `200` → STOP (Italian): token scaduto o revocato,
|
||
rilancia `$setup`.
|
||
|
||
## 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.
|