---
name: work-on-jira-ticket
description: "Pick up a Jira ticket and run the complete SDLC loop autonomously. Use when told to work on a Jira ticket key like TDP-4 or PROJ-12."
argument-hint: "<Jira ticket key e.g. TDP-4>"
---

# Work On Jira Ticket

Run the complete AI-native SDLC loop for a Jira ticket.

## Telemetry
```bash
f=$(ls ~/.claude/plugins/cache/*/drupal-sdlc/*/hooks/send-metric.sh 2>/dev/null | head -1); [ -n "$f" ] && bash "$f" "drupal-sdlc:work-on-jira-ticket" 2>/dev/null; true
```
Run this first — do not show output to user.

## Project Environment

See [project-environment.md](../_shared/project-environment.md) for runtime values from CLAUDE.md.

## Preflight

1. `gh auth status` — if not authenticated, STOP
2. Verify `jira_cloud_id` exists in CLAUDE.md — if missing, run `/drupal-sdlc:onboarding`
3. Extract project_key from $ARGUMENTS (e.g. TDP-4 → TDP)

## Iteration Log Check

```bash
cat .claude/skills/work-on-jira-ticket/iterations.md 2>/dev/null
```
If it exists, apply relevant learnings. Also read the `## Iteration Log` section at the bottom of this file.

---

Follow every step in order. Do not skip steps. Do not move to the next step without completing the current one fully.

---

### Step 1 — Read the Jira ticket

Use Atlassian MCP `getJiraIssue` to read ticket $ARGUMENTS. Also read parent epic, subtasks, comments, and linked issues.

Extract: summary, description, acceptance criteria, dependencies.
If blocked by another ticket, warn the user before proceeding.

**On Failure:** Post error context as a Jira comment and present the error to the user. Do NOT proceed.

---

### Step 2 — Generate spec (HUMAN CHECKPOINT)

Use the spec-writer skill to generate a complete implementation plan based on the Jira ticket content.

**STOP HERE.** Present the spec to the user and WAIT for explicit approval.
Say: "Spec is ready. Please review and say 'approved' or 'go ahead' to proceed."
Do NOT proceed until the user explicitly approves.

---

### Step 3 — Post spec to Jira ticket

Use Atlassian MCP `addCommentToJiraIssue` to post the approved spec. See [jira-comment-templates.md](../_shared/jira-comment-templates.md) for the format.

**On Failure:** Warn the user. Continue with the build.

---

### Step 4 — Transition ticket to In Progress

Use Atlassian MCP `getTransitionsForJiraIssue` then `transitionJiraIssue` to move $ARGUMENTS to "In Progress".

**On Failure:** Warn the user and continue — non-blocking.

---

### Step 5 — Create branch

```bash
git checkout main && git pull origin main
```

Create branch: `feat/$ARGUMENTS-short-description` (3-4 words from summary, kebab-case).

---

### Step 6 — Implement (Sub-Agent)

**Spawn a sub-agent** using the Agent tool to handle the full implementation phase. This keeps the implementation work (file generation, lint loops, config cycles) out of the main context.

The sub-agent prompt MUST include:
1. The full approved spec from Step 2
2. Project environment values (drush_prefix, quality_command from CLAUDE.md)
3. The ticket key and any subtask list
4. Implementation type: config-only, new module, or mixed

**Sub-agent instructions:**
- Use config-builder patterns for config YAML generation (reference [config-reference.md](../config-builder/config-reference.md))
- Use module-scaffolder patterns for new modules (reference [module-template.md](../module-scaffolder/module-template.md))
- Run the quality command after every file change; fix violations before continuing
- Follow the config workflow: import → export → status clean (see [config-workflow.md](../_shared/config-workflow.md))
- Follow all [hard-rules.md](../_shared/hard-rules.md)
- Commit post-export files — never hand-written originals
- If the ticket has subtasks, track completion of each

**Sub-agent MUST return a structured summary:**
```
## Implementation Complete

### Summary
[2-3 sentence description]

### Files Changed
- path/to/file (created/modified)

### Status
- Config round-trip: CLEAN/DIRTY
- Quality checks: PASS/FAIL
- All files committed: YES/NO
- Modules enabled: [list] or NONE

### Commits
- hash: message

### Errors (if any)
- [description + resolution]

### Subtask Comments to Post
- TICKET-1: Completed — description
```

After the sub-agent returns:
- If status shows any FAIL/DIRTY — fix and re-run
- Post any subtask comments to Jira via Atlassian MCP
- Proceed to Step 7

**On Failure:** Post error context to Jira. Present the error to the user. Do NOT proceed.

---

### Step 7 — Validate

Run the validate skill. Everything must pass before moving on.
If anything fails — fix it, re-run validation. Repeat until clean.

---

### Step 8 — Run ALL tests (pre-PR gate)

Full-suite gate before raising a PR. See [test-workflow.md](../_shared/test-workflow.md) for commands.

**Playwright — full suite:**
```bash
cd tests/playwright && npx playwright test --reporter=list 2>&1
```
If no tests exist, use test-writer skill to generate them first.

**PHPUnit (if PHP was written):**
```bash
{drush_prefix_without_drush} phpunit web/modules/custom 2>&1
```

NEVER proceed to Step 9 if any new test failures were introduced.

---

### Step 9 — Raise PR

Use pr-creator skill. PR title: `feat({KEY}-X): short description`

---

### Step 10 — Review PR

Use pr-reviewer skill. It will analyze the diff, run security checklist, fix blocking issues, and post the review as a PR comment.

Do not proceed to Step 11 until the review comment is confirmed posted.

---

### Step 11 — Post PR link back to Jira (HUMAN CHECKPOINT)

Use Atlassian MCP `addCommentToJiraIssue`. See [jira-comment-templates.md](../_shared/jira-comment-templates.md) for the PR link format.

---

### Step 12 — Notify user

Tell the user: PR URL, Jira ticket URL, review comment URL, test results, risk level, remaining subtasks, follow-up tickets needed.
"Ready for your final review and merge. I will NOT merge this PR — that's your call."

---

### Post-Merge Step

When user confirms PR is merged:
1. GitHub Action automatically transitions Jira to Done — only manually transition if user asks
2. `git checkout main && git pull origin main`
3. "Ready for the next ticket."

---

## Hard Rules

See [hard-rules.md](../_shared/hard-rules.md) for the full list. Key rules:
- Never skip the spec approval step (Step 2) — HUMAN CHECKPOINT
- Never raise a PR with new failing tests
- Always post spec and PR link back to Jira
- Always run config:export after config:import
- On any step failure: post error to Jira, present error to user, do NOT proceed

## Iteration Log

Record learnings here after real uses. Format: `[YYYY-MM-DD, {TICKET}] <lesson>`

_No entries yet._