siesa-agents 2.1.27 → 2.1.29

package/bmad-core/tasks/sync-prd-to-jira.md

@@ -0,0 +1,439 @@
+<!-- Powered by BMAD™ Core -->
+
+# Sync PRD to Jira Task
+
+## Purpose
+
+Automatically create Jira epics and stories based on a Product Requirements Document (PRD). This task extracts the epic and story structure from the PRD and creates corresponding issues in Jira using the MCP Jira integration, with all configuration managed through `jira-preferences.md`.
+
+## When to Use This Task
+
+**Use this task when:**
+
+- You have a completed PRD that needs to be translated to Jira
+- You want to automate the creation of multiple epics and stories
+- You need to maintain traceability between PRD and Jira issues
+- You want consistent issue structure based on PRD organization
+
+**Prerequisites:**
+
+- Completed PRD document (from `create-prd` or `create-brownfield-prd`)
+- Jira preferences configured in `.bmad-core/data/jira-preferences.md`
+- Active Jira connection with appropriate permissions
+- MCP Jira integration available
+
+## Instructions
+
+### Phase 1: Configuration & Validation
+
+#### Step 0: Validate Jira Authentication (REQUIRED)
+
+**CRITICAL:** Validate authentication BEFORE any Jira operations
+
+**Action:** Execute authentication check
+
+- [ ] Call `validate-jira-auth.md` task
+- [ ] Verify authentication is active
+- [ ] Only proceed if validation passes
+
+**If validation fails:** HALT and instruct user to re-authenticate via MCP panel before continuing.
+
+---
+
+#### Step 1: Load Jira Preferences
+
+```elicit
+path: Load the Jira preferences file
+format: |
+  Loading Jira configuration from: `.bmad-core/data/jira-preferences.md`
+  
+  Please confirm the following settings:
+  - Provider: {{provider}}
+  - Project Key: {{project_key}}
+  - Create Epics First: {{create_epics_first}}
+  - Dry Run Mode: {{dry_run_mode}}
+  
+  Type 'proceed' to continue, or 'edit' to modify preferences first.
+```
+
+#### Step 2: Identify PRD Document
+
+```elicit
+path: Locate the PRD to sync
+format: |
+  Which PRD document should be synced to Jira?
+  
+  Options:
+  1. Specify file path (e.g., `docs/prd.md`)
+  2. Use most recently created PRD
+  3. Search for PRD by name
+  
+  Enter selection (1-3) or file path:
+```
+
+#### Step 3: Parse PRD Structure
+
+**Action:** Read and analyze the PRD document structure
+
+- [ ] Load PRD content
+- [ ] Identify epic sections based on parsing rules from preferences
+- [ ] Extract story details under each epic
+- [ ] Map PRD structure to Jira hierarchy
+- [ ] Validate all required fields are present
+
+**Expected Output:**
+```markdown
+## Parsed Structure:
+
+### Epic 1: {{Epic Name}}
+- Goal: {{Epic Goal}}
+- Stories: {{Story Count}}
+  - Story 1.1: {{Story Title}}
+  - Story 1.2: {{Story Title}}
+
+### Epic 2: {{Epic Name}}
+- Goal: {{Epic Goal}}
+- Stories: {{Story Count}}
+  - Story 2.1: {{Story Title}}
+  - Story 2.2: {{Story Title}}
+
+Total: {{Epic Count}} epics, {{Story Count}} stories
+```
+
+#### Step 4: Confirm Sync Plan
+
+```elicit
+path: Review and confirm sync plan
+format: |
+  The following items will be created in Jira ({{project_key}}):
+  
+  {{Display parsed structure from Step 3}}
+  
+  Options:
+  1. Proceed with creation
+  2. Enable dry-run mode (preview only)
+  3. Modify selection (exclude specific items)
+  4. Cancel
+  
+  Enter selection (1-4):
+```
+
+### Phase 2: Epic Creation
+
+#### Step 5: Create Epics in Jira
+
+**For each epic identified in PRD:**
+
+1. **Extract Epic Data:**
+   - Epic Name: From section header
+   - Epic Goal: First paragraph after header
+   - Description: Detailed content from PRD section
+   - Labels: `prd-sync`, `automated`, `{epic-slug}`
+
+2. **Map Custom Fields:**
+   ```
+   Based on jira-preferences.md:
+   - Epic Name (customfield_10011): {{epic_name}}
+   - Business Value (customfield_10020): {{if specified in PRD}}
+   - Target Quarter (customfield_10021): {{if specified in PRD}}
+   ```
+
+3. **Create Epic Issue:**
+   ```javascript
+   // Using MCP Jira - Pseudo-code for clarity
+   {
+     provider: "jira",
+     issue_type: "Epic",
+     summary: "[Epic] {{Epic Name}}",
+     description: "## Epic Goal\n{{goal}}\n\n## Details\n{{description}}\n\n---\n*Source: {{prd_path}}*",
+     project_key: "{{from preferences}}",
+     priority: "{{from preferences or PRD}}",
+     labels: ["prd-sync", "automated", "{{epic-slug}}"],
+     custom_fields: {
+       "customfield_10011": "{{epic_name}}"
+       // Additional custom fields from preferences
+     }
+   }
+   ```
+
+4. **Store Epic Key:**
+   - Save the created Jira epic key (e.g., `PROJ-123`) for linking stories
+   - Maintain mapping: `Epic Name` → `Jira Key`
+
+**Progress Output:**
+```markdown
+Creating Epics:
+✓ Epic 1: {{Name}} → {{JIRA-KEY}}
+✓ Epic 2: {{Name}} → {{JIRA-KEY}}
+⚠ Epic 3: {{Name}} → Failed ({{error message}})
+```
+
+### Phase 3: Story Creation
+
+#### Step 6: Create Stories in Jira
+
+**For each story under each epic:**
+
+1. **Extract Story Data:**
+   - Title: From story header or user story format
+   - User Story: "As a... I want... So that..." format
+   - Description: Detailed content from PRD
+   - Acceptance Criteria: Extracted from AC sections or checklists
+   - Technical Notes: From implementation sections
+   - Parent Epic: Mapped epic key from Step 5
+
+2. **Map Custom Fields:**
+   ```
+   Based on jira-preferences.md:
+   - Story Points (customfield_10016): {{if specified in PRD}}
+   - Acceptance Criteria (customfield_10017): {{extracted AC}}
+   - Technical Notes (customfield_10018): {{tech details}}
+   - Dependencies (customfield_10019): {{if specified}}
+   ```
+
+3. **Create Story Issue:**
+   ```javascript
+   // Using MCP Jira - Pseudo-code for clarity
+   {
+     provider: "jira",
+     issue_type: "Story",
+     summary: "{{User Role}}: {{Action}}",
+     description: "## User Story\n{{user_story}}\n\n## Description\n{{description}}\n\n## Acceptance Criteria\n{{ac}}\n\n---\n*Source: {{prd_path}}*",
+     project_key: "{{from preferences}}",
+     priority: "{{from preferences or PRD}}",
+     labels: ["prd-sync", "automated", "{{parent-epic-slug}}"],
+     epic_link: "{{parent_epic_key}}",
+     custom_fields: {
+       "customfield_10017": "{{acceptance_criteria}}",
+       "customfield_10018": "{{technical_notes}}"
+       // Additional custom fields from preferences
+     }
+   }
+   ```
+
+4. **Link to Epic:**
+   - If Jira supports epic links, establish parent-child relationship
+   - Alternative: Use `epic_link` field with parent epic key
+
+**Progress Output:**
+```markdown
+Creating Stories for Epic {{EPIC-KEY}}:
+✓ Story 1: {{Title}} → {{JIRA-KEY}}
+✓ Story 2: {{Title}} → {{JIRA-KEY}}
+✓ Story 3: {{Title}} → {{JIRA-KEY}}
+```
+
+### Phase 4: Verification & Reporting
+
+#### Step 7: Generate Sync Report
+
+**Create summary report:**
+
+```markdown
+# PRD to Jira Sync Report
+
+**PRD Source:** {{prd_path}}
+**Jira Project:** {{project_key}}
+**Sync Date:** {{timestamp}}
+**Dry Run:** {{dry_run_mode}}
+
+## Summary
+
+- **Total Epics:** {{created}}/{{attempted}} created successfully
+- **Total Stories:** {{created}}/{{attempted}} created successfully
+- **Failed Items:** {{failure_count}}
+
+## Created Items
+
+### Epics
+
+| Epic Name | Jira Key | Stories | Status |
+|-----------|----------|---------|--------|
+| {{name}}  | {{key}}  | {{count}}| ✓     |
+| {{name}}  | {{key}}  | {{count}}| ✓     |
+
+### Stories
+
+| Story Title | Epic | Jira Key | Status |
+|-------------|------|----------|--------|
+| {{title}}   |{{epic}}|{{key}} | ✓     |
+| {{title}}   |{{epic}}|{{key}} | ✓     |
+
+## Failed Items
+
+{{If any items failed}}
+
+| Item | Type | Error |
+|------|------|-------|
+|{{name}}|{{type}}|{{error}}|
+
+## Next Steps
+
+1. Review created issues in Jira: {{jira_project_url}}
+2. {{If failures}} Retry failed items manually or after fixing configuration
+3. Update story points and assignments as needed
+4. Add to sprint/backlog for planning
+
+## Traceability
+
+PRD sections have been mapped to Jira as follows:
+- {{PRD Section}} → {{Jira Epic Key}}
+  - {{PRD Subsection}} → {{Jira Story Key}}
+
+---
+*Generated by PM Agent - sync-prd-to-jira task*
+```
+
+#### Step 8: Update PRD with Jira Links
+
+**CRITICAL:** Always update the PRD document with Jira references for traceability
+
+**Action:** Add Jira issue keys to the PRD document
+
+```output
+🔄 Updating PRD with Jira links...
+📄 File: {{prd_file_path}}
+```
+
+**Update Strategy:**
+
+1. **Add Jira Keys Inline to Epic Headers:**
+   - Locate each epic section header in PRD
+   - Append Jira key after epic name: `## Epic Name [{{EPIC_KEY}}]`
+   - Example: `## User Authentication [PM-101]`
+
+2. **Add Jira Keys Inline to Story Items:**
+   - Locate each story under its epic
+   - Append Jira key after story title: `### Story Title [{{STORY_KEY}}]`
+   - Example: `### User Login Flow [PM-102]`
+
+3. **Add Jira Synchronization Section:**
+   - At the end of the PRD, add a new section:
+
+```markdown
+## Jira Synchronization
+
+**Sync Date:** {{current_date}}
+**Project:** [{{project_key}}]({{jira_url}}/browse/{{project_key}})
+
+### Epic Mappings
+
+| Epic | Jira Key | Link |
+|------|----------|------|
+| {{Epic 1 Name}} | {{EPIC_1_KEY}} | [View in Jira]({{jira_url}}/browse/{{EPIC_1_KEY}}) |
+| {{Epic 2 Name}} | {{EPIC_2_KEY}} | [View in Jira]({{jira_url}}/browse/{{EPIC_2_KEY}}) |
+
+### Story Mappings
+
+| Story | Epic | Jira Key | Link |
+|-------|------|----------|------|
+| {{Story 1 Name}} | {{Epic 1 Name}} | {{STORY_1_KEY}} | [View in Jira]({{jira_url}}/browse/{{STORY_1_KEY}}) |
+| {{Story 2 Name}} | {{Epic 1 Name}} | {{STORY_2_KEY}} | [View in Jira]({{jira_url}}/browse/{{STORY_2_KEY}}) |
+
+**Total Issues Created:** {{epic_count}} epics, {{story_count}} stories
+
+---
+*Synchronized by PM Agent - sync-prd-to-jira task on {{current_date}}*
+```
+
+**Expected Output:**
+```output
+✅ PRD updated with Jira links
+✅ Inline keys added to {{epic_count}} epics
+✅ Inline keys added to {{story_count}} stories
+✅ Jira Synchronization section added
+✅ File saved: {{prd_file_path}}
+
+Traceability established between PRD and Jira issues.
+```
+
+### Phase 5: Post-Sync Actions
+
+#### Step 9: Validation Checklist
+
+**Manual verification steps:**
+
+- [ ] All epics created with correct information
+- [ ] All stories linked to appropriate epics
+- [ ] Custom fields populated correctly
+- [ ] Labels applied for filtering
+- [ ] No duplicate issues created
+- [ ] Descriptions formatted correctly
+- [ ] PRD updated with Jira keys inline
+- [ ] Jira Synchronization section added to PRD
+- [ ] Links between PRD and Jira documented
+
+#### Step 10: Handoff
+
+```elicit
+path: Notify stakeholders
+format: |
+  Jira sync complete! 
+  
+  Would you like to:
+  1. Generate a stakeholder notification (email/slack format)
+  2. Copy Jira project URL to clipboard
+  3. Open Jira project in browser
+  4. Complete sync and exit
+  
+  Enter selection (1-4):
+```
+
+## Error Handling
+
+### Common Issues and Solutions
+
+**Issue:** Duplicate epics/stories detected
+- **Solution:** Check `jira-preferences.md` duplicate handling setting
+- **Action:** Skip, update existing, or create with different naming
+
+**Issue:** Custom field not found
+- **Solution:** Verify custom field IDs in `jira-preferences.md`
+- **Action:** Update configuration with correct field IDs from your Jira instance
+
+**Issue:** Permission denied
+- **Solution:** Ensure Jira credentials have create issue permissions
+- **Action:** Contact Jira admin or use different account
+
+**Issue:** PRD structure not recognized
+- **Solution:** Review PRD parsing rules in `jira-preferences.md`
+- **Action:** Adjust parsing rules or restructure PRD to match expected format
+
+**Issue:** Epic link field not available
+- **Solution:** Epic links may not be enabled in your Jira project
+- **Action:** Use labels or manual linking instead
+
+## Tips for Success
+
+1. **Start with Dry Run:** Set `dry_run_mode: true` for first sync to preview results
+2. **Standardize PRD Format:** Use templates (`prd-tmpl.yaml`) for consistent structure
+3. **Configure Once:** Set up `jira-preferences.md` thoroughly before first use
+4. **Batch Process:** Sync entire PRD at once rather than section by section
+5. **Version Control:** Commit PRD and sync report together for traceability
+6. **Review Before Assign:** Create issues unassigned, then distribute work in Jira
+7. **Use Labels:** Leverage automated labels for filtering and reporting
+8. **Maintain Mapping:** Keep PRD-to-Jira mapping document for future reference
+
+## Integration with Other Tasks
+
+- **Before:** Run `create-prd` or `create-brownfield-prd` to generate source document
+- **After:** Use `create-story` for additional stories not in original PRD
+- **Alternative:** Use `create-epic` or `create-story` for individual item creation
+
+## Configuration Reference
+
+All configuration is managed in `.bmad-core/data/jira-preferences.md`. Key settings:
+
+- **Provider Settings:** Jira, Azure DevOps, GitHub, GitLab, Linear
+- **Project Configuration:** Project key, organization, default values
+- **Field Mappings:** Standard and custom field IDs
+- **Parsing Rules:** How to extract epics/stories from PRD
+- **Automation Preferences:** Batch creation, naming conventions, error handling
+
+Refer to the configuration file for detailed documentation of all available settings.
+
+---
+
+**Task Version:** 1.0.0
+**Last Updated:** 2025-12-10
+**Dependencies:** MCP Jira Integration, jira-preferences.md