jira-testing-release

What this skill does

# JIRA Testing Release — Scenario Generator

Generate a concise testing guide for a release version by combining Jira issue data with git diff analysis. Produces a table of what changed and what to verify — descriptive scenarios, not step-by-step scripts. Uses the `jira-fetch` script to pull all issue data via REST API in one call — no MCP overhead, no subagents, no token waste.

## Workflow

1. **Initial setup** — Ask language and branch configuration via `AskUserQuestion`
2. **Resolve JIRA project** — Get domain and project key from CLAUDE.md or ask user
3. **Fetch issue data** — Run `jira-fetch` script to get all issues for the version
4. **Analyze git diff** — Compare feature branch vs main branch to identify changed files
5. **Correlate and generate scenarios** — Match file changes to issues and produce testing scenarios
6. **Compose testing document** — Assemble the final table with optional risk sections
7. **Present draft for review** — Show the document and ask for confirmation
8. **Output** — Deliver as markdown

---

## Initial Setup (Step 1)

Use a single `AskUserQuestion` call with three questions:

- **Language** (header: "Language"): English (Recommended) | Spanish | Polish | German
- **Feature branch** (header: "Feature branch"): The branch containing release changes (default: `quality`). Pre-fill with current branch if it is not `master`/`main`.
- **Base branch** (header: "Base branch"): The branch to compare against (default: `master`)

If `$ARGUMENTS` contains a version number (e.g., `2.1.0`, `v3.0`), extract it for use in Step 3.

Use the selected language for the entire document. Translate section headers according to the translations in [references/format.md](references/format.md).

## Resolve JIRA Project (Step 2)

Look for a JIRA configuration block in the project's CLAUDE.md:

```
## JIRA
- Domain: mycompany.atlassian.net
- Project key: PROJ
```

If found, use that domain and project key. If not found, ask via `AskUserQuestion` (header: "JIRA Configuration"):
- Domain (e.g., mycompany.atlassian.net)
- Project key (e.g., PROJ)

Store the resolved `domain`, `projectKey`, and base URL (`https://{domain}`) for the rest of the session. The base URL is needed for clickable task links in the output.

---

## Fetch Issue Data (Step 3)

This single step replaces the old search + subagent extraction pattern. The `jira-fetch` script fetches all issues with full descriptions and comments in one call, returning a minimal JSON file with plaintext data ready for scenario generation.

### Locate Script

Find the fetch script via Glob:

```
pattern: **/jira-fetch/scripts/fetch-issues.mjs
```

### Determine Version and Fetch

**If a version was extracted from `$ARGUMENTS`**, run a targeted fetch:

```bash
node "${SCRIPT_PATH}" \
  --domain "${DOMAIN}" \
  --jql "project = ${PROJECT_KEY} AND fixVersion = \"${VERSION}\" ORDER BY priority DESC, issuetype ASC" \
  --output "/tmp/jira-testing-release-${VERSION}-$(date +%Y%m%d-%H%M%S).json"
```

**If no version was provided**, discover available versions first:

```bash
node "${SCRIPT_PATH}" \
  --domain "${DOMAIN}" \
  --jql "project = ${PROJECT_KEY} AND fixVersion IS NOT EMPTY ORDER BY fixVersion DESC" \
  --output "/tmp/jira-testing-versions-$(date +%Y%m%d-%H%M%S).json"
```

Read the JSON output and extract unique version names from the `fixVersions` field across all issues. Present discovered versions to the user via `AskUserQuestion` (header: "Version") as selectable options. Allow free text input for a version not in the list.

After the user selects a version, filter the already-fetched data to keep only issues where `fixVersions` includes the selected version. No second fetch needed — the discovery data already contains full issue details.

If the script fails, show the error and stop. Common issues: missing `JIRA_EMAIL` or `JIRA_API_TOKEN` env vars.

### Read and Parse

The JSON output contains per issue: `key`, `type`, `status`, `priority`, `assignee`, `reporter`, `labels`, `fixVersions`, `components`, `summary`, `created`, `updated`, `description` (plaintext), `comments[]` (with `author`, `created`, `body` as plaintext).

From the fetched (or filtered) data, collect for each issue: `key`, `summary`, `type`, `priority`, `status`, `labels`, `components`, `description`. Comments are available but not typically needed for testing scenarios — we care about what was built, not the discussion.

---

## Analyze Git Diff (Step 4)

Compare the feature branch against the base branch (from Step 1) to understand what code actually changed.

### 4a. Get Changed Files

Run:
```bash
git diff {baseBranch}...{featureBranch} --name-only
```

If the command fails (branches not found, not a git repo), skip git analysis entirely and generate scenarios from Jira data alone. Inform the user that git analysis was skipped.

### 4b. Get Change Statistics

Run:
```bash
git diff {baseBranch}...{featureBranch} --stat
```

This provides lines added/removed per file — useful for identifying high-change areas.

### 4c. Group Changed Files by Area

Classify each changed file into an area based on its path and extension:

| Path patterns | Area |
|---------------|------|
| `*/components/*`, `*/views/*`, `*/pages/*`, `*.vue`, `*.tsx`, `*.jsx`, `*.css`, `*.scss` | Frontend / UI |
| `*/api/*`, `*/controllers/*`, `*/routes/*`, `*/endpoints/*` | API |
| `*/services/*`, `*/models/*`, `*/repositories/*`, `*/domain/*` | Backend / Business Logic |
| `*/migrations/*`, `*.sql`, `*/schema/*` | Database |
| `*/tests/*`, `*/test/*`, `*spec*`, `*test*` | Tests |
| `*.config.*`, `*.yml`, `*.yaml`, `*.env*`, `Dockerfile`, `docker-compose*` | Configuration / Infrastructure |
| Everything else | Other |

### 4d. Identify High-Change Areas

Flag areas where:
- A single file has more than 100 lines changed
- A directory has more than 5 files changed
- New files were added (potential new features not yet tested)

These become candidates for the "High Risk Areas" section in the output.

---

## Correlate and Generate Scenarios (Step 5)

This is the core step — combine Jira data with git analysis to produce testing scenarios.

### 5a. Match Files to Issues

For each Jira issue, attempt to correlate with changed files using:
- Component names from Jira matching directory/file paths
- Keywords from the issue summary matching file names or paths
- Labels matching area classifications from Step 4c

This correlation is best-effort — not every issue will have a clear file match, and that is fine.

### 5b. Generate One Scenario Per Issue

For each issue, produce a testing scenario that answers: **"What changed and what should the tester verify?"**

Use the `description` field from the JSON data to understand what each task does and generate accurate testing scenarios. Having descriptions available directly (instead of summary alone) enables more precise and useful scenarios.

Scenario writing rules:
- **Descriptive, not procedural** — describe the function and what to check, not click-by-click steps
- **2-3 bullet points per scenario** covering: the main change, edge cases to watch for, and any integration points
- **Max 60 words per scenario** — concise enough to scan quickly
- **User-visible focus** — describe behavior from the end user's perspective
- **Include risk context** — if git diff shows many file changes for this issue, mention the breadth of impact

Examples of good scenarios:
- "Verify that the new date range filter on the orders page returns correct results. Check edge cases: empty date range, future dates, very old dates. Confirm that existing saved filters still work."
- "Check that the updated payment flow completes successfully for all payment methods. Verify error messages display correctly when payment fails. Test with both new and returning customers."

Examples of bad scenarios (too detailed / step-by-step):
- "1. Go to Orders page 2. Click the Date Filter dropdown 3. Select 'Custom Range' 4. Enter start date 01/01/2025 5. Ente