--- name: epic-analyzer description: Generate Intermediate Representation (IR) from JIRA epic and user stories via MCP server. argument-hint: [epic-key] [ir-path] allowed-tools: Read, Write, Edit, Skill, Bash, mcp__plugin_sdlc_atlassian__* model: opus disable-model-invocation: true --- # JIRA Analyzer Skill ## Overview Fetch a JIRA epic and its linked user stories via the JIRA MCP server, then generate a structured Intermediate Representation (IR) capturing requirements, acceptance criteria, and BDD scenarios. Domain models, API contracts, and business logic are delegated to the `design-analyzer` skill, which is invoked with either a design document attached to the JIRA epic or a synthesized design document generated from the requirements text. ## Derived Arguments 1. **Epic Key** (`$EPIC_KEY`): JIRA epic key (e.g., "ATR-7102") 2. **IR Output Path** (`$IR_OUTPUT`): Output path for the IR file (e.g., `./temp/feature.ir.md`) ```text $EPIC_KEY = $ARGUMENTS[0] $IR_OUTPUT = $ARGUMENTS[1] $WORK_DIR = dirname($IR_OUTPUT) # Working directory (same as IR output dir) $CRATE_NAME = basename($IR_OUTPUT, ".ir.md") # Crate name derived from IR filename ``` ## Principles (Non-Negotiable) 1. **Comprehensive Extraction**: Capture all requirements, acceptance criteria, and BDD scenarios 2. **Delegation**: Delegate all design-related IR generation (Domain Model, API Contracts, Business Logic) to the `design-analyzer` skill 3. **Zero Invention**: Do not invent requirements or functionality not present in JIRA 4. **Explicit Unknowns**: Use `[unknown]` tags for ambiguous or missing information 5. **Traceability**: Each requirement must be traceable to a JIRA issue 6. **Tagging**: Tag business logic as `[domain]`, `[infrastructure]`, `[mechanical]`, or `[unknown]` ## Tags and Unknown Tokens See complete definitions in [IR Format Specification - Tags Reference](references/ir-spec.md#tags-reference) and [Unknown Tokens Reference](references/ir-spec.md#unknown-tokens-reference). ## MCP Tool Usage ### Discovering Available Tools ```bash # List MCP servers ls /Users/andrewweston/.cursor/projects/Users-andrewweston-rust-github-com-augentic-plugins/mcps/ # If jira/ folder exists, list available tools ls /Users/andrewweston/.cursor/projects/Users-andrewweston-rust-github-com-augentic-plugins/mcps/jira/tools/ ``` ### Expected JIRA MCP Tools Based on `@modelcontextprotocol/server-jira`, expected tools include: - `get_issue` — Fetch single issue by key - `search_issues` — Search issues with JQL - `get_issue_comments` — Fetch comments for an issue - `get_epic_issues` — Fetch all issues in an epic ### Example MCP Call ```prompt CallMcpTool: server: "jira" toolName: "get_issue" arguments: {"issueKey": "ATR-7102"} ``` ## Process ### Step 1: Verify MCP Server Configuration 1. List available MCP servers to check if JIRA MCP server is configured 2. If not configured, provide setup instructions and exit with error 3. List available JIRA MCP tools to understand capabilities ### Step 2: Fetch JIRA Epic 1. Use MCP tool to fetch epic by key (`$EPIC_KEY`) 2. Extract epic metadata: - Key, Summary, Description, Status, Labels, Components - Priority, Assignee, Reporter, Created, Updated 3. Extract custom fields if present (e.g., Acceptance Criteria) ### Step 3: Fetch Linked User Stories 1. Search for issues linked to the epic (via epic link or parent relationship) 2. For each user story, extract: - Key, Summary, Description, Status - Acceptance Criteria (from Description or custom field) - BDD Scenarios (look in Description, Comments, or "Other Information" section) - Story Points, Priority 3. Preserve hierarchical relationships ### Step 3.5: Extract Technical Documentation from Descriptions Parse epic and user story descriptions for structured technical documentation sections: 1. **Identify Markdown Sections**: - Look for headers like `## Technical Specifications`, `## API Contract`, `## Domain Model`, `## External Services`, `## Database Schema`, `## Configuration` - Extract content under these headers until next same-level header 2. **Supported Section Types**: - `## Technical Specifications` — General technical details - `## API Contract` / `## API Contracts` — Endpoint specifications - `## Domain Model` — Entity definitions - `## External Services` / `## External Dependencies` — External integrations - `## Database Schema` — Database structure - `## Configuration` — Required environment variables and config 3. **Content Preservation**: - Preserve JSON code blocks as-is - Preserve YAML code blocks as-is - Preserve SQL code blocks as-is - Preserve tables and lists - Maintain formatting and structure 4. **Source Tracking**: - Tag each extracted section with source: Epic or User Story key ### Step 3.6: Fetch Issue Attachments (Optional) Attempt to fetch attachments from epic and user stories via MCP: 1. **Check MCP Capability**: - Try to call MCP tool for attachments (e.g., `jira_get_attachments`, `jira_download_attachments`) - If tool not available, skip gracefully and log in IR Notes 2. **For Each Issue** (Epic + User Stories): - Call MCP tool to list attachments - Filter for relevant file types: `.json`, `.yaml`, `.yml`, `.md`, `.sql`, `.txt` 3. **Download and Parse**: - For JSON/YAML: Parse as structured data - For Markdown: Extract as formatted text - For SQL: Extract as code block - For text files: Extract raw content 4. **Error Handling**: - If MCP tool not available: Log "Attachment support not available" in IR Notes - If attachment download fails: Log failure with filename - Continue processing remaining attachments 5. **Size Limits**: - Skip attachments larger than 1MB - Log skipped files in IR Notes ### Step 4: Parse Acceptance Criteria For each user story, parse acceptance criteria: 1. **Natural Language Format**: ```text - User can perform action X - System validates condition Y - Error message Z is displayed when... ``` 2. **Structured Format**: ```text Given: preconditions When: action Then: expected outcome ``` 3. Extract as structured requirements list ### Step 5: Parse BDD Scenarios Parse BDD scenarios from "Other Information", Comments, or Description: ```gherkin Scenario: Description Given precondition And another precondition When action occurs Then expected result And another expected result ``` Extract: - Scenario name - Given steps (preconditions) - When steps (actions) - Then steps (assertions) ### Step 6: Resolve Design Document Locate or synthesize a solution design document that will be passed to `design-analyzer` for Domain Model, API Contracts, and Business Logic IR generation. **Priority order**: 1. **JIRA attachment** — Check attachments fetched in Step 3.6 for files matching `*design*.md`, `*solution*.md`, `*architecture*.md` 2. **Synthesize from requirements** — If no attachment found, generate a design document from the JIRA data gathered in Steps 1-5 **If using a JIRA attachment**: - Use the attachment content directly as the design document - Write it to `$WORK_DIR/.design.md` - Add header: `` **If synthesizing** (no design attachment found): Assemble a Markdown design document at `$WORK_DIR/.design.md` from the JIRA data: 1. **Overview section** — From epic summary and description 2. **Domain Model section** — Compose from: - Structured `## Domain Model` sections extracted in Step 3.5 (include verbatim — these are high-fidelity) - If Step 3.5 found no Domain Model: infer entities from nouns in requirements text, attributes from field mentions, types from context, relationships from language. Mark inferred content with `` for transparency. 3. **API Contracts section** — Compose from: - Structured `## API Contract` sections extracted in Step 3.5 (include verbatim) - If Step 3.5 found no API contracts: infer endpoints from acceptance criteria verbs (e.g., "create order" → `POST /orders`), request/response shapes from preconditions/outcomes, error cases from acceptance criteria. Mark inferred content with ``. 4. **Business Rules section** — Compose from: - Structured business rules from Step 3.5 technical documentation (include verbatim) - Validation rules and algorithmic steps extracted from acceptance criteria and BDD scenarios - Preconditions, postconditions, edge cases, and failure modes - Tag each rule: `[domain]`, `[infrastructure]`, `[mechanical]`, or `[unknown]` 5. **External Dependencies section** — From Step 3.5 `## External Services` / `## External Dependencies` sections, or `[unknown — not specified in JIRA]` if absent 6. **Configuration section** — From Step 3.5 `## Configuration` sections, or `[unknown — not specified in JIRA]` if absent 7. **Open Questions section** — Ambiguities, missing information, and items requiring product team clarification. Each becomes an `[unknown]` token in the final IR. Add header to synthesized document: ```markdown ``` ### Step 7: Write Base IR Write a partial IR to `$IR_OUTPUT` using the `requirements` IR type format from the [IR Format Specification](references/ir-spec.md). The base IR contains **only** sections that epic-analyzer produces directly. Domain Model, API Contracts, Business Logic, External Dependencies, Configuration, Publication Patterns, and Implementation Requirements are produced by `design-analyzer` in Step 8. **Include in the base IR**: - **Header**: `IR Type: requirements`, `Source: JIRA Epic $EPIC_KEY`, `Generated at: ` - **Component**: Name (from epic key/summary), Origin (`JIRA Epic $EPIC_KEY`), Purpose summary - **Requirements**: Raw acceptance criteria with JIRA traceability (source issue key per requirement) - **BDD Scenarios**: Parsed Given/When/Then scenarios with source issue key - **Notes**: Any observations from JIRA analysis (missing fields, attachment issues, ambiguities) **Do NOT include**: Domain Model, API Contracts, Business Logic Blocks, External Service Dependencies, Constants & Configuration, Publication & Timing Patterns, Implementation Requirements — these will be added by `design-analyzer`. ### Step 8: Invoke design-analyzer Call `design-analyzer` as a sub-skill to produce the design-derived IR sections: ```prompt design-analyzer $WORK_DIR/.design.md $IR_OUTPUT ``` Since `$IR_OUTPUT` already exists (written in Step 7), `design-analyzer` automatically enters enrichment mode and adds Domain Model, API Contracts, Business Logic Blocks, External Service Dependencies, Constants & Configuration, Publication & Timing Patterns, and Implementation Requirements to the base IR. **Validation after design-analyzer completes**: - [ ] IR file still exists and is valid - [ ] Domain Model section added with entities and attributes - [ ] API Contracts section added with endpoints - [ ] Business Logic Blocks section added with tagged algorithm steps - [ ] Enrichment note appended to Notes section ### Step 9: Verify Final IR Read back the IR at `$IR_OUTPUT` after `design-analyzer` has completed and verify: 1. All required sections for `requirements` IR are present (see [Section Requirement Matrix](references/ir-spec.md#section-requirement-matrix)) 2. Component metadata is correct (name, origin, purpose) 3. Requirements and BDD scenarios have JIRA traceability 4. Domain Model, API Contracts, and Business Logic were added by design-analyzer 5. The IR follows the exact format specified in [ir-spec.md](references/ir-spec.md) If any required sections are missing, log the gap in the Notes section with an `[unknown]` token. ## Reference Documentation The IR format and downstream consumers are documented in shared references: - **[IR Format Specification](references/ir-spec.md)** -- Unified IR structure with section-by-section templates for `requirements` and `code-analysis` types - **[Examples](references/examples/)** -- Complete worked examples showing JIRA data to IR conversion For more detail on how the code-analyzer skill produces `code-analysis` IR, see the `code-analyzer` skill. ## Examples Detailed examples are available in the `references/examples/` directory: 1. [simple-epic.md](references/examples/simple-epic.md) - Analyze a simple epic with 2-3 user stories 2. [epic-with-bdd.md](references/examples/epic-with-bdd.md) - Epic with comprehensive BDD scenarios in "Other Information" 3. [epic-with-technical-docs.md](references/examples/epic-with-technical-docs.md) - Epic with technical documentation in markdown sections and attachments Each example includes: - JIRA epic and user story keys - Expected JIRA data structure - MCP tool calls used - Design document resolution (attachment vs synthesized) - Generated IR excerpts - Technical documentation extraction (where applicable) See the examples directory for complete details. ## Error Handling ### MCP Server Not Configured **Symptom**: MCP server folder not found or empty **Resolution**: 1. Display setup instructions from Prerequisites section 2. Exit with error: "JIRA MCP server not configured. See setup instructions above." ### Epic Not Found **Symptom**: MCP returns 404 or "Issue not found" **Resolution**: 1. Verify epic key is correct 2. Check JIRA_URL and authentication in MCP config 3. Ensure user has access to the epic ### Missing Custom Fields **Symptom**: Acceptance Criteria or BDD scenarios not found **Resolution**: 1. Check Description field for acceptance criteria 2. Look in Comments for BDD scenarios 3. Mark as `[unknown — not specified in JIRA]` if truly missing ### JQL Search Failures **Symptom**: Cannot find user stories linked to epic **Resolution**: 1. Try alternative search: `"Epic Link" = $EPIC_KEY` 2. Try: `parent = $EPIC_KEY` 3. If both fail, document in IR Notes section ## Verification Checklist Before completing, verify: - [ ] MCP server is available and configured - [ ] Epic fetched successfully with all metadata - [ ] All linked user stories retrieved - [ ] Acceptance criteria extracted from each story - [ ] BDD scenarios parsed with Given/When/Then structure - [ ] Technical documentation sections extracted from descriptions - [ ] Attachments fetched (if MCP supports it) - [ ] Design document resolved (JIRA attachment or synthesized from requirements) - [ ] Design document written to `$WORK_DIR/.design.md` - [ ] Base IR written to `$IR_OUTPUT` with Component, Requirements, BDD Scenarios - [ ] `design-analyzer` invoked successfully - [ ] Domain Model, API Contracts, Business Logic sections added by design-analyzer - [ ] All unknowns explicitly marked - [ ] Final IR follows exact format specified in [ir-spec.md](references/ir-spec.md) ## Important Notes - Do not invent requirements not present in JIRA - Preserve exact wording from acceptance criteria - Use `[unknown]` liberally when requirements are ambiguous - Traceability is critical: link each item to source JIRA issue - Focus on reconstruction-grade accuracy for downstream code generation - **Design delegation**: Domain Model, API Contracts, and Business Logic are produced exclusively by `design-analyzer`, not by this skill. Epic-analyzer's role is to resolve or synthesize the design document and write the base IR (requirements + BDD scenarios). - **Synthesized design documents**: When no design attachment is found in JIRA, epic-analyzer generates a best-effort design document from requirements text. Sections inferred from acceptance criteria are marked with `` for transparency. The quality of the final IR depends on the quality of this input. - **Design document persistence**: The resolved/synthesized design document is always written to `$WORK_DIR/.design.md` for review and reuse.

epic-analyzer

Scan your own AI components