Imported from EricTechPro/startup-claude-skills (skills/fix-ticket/SKILL.md). Install upstream with npx skills add EricTechPro/startup-claude-skills --skill fix-ticket. Copyright stays with the author.

Fix Ticket

Automate the full lifecycle of a Jira bug ticket: read the ticket, implement the fix, review changes, commit, transition to QA, assign to QA engineer, and comment with a summary. Zero-touch pipeline from ticket to QA handoff.

Prerequisites

Read CONFIG.md at the start of every run. This file contains project-specific settings (Jira project key, team members, transition IDs, deployment config, QA credentials). If CONFIG.md doesn't exist, warn the user and point them to CONFIG.template.md.

When to Use

• User passes a Jira ticket ID (e.g., PROJ-123) and wants it fixed end-to-end
• User says "fix this ticket", "resolve this bug", "fix and ship PROJ-XXX"
• Any bug ticket that needs the full fix-review-commit-handoff cycle

Parameters

Invocation

/fix-ticket PROJ-123                       # asks branch strategy first (default)
/fix-ticket PROJ-123 branch=main          # urgent fix, commit directly to main
/fix-ticket PROJ-123 branch=new           # create fix/PROJ-123 branch
/fix-ticket PROJ-123 branch=worktree      # isolated worktree (great for parallel runs)
/fix-ticket PROJ-123 skip-review=true
/fix-ticket PROJ-123 skip-jira=true
/fix-ticket PROJ-123 skip-deploy=true
/fix-ticket PROJ-123 skip-verify=true
/fix-ticket PROJ-123 skip-qa-check=true

Architecture

ORCHESTRATOR (main session)
|
+-- Phase 0: BRANCH STRATEGY (runs FIRST — before any code work)
|   If branch=ask (default): prompt user with 3 options:
|     1. Main branch — commit directly (fast, for simple/urgent fixes)
|     2. Separate branch — create fix/{TICKET-ID} branch (for PR workflow)
|     3. Worktree — isolated worktree (for running parallel fix-tickets)
|   If branch=worktree: call EnterWorktree, symlink .env.local + node_modules
|   If branch=new: create fix/{TICKET-ID} branch
|   If branch=main: stay on current branch
|
+-- Phase 1: READ TICKET
|   Jira MCP -> ticket details, comments, acceptance criteria
|
+-- Phase 1.5: QA VERIFY <- headless browser bug reproduction (unless skip-verify=true)
|   Start dev server if needed, provision test user, login via browser
|   Reproduce the bug steps from the ticket in headless Chrome
|   Screenshot evidence, generate inline verdict
|   If not reproducible -> ask user whether to continue
|   -> Read references/qa-integration.md for full steps
|
+-- Phase 2: RESEARCH & UNDERSTAND <- MANDATORY + USER GATE
|   Research the bug (Explore agent or direct search)
|   Budget: ~10 tool calls, target root cause in <60s
|   Present findings to user (include QA verify evidence if available)
|   STOP — ask user "Does this look right?" — do NOT continue until they respond
|
+-- Phase 3: ANALYZE & PLAN
|   Classify complexity using thresholds below
|   For complex fixes: use delegation skill from CONFIG.md (if configured)
|   For simple fixes: plan and proceed
|
+-- Phase 4: IMPLEMENT
|   Apply the fix (direct edit or delegated)
|   Run build + lint to verify
|
+-- Phase 5: REVIEW <- MANDATORY (unless skip-review=true or delegation used)
|   Pick 3-5 agents from pool based on what the diff touches
|   Large/risky fixes (5+ files, DB, auth): escalate to full review team
|   If critical/high findings: fix -> re-review (max 2 cycles)
|   NEVER skip review because "change looks trivial"
|
+-- Phase 5.5: QA CHECK <- headless browser fix verification (unless skip-qa-check=true)
|   Re-provision test user, re-run same steps as Phase 1.5
|   Verify the bug is resolved — expected behavior now works
|   If fix incomplete -> loop back to Phase 4 (max 1 retry)
|   -> Read references/qa-integration.md for full steps
|
+-- Phase 6: COMMIT & PUSH <- BOTH REQUIRED
|   Branch strategy: ask user, main, or new fix branch
|   Handle remote-ahead: stash -> pull --rebase -> stash pop -> push
|   git push to remote — local-only commit = incomplete
|
+-- Phase 6.5: WORKTREE MERGE (if branch=worktree, runs AFTER Phase 7)
|   Merge worktree branch into main, push, clean up worktree + branch
|   Must use absolute paths (Bash tool resets cwd after cd)
|
+-- Phase 7: DEPLOYMENT MONITOR
|   Poll deployment platform until build succeeds
|   If Ready: proceed to Phase 6.5 merge (if worktree), then Phase 8
|   If Error: read logs, fix, re-commit, re-push, re-monitor (max 2 retries)
|
+-- Phase 8: JIRA HANDOFF (unless skip-jira=true)
|   Smart transition: QA (clean) / In Review (unresolved) / Done (trivial+skip-review)
|   Assign to QA engineer
|   Post comment: what was fixed, commit hash, QA steps, review findings
|   If ticket has existing comments: respond contextually
|
+-- Phase 9: SUMMARY
|   Report to user: what was done, commit hash, deployment status, Jira link

Phase Execution Order — STRICT SEQUENTIAL

You MUST execute phases 0 -> 1 -> 1.5 -> 2 -> 3 -> 4 -> 5 -> 5.5 -> 6 -> 7 -> 6.5 -> 8 -> 9 in order. Do NOT skip or reorder phases. (Phase 0 always runs — it asks the user their branch preference when branch=ask (default), or sets up worktree when branch=worktree. Phase 1.5 skips when skip-verify=true. Phase 5.5 skips when skip-qa-check=true. Phase 6.5 only runs when worktree was chosen — it merges the worktree branch into main AFTER deployment succeeds.)

Parameter Gate — How to Check Skip Flags

Before each skippable phase, perform this literal check on the invocation arguments:

Phase 1.5: Was `skip-verify=true` in the user's invocation? YES -> skip. NO -> run it.
Phase 5:   Was `skip-review=true` in the user's invocation? YES -> skip. NO -> run it.
Phase 5.5: Was `skip-qa-check=true` in the user's invocation? YES -> skip. NO -> run it.
Phase 7:   Was `skip-deploy=true` in the user's invocation? YES -> skip. NO -> run it.

Do NOT invent reasons to skip. The parameter either exists or it doesn't. If it doesn't exist, the phase is mandatory regardless of what the bug is about.

Phases That Get Skipped (and Why That's Wrong)

Every rationalization below has been observed in real runs and is INVALID:

• Phase 1.5 (QA Verify): "I'll research first then verify" — NO. "I'll verify in Phase 5.5 instead" — NO. "This is a navigation/routing bug" — navigation bugs are EXACTLY what browser testing catches. "Requires specific test data" — provision the data.
• Phase 5.5 (QA Check): "This is a straightforward URL param change verified by build + review" — NO. Build + review verify code correctness; browser testing verifies user-facing behavior. Different things. "skip-qa-check" — check the invocation: was this parameter actually passed?
• Phase 5 (Review): "Change is too small" — small changes with subtle bugs are the hardest to catch yourself.
• Phase 7 (Deploy Monitor): A broken build = QA can't test.

When announcing each phase, use the exact header: Phase {N}: {Name} so the user can track progress.

Context Budget Awareness

This pipeline typically uses 120-180k tokens across all phases. The biggest budget risks:

If context usage exceeds 60% before Phase 6, switch to minimal output mode: shorter build output, no verbose commentary, brief review summaries.

Mandatory Checklist (before reporting summary)

Before moving to Phase 9, verify ALL of these are done:

• Branch strategy resolved: User was asked (or explicit param used) — strategy stored for Phase 6
• QA verify ran: Bug reproduced in headless browser (or skip-verify=true)
• Research done: Bug was investigated AND user acknowledged findings with diagram
• Review ran: 3 agents were spawned (or skip-review=true was explicitly set)
• Critical/high findings fixed: All critical and high review findings addressed
• QA check ran: Fix verified in headless browser (or skip-qa-check=true)
• Committed: Changes committed with conventional commit message
• Pushed: git push executed and confirmed — local-only commits are NOT complete
• Deployed: Deployment platform checked and status confirmed
• Worktree merged: If branch=worktree, worktree merged to main, pushed, and cleaned up
• Jira updated: Ticket transitioned, assigned, and commented (or skip-jira=true)

If any item is missing, go back and complete it before proceeding to Phase 9.

Workflow

Phase 0: Branch Strategy

This phase ALWAYS runs first — before reading the ticket or doing any work.

First: Read CONFIG.md to load project-specific settings (team members, Jira transitions, deployment config, QA credentials). If not found, warn user and point to CONFIG.template.md.

If the branch parameter was explicitly set (main, new, or worktree), use that value. Otherwise (default ask), prompt the user:

Before I start, how would you like to handle the branch for this fix?

1. **Main branch** — commit directly to main (fast, for simple/urgent fixes)
2. **Separate branch** — create a `fix/{TICKET-ID}` branch (for PR workflow)
3. **Worktree** — isolated worktree (for running parallel fix-tickets)

STOP — wait for the user's response before proceeding.

Once the branch strategy is determined:

Store the resolved branch strategy — Phase 6 and Phase 6.5 need it for commit/push/merge logic.

Phase 1: Read Ticket

Fetch the Jira ticket details using MCP:

mcp__jira__jira_get:
  path: /rest/api/3/issue/{ticketId}
  jq: "{key: key, summary: fields.summary, description: fields.description, status: fields.status.name, assignee: fields.assignee.displayName, priority: fields.priority.name}"

Also fetch comments to understand any ongoing conversation:

mcp__jira__jira_get:
  path: /rest/api/3/issue/{ticketId}/comment
  jq: "comments[*].{author: author.displayName, body: body, created: created}"

Fetch acceptance criteria if available (field ID from CONFIG.md):

mcp__jira__jira_get:
  path: /rest/api/3/issue/{ticketId}
  jq: "fields.{acceptance_criteria_field}"

Extract:

• Summary: What the bug is
• Description: Full context, repro steps, expected behavior
• Acceptance criteria: What "fixed" looks like
• Comments: Any discussion, additional context, or previous attempts
• Priority: Helps determine fix urgency

If the Jira fetch fails, ask the user to describe the bug manually and continue.

Phase 1.5: QA Verify (Headless Browser Bug Reproduction)

Skip if skip-verify=true. Also skip if the QA tool (from CONFIG.md) is not installed — warn user and continue.

Phase 1.5 runs BEFORE Phase 2 research. Do NOT skip it to "research first". The browser evidence from Phase 1.5 directly informs Phase 2 research — seeing the actual bug behavior in a browser is more valuable than reading code first.

Read references/qa-integration.md for the full provisioning, login, and interaction steps.

Steps

1. Start dev server if not running (command and port from CONFIG.md):

   lsof -ti:{PORT} || ({DEV_COMMAND} &)

   Wait up to 30s for it to be ready. Set WE_STARTED_SERVER=true if you started it.

2. Provision test user — follow the provisioning steps in references/qa-integration.md for your auth provider (from CONFIG.md).

3. Open browser, login, navigate to the affected page — follow the login flow in references/qa-integration.md.

4. Reproduce the bug — follow the reproduction steps from the Jira ticket description. Screenshot each step:

   playwright-cli screenshot --filename=playwright-qa-screenshots/{ticket-id}-verify/NN-step.png

5. Report verdict to the user:

   Verdict	Action
   Bug confirmed	Show screenshots, continue to Phase 2
   Not reproducible	Show screenshots, ask user whether to continue
   Different behavior found	Report what actually happened, ask user how to proceed

6. Keep browser open — Phase 5.5 will reuse the session.

Error Handling

Phase 2: Research & Understand

CHECKPOINT: Did Phase 1.5 run? If not, and skip-verify=true was NOT in the invocation, STOP and go back to Phase 1.5 NOW.

MANDATORY: Before writing any code, you MUST research the affected area thoroughly.

Research budget: Keep research focused. Start with the lightest strategy:

How to research: Use an Explore agent (preferred for thorough investigation) or search directly with Glob/Grep/Read. Either way, you must:

1. Search the codebase for files related to the bug
2. Map the affected code paths: all files involved, how they interact, where the bug originates
3. Understand the current behavior: what the code does vs. what it should do
4. Check for existing patterns: look in shared libs for utilities that could help

Output to the user: Present findings using this structure:

1. Root cause (1-2 sentences)

2. Bug flow diagram (MANDATORY — always include a visual):

   Draw an ASCII data-flow diagram showing how data/control moves through the bug. Use arrows with annotations marking the bug point:

   User clicks [Action] -> ComponentA
       -> handlerFunction()
       -> someCall('/api/endpoint')  <- BUG: incorrect parameter
       -> wrong behavior in UI
   

   Keep it under 10 lines. Mark the bug with <- BUG: or X and the fix with OK.

3. Affected files and their roles (table or bullet list)

4. Proposed approach (1-3 sentences)

Then ask: "Does this look right, or would you like a different approach?"

STOP HERE. Do NOT proceed to Phase 3 until the user responds. This is a hard gate — even if the fix seems obvious, wait for the user to confirm.

Phase 3: Analyze & Plan

1. Classify complexity using these thresholds:

Edge case: 3+ files but same mechanical concern (renaming a constant, updating imports) -> still Simple.

• Simple fix: Proceed to Phase 4 directly
• Complex fix: If a delegation skill is configured in CONFIG.md, invoke it. Otherwise, plan the implementation in detail and proceed.

2. For simple fixes, create a brief plan:
   • Which files to change
   • What the change is
   • How to verify it works

Phase 4: Implement

For simple fixes:

1. Make the code changes using Edit tool
2. Verify the fix compiles and passes lint:

npm run build 2>&1 | tail -5
npm run lint 2>&1 | tail -5

3. If build/lint fails, fix the issues and re-verify
4. Run relevant tests if they exist

For complex fixes delegated to another skill: wait for completion, then continue from Phase 5.

Phase 5: Review

Skip if skip-review=true. Also skip if a delegation skill was used that includes its own review.

MANDATORY: You MUST spawn review agents. There are ZERO exceptions other than skip-review=true.

If you catch yourself thinking "this change is too small to review" — that is exactly the signal to RUN the review. Small changes with subtle bugs are the hardest to catch yourself.

HARD GATE: Do NOT proceed to Phase 6 without spawning agents.

Agent Pool

Pick 3-5 agents from this pool based on what the fix actually touches:

Tier 1 — Always include (mandatory):

Tier 2 — Pick based on what the diff touches (add 1-3):

Selection rules:

• Minimum 3 agents, maximum 5
• Code Reviewer + Silent Failure Hunter are mandatory in every review
• Pick the remaining 1-3 based on which areas the diff touches

Steps

1. Run git diff --stat to see the scope of changes
2. Select agents based on the diff
3. Announce the team before spawning:

   Spawning {N} review agents: {Agent1} ({type}), {Agent2} ({type}), ... — reviewing {N} files, {M} lines changed
   

4. Spawn agents in parallel (run_in_background: true), each receiving the git diff output
5. Report completion as each agent finishes
6. Merge and deduplicate findings

After review completes:

• Critical or high issues: Fix them, re-run build/lint, create a new commit
• Medium/low issues: Note them in the Jira comment, fix if quick
• No issues: Note "No issues found" in summary

Iteration limit: Max 2 fix-then-re-review cycles.

Phase 5.5: QA Check (Headless Browser Fix Verification)

PARAMETER CHECK: Read back the user's invocation arguments. Is skip-qa-check=true literally present?

• YES -> skip this phase.
• NO -> this phase is MANDATORY.

Do NOT infer skip-qa-check from the nature of the bug. Build + review verify code correctness; browser testing verifies user-facing behavior. They test different things.

Read references/qa-integration.md for the full interaction steps.

Steps

1. Re-provision test user (reset test data)

2. Restore browser session or re-login

3. Navigate to the same page tested in Phase 1.5

4. Re-run the reproduction steps — the bug should no longer occur. Screenshot each step.

5. Check for regressions: look for new console errors

6. Report verdict:

   Verdict	Action
   Fix verified	Show before/after screenshots, proceed to Phase 6
   Fix incomplete	Report what still fails -> loop back to Phase 4 (max 1 retry)
   Regression found	Report the regression -> loop back to Phase 4

7. Cleanup — close browser, clean up test user, kill dev server if you started it

Escalation After 2 Failed QA Attempts

If still failing after 2 attempts, present the user with a structured refinement menu:

QA check failed twice. Here's what's still broken:
- <specific failure with screenshot references>
- <browser console errors if any>

How would you like to proceed?

1. **Manual test** — I'll keep the browser open so you can inspect it yourself.
2. **Different approach** — I'll re-research the bug from scratch and try an alternative fix.
3. **Commit with known issue** — Ship what we have and note the remaining issue in Jira.
4. **Pair debug** — Walk me through what you expect step by step.

STOP — wait for the user's response.

Phase 6: Commit & Push

MANDATORY: You MUST both commit AND push. A local-only commit is not a completed fix.

Branch strategy

Use the strategy resolved in Phase 0:

Worktree flow

Phase 6.5: Worktree Merge & Cleanup (after Phase 7 succeeds):

After deployment succeeds, merge the fix into main and clean up. Use a single chained Bash command (Bash tool resets cwd between calls):

REPO_ROOT=$(git worktree list | head -1 | awk '{print $1}') && BRANCH_NAME=$(git branch --show-current) && cd "$REPO_ROOT" && git checkout main && git pull origin main && git merge "$BRANCH_NAME" --no-edit && git push origin main && echo "Merged $BRANCH_NAME into main"

Then clean up:

REPO_ROOT=$(git worktree list | head -1 | awk '{print $1}') && WORKTREE_PATH=$(pwd) && BRANCH_NAME=$(git branch --show-current) && cd "$REPO_ROOT" && git worktree remove --force "$WORKTREE_PATH" && git branch -d "$BRANCH_NAME" 2>/dev/null && git push origin --delete "$BRANCH_NAME" 2>/dev/null && echo "Worktree cleaned up"

If merge conflicts occur: Stop and ask the user. Do NOT force-merge.

Commit

Create a conventional commit referencing the ticket:

git add <specific-files-changed>
git commit -m "$(cat <<'EOF'
fix: <concise description of what was fixed>

<Optional body: 1-2 sentences explaining the root cause and fix>

Resolves {TICKET-ID}

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Then push to remote:

git push origin <current-branch>

If push is rejected (remote has newer commits):

git stash && git pull --rebase origin <current-branch> && git stash pop
git push origin <current-branch>

If pushed to a feature branch, offer to create a PR.

Capture the commit hash: git rev-parse --short HEAD

Phase 7: Deployment Monitor

Skip if skip-deploy=true.

After pushing, monitor the deployment to confirm the build succeeds before handing off to QA.

The deployment platform is configured in CONFIG.md. Currently supported: Vercel (via MCP tools).

Vercel

Read .vercel/project.json for the project ID and team ID.

1. Find the latest deployment: Use mcp__claude_ai_Vercel__list_deployments. Find the one matching your commit SHA with state: "BUILDING".

2. Poll: Use mcp__claude_ai_Vercel__get_deployment with the deployment ID.

   State	Action
   BUILDING	Wait, poll again
   READY	Report success, proceed
   ERROR	Read logs, fix, re-commit, re-push (max 2 retries)
   CANCELED	Warn user, proceed

   Polling schedule: 45s, 45s, 60s, 60s, 60s, 60s (max 6 polls).

3. On failure: Read build logs via mcp__claude_ai_Vercel__get_deployment_build_logs, fix the code, create a new commit, push, and re-monitor.

Other Platforms

If platform in CONFIG.md is none, skip this phase entirely. For unsupported platforms, warn the user and suggest they verify the deployment manually.

Phase 8: Jira Handoff

Skip if skip-jira=true.

Resolve the assignee from CONFIG.md using the assignee parameter (alias lookup).

IMPORTANT: Jira MCP body parameter must be a JSON object, NOT a JSON string.

Execute these three Jira operations in parallel:

1. Transition ticket (transition IDs from CONFIG.md):

mcp__jira__jira_post:
  path: /rest/api/3/issue/{ticketId}/transitions
  body: {"transition": {"id": "<transition-id-from-config>"}}

2. Assign to QA engineer:

mcp__jira__jira_put:
  path: /rest/api/3/issue/{ticketId}
  body: {"fields": {"assignee": {"accountId": "<account-id-from-config>"}}}

3. Post comment (Jira ADF format):

Include:

• What was fixed (root cause + solution)
• Commit reference (short hash)
• QA verification steps
• Review findings summary

If the ticket has existing comments with questions, acknowledge them.

{
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          {"type": "text", "text": "Fix committed: <description>."}
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {"type": "text", "text": "Commit: <short-hash> — <commit subject line>"}
        ]
      },
      {
        "type": "paragraph",
        "content": [
          {"type": "text", "text": "QA verification steps:", "marks": [{"type": "strong"}]}
        ]
      },
      {
        "type": "orderedList",
        "attrs": {"order": 1},
        "content": [
          {
            "type": "listItem",
            "content": [
              {"type": "paragraph", "content": [{"type": "text", "text": "<step 1>"}]}
            ]
          }
        ]
      }
    ]
  }
}

Phase 9: Summary

Report to the user:

## Fix Complete: {TICKET-ID}

**Ticket**: {summary}
**Status**: Moved to {QA|In Review|Done} -> Assigned to {assignee name}
**Commit**: `{short-hash}` — {commit subject}
**Deployment**: {Ready at <url> / Failed / Skipped}

### What was fixed
{1-2 sentence description of root cause and fix}

### Files changed
{list of files}

### Review findings
{summary or "Skipped" or "No issues found"}

### Deployment
{Build succeeded / Failed after N retries / Monitoring skipped}

### QA steps posted to Jira
{numbered list}

### Phase tracker
| Phase | Status |
|-------|--------|
| 0. Branch Strategy | {main / separate branch / worktree} |
| 1. Read Ticket | {Done/Failed} |
| 1.5. QA Verify | {Bug confirmed / Not reproducible / Skipped} |
| 2. Research | {Done — user acknowledged} |
| 3. Plan | {Simple fix / Complex -> delegated} |
| 4. Implement | {Done — build+lint passed} |
| 5. Review | {Done — N findings / Skipped} |
| 5.5. QA Check | {Fix verified / Fix incomplete / Skipped} |
| 6. Commit & Push | {Done — hash} |
| 7. Deploy | {Ready / Failed / Skipped} |
| 6.5. Worktree Merge | {Merged + cleaned up / N/A} |
| 8. Jira Handoff | {Done / Skipped} |
| 9. Summary | Done |

Error Handling

Tips

1. Simple bugs are the sweet spot — This skill shines for 1-2 file fixes where the overhead of manual Jira management exceeds the coding effort
2. Skip review for trivial fixes — Use skip-review=true for obvious one-liner fixes
3. Add more QA assignees — Update CONFIG.md as your team grows
4. Existing comments matter — The skill reads ticket comments and responds contextually
5. Parallel fixes with worktrees — Use branch=worktree to run multiple /fix-ticket in separate terminals simultaneously

Evaluation Criteria

After each run, check whether the skill passed on these specific behaviors. A run passes if ALL criteria are met: