MaarkssDN/Birthub-360 / .agents/skills/bug-tracker-workflow
bug-tracker-workflow
VerifiedUse when defect counts or reports are wrong (missing top-severity bugs, fixed items counted as new, unmerged duplicates) or bug filing and transitions need automating. One workflow for Jira, Linear, GitHub Issues and Azure DevOps: dedupe before filing, severity vs priority, lifecycle and CI filing.
bug-tracker-workflow
Overview
Every mainstream tracker exposes the same four core operations - create, transition, search, and update/comment - behind a different API shape. This skill runs the bug workflow tracker-agnostically, with Jira Cloud REST API v3 worked in full below and per-platform deep dives in references:
| Tracker | API shape | Lifecycle model | Deep dive |
|---|---|---|---|
| Jira Cloud | REST v3, ADF rich text | Configurable workflow engine; look up transition IDs at runtime | Worked below + references/jira.md |
| Linear | GraphQL only | Per-team WorkflowState objects; resolve by type, not display name | references/linear.md |
| GitHub Issues | REST + Projects v2 GraphQL | Two states (open/closed) + state_reason; severity/priority via labels | references/github-issues.md |
| Azure DevOps | WIT REST 7.1, JSON Patch | Process-template states (Agile: New/Active/Resolved/Closed); WIQL search | references/azuredevops.md |
The tracker-agnostic rules that hold on all four platforms:
- Dedupe before create. CI bug filing must not duplicate when the same failure recurs: search open bugs by title/summary first, comment on the existing bug on a hit, and fail closed (skip the create, surface the error) if the search itself errors.
- Severity and priority are different axes - keep both fields and score them independently (references/severity-vs-priority.md).
- Never hard-code lifecycle identifiers. Jira transition IDs, Linear state names, and ADO state strings are all tenant/team/process-specific - discover them at runtime.
- Dry-run bulk operations. Bulk transitions are not trivially reversible; log the plan and verify counts before applying.
- Secrets in env vars / secret stores, never in code.
When to use
- Filing a bug from a CI test failure (fed by the from-CI-failure workflow
in
bug-report-template, qa-bug-repro). - Bulk-transitioning bugs after a release.
- Building a triage script that pulls new defects and applies severity / priority based on labels.
- Backing a duplicate-defect search backend.
Worked primary - Jira Cloud REST API v3
Jira's workflow engine maps cleanly to the canonical defect lifecycle (see references/lifecycle.md), but every project's actual workflow is configurable, so the runner looks up transition IDs at runtime rather than hard-coding them. All calls per developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/.
Authentication
Jira Cloud REST API v3 uses HTTP Basic auth with an API token:
export JIRA_BASE="https://your-tenant.atlassian.net"
export JIRA_EMAIL="you@company.com"
export JIRA_TOKEN="<api-token-from-id.atlassian.com>"
import requests, base64, os
auth = base64.b64encode(
f"{os.environ['JIRA_EMAIL']}:{os.environ['JIRA_TOKEN']}".encode()
).decode()
HEADERS = {
"Authorization": f"Basic {auth}",
"Accept": "application/json",
"Content-Type": "application/json",
}
BASE = os.environ["JIRA_BASE"]
Create a bug
POST /rest/api/3/issue. The description must be Atlassian Document
Format (ADF), not plain text.
def create_bug(project_key, summary, description_text, severity, priority, labels):
payload = {
"fields": {
"project": {"key": project_key},
"summary": summary,
"description": {
"type": "doc",
"version": 1,
"content": [{
"type": "paragraph",
"content": [{"type": "text", "text": description_text}],
}],
},
"issuetype": {"name": "Bug"},
"priority": {"name": priority}, # e.g. "High"
"labels": labels + [f"severity-{severity}"],
}
}
r = requests.post(f"{BASE}/rest/api/3/issue", json=payload, headers=HEADERS)
r.raise_for_status()
return r.json()["key"]
Note: severity is typically a custom field - most tenants either define a
custom Severity field (customfield_XXXXX) or use labels
(severity-critical). The example uses labels for portability; discovering
and submitting the custom field is in references/jira.md.
Look up and apply a transition
Workflow transitions are project-specific. Look up the available transitions then apply by transition ID:
def get_transitions(issue_key):
r = requests.get(f"{BASE}/rest/api/3/issue/{issue_key}/transitions",
headers=HEADERS)
r.raise_for_status()
return r.json()["transitions"]
def transition(issue_key, target_state_name):
transitions = get_transitions(issue_key)
match = next((t for t in transitions if t["name"] == target_state_name), None)
if not match:
raise ValueError(f"No transition named {target_state_name}; "
f"available: {[t['name'] for t in transitions]}")
r = requests.post(
f"{BASE}/rest/api/3/issue/{issue_key}/transitions",
json={"transition": {"id": match["id"]}},
headers=HEADERS,
)
r.raise_for_status()
The POST /rest/api/3/issue/{key}/transitions body shape is
{"transition": {"id": "<id>"}} per the API group docs.
Search via JQL
POST /rest/api/3/search/jql returns issues matching a JQL query. Useful
for duplicate detection and triage queues.
def search_jql(jql, max_results=50):
r = requests.post(
f"{BASE}/rest/api/3/search/jql",
json={"jql": jql, "fields": ["summary", "status", "priority"],
"maxResults": max_results},
headers=HEADERS,
)
r.raise_for_status()
return r.json()["issues"]
# Triage queue:
triage = search_jql(
'project = ENG AND issuetype = Bug AND status = "New" ORDER BY created ASC'
)
# Duplicate-candidate search:
dupes = search_jql(
f'project = ENG AND text ~ "{summary_safe}" AND issuetype = Bug'
)
Idempotent bug creation
def create_or_attach(project, summary, body):
existing = search_jql(
f'project = {project} AND summary ~ "\\"{summary}\\"" '
f'AND statusCategory != Done',
max_results=5,
)
if existing:
# Attach a comment to the existing bug instead of duplicating
key = existing[0]["key"]
add_comment(key, f"Recurred at {timestamp()}: {body[:500]}")
return key
return create_bug(project, summary, body, "Medium", "Medium",
labels=["auto-filed", "ci-failure"])
Verify: the statusCategory != Done search must run and return 0 open
matches before create_bug fires. If it returns a hit, comment on that key
instead of creating; if the search itself errors, fail closed (skip the
create and surface the error) rather than filing a possible duplicate.
Bulk transition after release
Dry-run first: a mis-scoped JQL can push hundreds of issues into the wrong state, and a transition is not trivially reversible. Gate the apply behind a flag:
DRY_RUN = True # flip to False only after reviewing the logged plan
verified = search_jql(
'project = ENG AND status = Verified AND fixVersion = "2026.05.20"',
max_results=1000,
)
for issue in verified:
if DRY_RUN:
print(f"[dry-run] {issue['key']}: Verified -> Close Issue")
continue
transition(issue["key"], "Close Issue")
Verify: assert the dry-run count and keys match the issue set you intended
to close before flipping DRY_RUN to False; if they do not, fix the JQL
and re-run the dry run. transition already raises ValueError when the
named transition is absent for an issue's workflow, so a workflow mismatch
fails loud rather than silently skipping.
CI integration
Auto-file a bug from a test failure:
# .github/workflows/test.yml (excerpt)
- name: Run tests
id: tests
run: pytest --junitxml=results.xml
continue-on-error: true
- name: File Jira bug on failure
if: steps.tests.outcome == 'failure'
env:
JIRA_BASE: ${{ secrets.JIRA_BASE }}
JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
JIRA_TOKEN: ${{ secrets.JIRA_TOKEN }}
run: python scripts/file-jira-bug.py results.xml
Where file-jira-bug.py parses the JUnit XML, extracts the failure,
deduplicates, and creates / comments per the helpers above.
Verify: assert the create call returned HTTP 2xx and a non-empty issue key
before the step reports success. On 400, the description was likely
plain text instead of ADF or a required field is missing - fix the payload
and re-run. On 429 (rate limit), back off and retry rather than failing
the build. If it still fails, leave the test result red so the filing gap
stays visible instead of being swallowed.
Other trackers
The same workflow shape on the other three platforms, each with its own auth, create, transition, search, worked example, anti-patterns, and CI wiring:
- Linear - references/linear.md: GraphQL-only
API;
issueCreate/issueUpdatemutations; per-teamworkflowStatesresolved by lifecycletype(never displayname); priority enum where 1 = Urgent; personal-key vs OAuth Bearer header difference. - GitHub Issues - references/github-issues.md:
two states only; the canonical-lifecycle-to-labels mapping;
state_reasontransitions (completed / not_planned / duplicate / reopened); Projects v2 GraphQL and the gh CLI. - Azure DevOps - references/azuredevops.md:
JSON Patch work-item mutations (
application/json-patch+json); WIQL triage / dedupe queries; process-template state names; optimistic concurrency viatest /rev; PR / build artifact links; az boards CLI.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Hard-coding transition IDs / state names | Workflow or process-template updates break the runner silently | Discover at runtime (Jira GET /transitions, Linear workflowStates by type, ADO process template) |
Plain-text description in Jira | API returns 400 - Jira v3 requires ADF | Wrap as {"type": "doc", "version": 1, "content": [...]} |
| No deduplication before create | Each retry of a flaky test creates a new bug | Search by summary first; comment on existing |
Severity as built-in priority | Conflates two axes (references/severity-vs-priority.md) | Use a custom Severity field or severity-* labels |
| Storing the API token in code | Token leak | Use environment variables / secret stores |
| Polling metadata endpoints on every call | Rate-limited | Cache per workflow scheme, refresh on 4xx |
| Bulk transitions without dry-run | Cannot easily reverse if wrong state | Always run in dry-run mode first; log all changes |
Limitations
- Workflow is per-project / per-team / per-process. A transition or state name in one project may not exist in another - handle "not found" gracefully on every platform.
- Custom fields are tenant-specific. Jira field IDs
(
customfield_10039) and ADO severity availability vary; discover at deploy time. - Rich text differs per platform. Jira needs full ADF; Linear takes Markdown; GitHub takes Markdown; ADO takes HTML. Test code-block / table rendering per platform.
- Rate limits everywhere. Jira per-minute, Linear ~1500 req/15 min, GitHub search 30 req/min unauthenticated, ADO per-user throttling - bulk operations need throttling and retry-with-backoff.
- Query injection. JQL
text ~, WIQLCONTAINS WORDS, and GitHub search all interpolate user text - escape quotes and reserved characters.
References
- Jira Cloud REST API v3 issues - developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/.
- Jira Cloud authentication - developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis.
- ADF spec - developer.atlassian.com/cloud/jira/platform/apis/document/structure.
- JQL syntax - confluence.atlassian.com/jiracoreserver/advanced-searching.
- Per-platform deep dives: references/jira.md, references/linear.md, references/github-issues.md, references/azuredevops.md - each carries its own platform-doc citations.
- Classification reference: references/severity-vs-priority.md (classification, lifecycle states, taxonomy).
- Fed by: the from-CI-failure spec workflow in
bug-report-template(qa-bug-repro). - Sibling-plugin neighbour:
test-management-sync(in the qa-test-reporting plugin) - different scope (test-result posting; not bug workflow).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |