Pull

JIRA Issue Analysis Skill

Purpose

Fetch JIRA issue details, extract requirements, and retrieve linked Confluence documentation.

Usage

/pull DRT-17270

What This Skill Does

1. Detect Target Repo: Identifies the repo from git remote and writes target-repo.md
2. Fetch JIRA Issue: Retrieves complete issue details from Atlassian JIRA
3. Extract Requirements: Parses summary, description, acceptance criteria, components, labels
4. Retrieve Confluence Docs: Fetches linked Confluence pages
5. Download Attachments: Downloads JIRA attachments (screenshots, PDFs, documents) if credentials configured (skips processing entirely if not, saving tokens)
6. Create Workflow Directory: Sets up workflow/jira-to-github/<JIRA-NUMBER>/ for state management
7. Output Structured Analysis: Saves comprehensive analysis to current-issue.md with embedded summary (single-pass generation saves tokens)

Prerequisites

Atlassian API Token (optional but recommended):

1. Generate token at: https://id.atlassian.com/manage-profile/security/api-tokens
2. Set environment variables:

   export ATLASSIAN_EMAIL="[email protected]"
   export ATLASSIAN_API_TOKEN="your-api-token-here"
   

3. Add to shell profile (~/.zshrc or ~/.bashrc) to persist across sessions

Token Optimization: If credentials are not configured, the skill skips ALL attachment processing (metadata parsing + downloads), saving tokens per run. Analysis continues without attachments.

Instructions

You are coordinating the analysis of a JIRA issue for the Detective Panda team.

CRITICAL: Your ONLY job is to:

1. Detect the target repo and write target-repo.md
2. Extract the JIRA key from the skill argument
3. Create the workflow directory
4. Spawn a sub-agent using the Task tool
5. Report the agent's results to the user

DO NOT:

• Fetch JIRA data yourself
• Read any code files
• Perform any analysis yourself
• If the sub-agent fails, DO NOT retry the work yourself - report the failure to the user

Step 1: Detect Target Repo

Identify which repo the user is working in and persist it for downstream skills.

1. Run git remote get-url origin to get the remote URL
2. Parse the repo slug:
   • Strip [email protected]: or https://github.com/ prefix
   • Strip .git suffix
   • Result: org/repo-name (e.g., krogertechnology/esperanto)
3. Find matching profile:
   • Use Glob tool with pattern context/repos/*.md to find all profile files
   • For each profile file found: a. Use Read tool to read the file b. Look for the line containing - **Repo**: in the "## Repo Identity" section c. Extract the value after - **Repo**: (e.g., krogertechnology/esperanto) d. Compare this value EXACTLY with the parsed slug from step 2
   • If exact match found:
     • Extract profile filename (e.g., esperanto.md from /Users/.../context/repos/esperanto.md)
     • Set profile path as context/repos/<filename>.md
     • Extract repo-name from slug (part after /)
     • Display: ✓ Detected repo: <repo-name>
   • If no match found after checking all profiles:
     • Use AskUserQuestion to ask "Which repo are you working in?"
     • Derive options from the profile filenames found by Glob (strip path prefix and .md extension for display)
     • After user selects, read that profile file and extract the repo-slug from its **Repo**: field
4. Record CWD as repo-path
5. Write target-repo.md to the workflow directory (created in Step 2):

# Target Repo

- **repo-name**: <repo-name from slug, e.g., "esperanto">
- **repo-slug**: <full slug from git remote, e.g., "krogertechnology/esperanto">
- **repo-path**: <CWD absolute path>
- **profile**: context/repos/<matched-filename>.md (e.g., "context/repos/esperanto.md")
- **detected-via**: git-remote | user-prompt

Note: target-repo.md is written after the workflow directory is created in Step 2. Perform detection first, hold the values, then write the file after mkdir.

Step 2: Extract JIRA Key and Create Workflow Directory

Extract the JIRA key from the skill argument (format: DRT-12345, TEAM-123, etc.) and create the workflow directory.

CRITICAL: The workflow directory MUST be created at the project root (the repo-path detected in Step 1), NOT in the skills directory.

Use the repo-path from Step 1 to construct absolute paths:

JIRA_KEY="<extracted-key>"
JIRA_NUMBER="${JIRA_KEY##*-}"
REPO_PATH="<repo-path from Step 1>"
mkdir -p "${REPO_PATH}/workflow/jira-to-github/${JIRA_NUMBER}"
mkdir -p "${REPO_PATH}/workflow/jira-to-github/${JIRA_NUMBER}/attachments"

Then write target-repo.md to ${REPO_PATH}/workflow/jira-to-github/${JIRA_NUMBER}/target-repo.md with the values detected in Step 1.

Step 3: Spawn Analysis Agent

Use the Task tool with these exact parameters:

• subagent_type: "general-purpose"
• description: "Analyze JIRA issue <JIRA-KEY>"
• prompt: Use the template below, replacing <JIRA-KEY>, <JIRA-NUMBER>, and <REPO-PATH> with actual values

Agent Prompt:

Analyze JIRA issue <JIRA-KEY> and create a comprehensive analysis document.

JIRA KEY: <JIRA-KEY>
JIRA NUMBER: <JIRA-NUMBER>
REPO PATH: <REPO-PATH>

IMPORTANT CONSTRAINTS:
- ONLY use Atlassian MCP tools (mcp__atlassian__*) to fetch data
- DO NOT read any code files from the repository
- DO NOT use Read, Glob, or Grep tools
- DO NOT analyze code changes or implementation details
- This is purely a JIRA/Confluence data extraction task
- DO NOT use bash commands for file operations (cat, jq, grep, wc, ls, etc.)
- DO NOT read from ~/.claude/projects/ or write to /tmp/
- USE the MCP tool response data directly - it's already structured JSON
- PARSE the tool response in-memory, don't write intermediate files
- ONLY use Write tool to save the final analysis file - no other file operations needed

TOKEN OPTIMIZATION REQUIREMENTS:
- Target output size: 4.5-5 KB (20-25% reduction from baseline)
- Use tables instead of paragraphs for structured data
- Use bullet points for technical context (no verbose subsections)
- Remove duplicate links - Figma/Confluence links should appear ONLY in dedicated sections
- Keep descriptions concise and factual
- Avoid generic commentary or explanations for obvious items
- Use "None" or "Not applicable" instead of explaining why something is absent

Tasks:
1. Fetch JIRA issue using Atlassian MCP (mcp__atlassian__getJiraIssue)
   - Use MCP tool getJiraIssue (mcp__atlassian__getJiraIssue)
   - Extract: Key, Summary, Description, Type, Status, Priority, Assignee, Reporter, Comments
   - Extract: Components, Labels, Acceptance Criteria
   - Extract: Figma links and Confluence page links from description

2. Fetch Confluence pages:
   - Confluence page links extracted from the JIRA issue
   - This task is optional and call the MCP tools only if you found linked Confluence pages
   - DO NOT use mcp__atlassian__searchJiraAndConfluence or any Rovo search tools
   - ONLY fetch Confluence pages whose URLs appear explicitly in the JIRA issue description or comments
   - If no Confluence links are found in the issue, skip Confluence retrieval entirely
   - Use Atlassian MCP to fetch relevant Confluence pages:
     - mcp__atlassian__getPage (for specific page URLs)
     - mcp__atlassian__getPageContent (for full page content)

2.5. Download JIRA Attachments (Token-Optimized):
   - CRITICAL: Check credentials FIRST before any attachment processing to save tokens
   - Use Bash tool to check environment variables:
     ```bash
     if [ -z "$ATLASSIAN_EMAIL" ] || [ -z "$ATLASSIAN_API_TOKEN" ]; then
       echo "SKIP_ATTACHMENTS=true"
     fi
     ```
   - If credentials missing:
     - DO NOT parse attachment metadata from JIRA response
     - DO NOT process fields.attachment array
     - Log "Atlassian credentials not configured - attachments skipped" to <REPO-PATH>/workflow/jira-to-github/<JIRA-NUMBER>/errors.log
     - Skip to step 3 (document generation) immediately

   - Only if credentials are configured:
     a. Parse mcp__atlassian__getJiraIssue response for attachment data (fields.attachment array)
     b. Extract JIRA base URL from the MCP response (.self field) using pattern matching:
        JIRA_BASE_URL=$(echo "$JIRA_RESPONSE" | jq -r '.self' | sed -E 's|(https?://[^/]+)/.*|\1|')
     c. If attachments exist, download using Bash tool with authenticated API endpoint:
        # Parse attachment metadata
        echo "$JIRA_RESPONSE" | jq -c '.fields.attachment[]' | while read -r attachment; do
          ATTACH_ID=$(echo "$attachment" | jq -r '.id')
          FILENAME=$(echo "$attachment" | jq -r '.filename')

          # Download using authenticated endpoint
          curl -L -f -s -S \
               -u "${ATLASSIAN_EMAIL}:${ATLASSIAN_API_TOKEN}" \
               -o "${REPO_PATH}/workflow/jira-to-github/${JIRA_NUMBER}/attachments/${FILENAME}" \
               "${JIRA_BASE_URL}/rest/api/3/attachment/content/${ATTACH_ID}"

          # Check download status
          if [ $? -ne 0 ]; then
            echo "❌ Failed to download: ${FILENAME}" >> "${REPO_PATH}/workflow/jira-to-github/${JIRA_NUMBER}/errors.log"
            echo "   Error: HTTP error from JIRA API" >> "${REPO_PATH}/workflow/jira-to-github/${JIRA_NUMBER}/errors.log"
          fi
        done
     d. If download fails, document in <REPO-PATH>/workflow/jira-to-github/<JIRA-NUMBER>/errors.log

   - Filter by type (only if processing attachments):
     ✅ Images: .png, .jpg, .jpeg, .gif, .svg, .webp
     ✅ Documents: .pdf, .doc, .docx
     ❌ Skip: Archives (.zip, .tar, .gz), executables (.exe, .sh, .bat), files >10MB

   - Error handling:
     - curl flags: -f (fail on HTTP errors), -s (silent), -S (show errors), -L (follow redirects)
     - If download fails: Log "Failed to download: <filename>" with "HTTP error from JIRA API" to errors.log
     - Continue processing remaining attachments even if one fails
     - If no attachments: Skip section silently (no error)
     - Graceful degradation: Continue workflow even if all downloads fail

3. Create structured analysis document with this format:

IMPORTANT FORMATTING REQUIREMENTS FOR TOKEN OPTIMIZATION:
- Use tables instead of verbose paragraphs where possible
- Use bullet points for technical context
- Remove duplicate information across sections
- Keep descriptions concise and actionable
- Remove Figma/Confluence links from Description section (they have dedicated sections)

# JIRA Issue Analysis: <JIRA-KEY>

## Issue Details

- **Key**: <JIRA-KEY>
- **Summary**: <Summary>
- **Type**: <Issue Type>
- **Status**: <Status>
- **Priority**: <Priority>
- **Assignee**: <Assignee>
- **Reporter**: <Reporter>
- **Created**: <Created date>
- **Updated**: <Updated date>

## Description

<Full description text ONLY - remove any Figma/Confluence links or URLs from this section>

## Acceptance Criteria

<List of acceptance criteria>

## Components

<List of components>

## Labels

<List of labels or "None">

## Comments

<Summary of comments or "No comments on this issue.">

## Confluence Documentation

<Links to Confluence pages if present, or "No Confluence documentation linked">

## Figma Links

<List all Figma design links found in the issue description>
<If none found, state: "No Figma links in this issue">

## Attachments

<If credentials not configured:>
Credentials not configured - attachment processing skipped. See errors.log for details.

<If credentials configured but no attachments:>
No attachments on this issue

<If attachments were downloaded, use this table format:>
| Filename | Type | Size | Path | Status |
|----------|------|------|------|--------|
| <filename> | Image (PNG) | 234 KB | attachments/<filename> | Downloaded ✓ |
| <filename> | PDF Document | 1.2 MB | attachments/<filename> | Downloaded ✓ |
| <filename> | Archive (ZIP) | 5.6 MB | - | Skipped (archive) |

<If download failed, mark status as: "Download Failed ❌">

*Note: Visual analysis deferred to /explore phase*

## Technical Context

<Use concise bullet points instead of paragraphs and subsections:>
- Key implementation notes (1 line each)
- Dependencies or related technical considerations
- Any deferred/out-of-scope items
- Multi-platform requirements

<Remove generic commentary - focus on task-specific technical details only>

---

## Summary

**Issue**: <JIRA-KEY> - <Summary>
**Type**: <Issue Type> | **Priority**: <Priority>
**Confluence Docs**: <count> retrieved
**Figma Links**: <count> found
**Attachments**: <count> downloaded (<breakdown by type, e.g., "2 images, 1 PDF">)
**Analysis File**: workflow/jira-to-github/<JIRA-NUMBER>/current-issue.md

**Next Step**: Run `/explore` to gather implementation context

---
*Analysis generated: <timestamp>*

4. Save the analysis to: <REPO-PATH>/workflow/jira-to-github/<JIRA-NUMBER>/current-issue.md

5. Display ONLY the Summary section (Token Optimization):
   - DO NOT regenerate a separate summary
   - Extract and display the "## Summary" section from the analysis document you just created
   - This avoids redundant summary generation, saving tokens
   - The summary is already in the analysis file - just show it to the user

REMINDER: Your job is COMPLETE after saving the analysis and displaying the summary. DO NOT read code files or proceed to implementation planning.

ERROR HANDLING:
- If JIRA issue not found: Log to <REPO-PATH>/workflow/jira-to-github/<JIRA-NUMBER>/errors.log and show user-friendly error
- If Confluence fetch fails: Continue with JIRA data only, note missing docs in analysis
- If authentication fails: Show clear error about MCP credentials

Step 4: Handle Agent Result

If the agent succeeds:

• Read the output from the Task tool result
• Report the summary to the user as provided by the agent

If the agent fails:

• Report the error to the user with the agent's error message
• Suggest the user check:
  • Atlassian MCP credentials are configured
  • JIRA issue key is correct
  • Network connectivity
• DO NOT attempt to do the analysis yourself
• DO NOT call any Atlassian MCP tools yourself
• DO NOT proceed with the workflow

Error Handling

For the coordinating agent (you):

• If Task tool fails to spawn sub-agent: Report error to user, do not proceed
• If sub-agent returns an error: Pass the error to user, do not retry yourself

For the sub-agent (error handling instructions included in agent prompt):

• If JIRA issue not found: Log to <REPO-PATH>/workflow/jira-to-github/<JIRA-NUMBER>/errors.log and show user-friendly error
• If Confluence fetch fails: Continue with JIRA data only, note missing docs in analysis
• If authentication fails: Show clear error about MCP credentials

Common errors to help user troubleshoot:

• JIRA issue not found: Verify issue key format (DRT-12345). Check if issue exists in JIRA.
• Confluence page not found: Check page permissions or search with different keywords
• Authentication failure: Verify Atlassian credentials in MCP configuration
• Network errors: Retry after a few seconds or check connectivity

Examples

Example 1: Standard feature story

/pull DRT-17270

Example 2: Bug fix

/pull DRT-17345

Example 3: Technical task

/pull DRT-17410