---
name: fix-jira-ticket
description: Fetch a Jira ticket with the `jira` CLI and implement the fix end to end. Use when the user says "fix <jira-url>", "fix TK-NN", or references a https://yg-hpw.atlassian.net/browse/TK-NN link and wants it worked.
---

# Fix Jira Ticket

Turn a Jira ticket reference into a completed, verified code change in the Traditional Knowledge repo.

## Instructions

### Step 1: Create a branch
Create and check out a working branch for the ticket:

```bash
dev branch-from <jira ticket link>
```

This derives the branch name from the ticket (see the branch-name note below).

### Step 2: Resolve the issue key
Accept either a full URL (`https://yg-hpw.atlassian.net/browse/TK-61`) or a bare key (`TK-61`).
Extract the key with the pattern `[A-Z]+-\d+`. Everything below uses `<KEY>`.

### Step 3: Fetch the ticket
Read the full ticket including comments — comments often carry the final approved wording or scope changes:

```bash
jira issue view <KEY> --comments 10 --plain
```

- The CLI is already authenticated (`~/.config/.jira/.config.yml`). No token setup needed.
- For machine-readable fields (status, assignee, links, attachments) use `jira issue view <KEY> --raw` and parse the JSON.
- Read the **Acceptance criteria** and the **latest comments** carefully. When a comment supersedes the description (e.g. "NEW APPROVED terminology is…"), the comment wins.

### Step 4: Claim the ticket
Assign the ticket to yourself and move it to **In Progress** before starting work:

```bash
jira issue assign <KEY> $(jira me)
jira issue move <KEY> "In Progress"
```

### Step 5: Plan the change
- Identify exact acceptance criteria as a checklist.
- Locate the affected code by searching for the **behavior or string**, not a guessed variable name (e.g. grep the literal label text, not a component name).
- Follow repo conventions in `AGENTS.md` and the nearest `README.md` / `agents/` workflow.

### Step 6: Implement
- Make the smallest change that satisfies every acceptance criterion.
- Migrate all call sites; no shims or partial edits.
- No `any`, `@ts-ignore`, or abbreviations (per repo pre-submission checklist).

### Step 7: Verify
- Run the specific tests/lint for the touched area:
  `dev test api` / `dev test web`, `dev api npm run lint` / `dev web npm run lint`.
- For UI/text changes, confirm the actual rendered surface.

### Step 8: Report
Summarize per acceptance criterion: what changed, where (file:symbol), and the verification evidence. Do not update the Jira ticket status unless the user asks.

## Notes
- Branch name: Step 1's `dev branch-from <url>` derives the name via `JiraApi.build_branch_name`, which needs `JIRA_USERNAME`/`JIRA_API_TOKEN` env vars set (the `jira` CLI does not). To preview the name only: `ruby -r./bin/jira_api -e 'puts JiraApi.build_branch_name("<URL>")'`.
- If the ticket is ambiguous or blocked on a decision, state exactly what's missing rather than guessing at requirements.