siesa-agents 2.1.27 → 2.1.29

package/bmad-core/tasks/update-story-jira-status.md

@@ -0,0 +1,600 @@
+<!-- Powered by BMAD™ Core -->
+
+# Update Story Status Task
+
+## Purpose
+
+Update the status of a story in Jira by transitioning it to a selected target state. This task validates that all prerequisites are met before allowing the transition, including checking that all tasks/subtasks are completed and QA gates have passed.
+
+## When to Use This Task
+
+**Use this task when:**
+
+- Story implementation is complete and ready to transition to next state
+- All tasks and subtasks are checked off locally
+- QA gates (if present) need validation before marking as done
+- You need to move story to a specific workflow state (Ready for Review, Done, In Testing, etc.)
+
+**Prerequisites:**
+
+- Story document exists in `docs/stories/`
+- All tasks and subtasks marked with `[x]` in story file
+- Jira preferences configured in `.bmad-core/data/jira-preferences.md`
+- Project-specific Jira configuration in `docs/jira-conf.md`
+- Story exists in Jira with valid issue key
+- Available transitions configured in `.bmad-core/core-config.yaml` under `jira.storyTransitions`
+
+## Instructions
+
+### Phase 1: Story Identification & 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: Identify Target Story
+
+**Input Parameter:** `{story}` - Story file path provided by user when calling this task
+
+**Action:** Validate and load the story document
+
+- [ ] Check if `{story}` parameter was provided when task was called
+- [ ] If NOT provided, use elicitation below to prompt user
+- [ ] If provided, verify file exists at the specified path
+- [ ] Load story file content
+- [ ] Extract story metadata (title, status, Jira key)
+- [ ] Verify Jira issue key exists in story metadata
+- [ ] Parse tasks and subtasks structure
+
+```elicit
+path: Prompt for story file if not provided as parameter
+condition: Only show if {story} parameter is missing
+format: |
+  Which story should be updated in Jira?
+  
+  Options:
+  1. Specify file path (e.g., `docs/stories/1.1.user-authentication.story.md`)
+  2. Search for story by name
+  3. Use story from current context
+  
+  Enter selection (1-3) or file path:
+```
+
+**Expected Story Structure:**
+```markdown
+# Story: [Story Title]
+
+**Jira Issue Key:** PROJ-123
+**Status:** Ready for Review
+
+## Tasks and Subtasks
+
+- [x] Task 1
+  - [x] Subtask 1.1
+  - [x] Subtask 1.2
+- [x] Task 2
+```
+
+#### Step 2: Validate Local Completion
+
+**Action:** Check that all tasks and subtasks are marked complete
+
+- [ ] Parse all task lines (starting with `- [ ]` or `- [x]`)
+- [ ] Parse all subtask lines (indented tasks)
+- [ ] Count total tasks and subtasks
+- [ ] Count completed tasks and subtasks
+- [ ] Verify 100% completion
+
+**Validation Logic:**
+```
+Total Tasks: {{task_count}}
+Completed Tasks: {{completed_count}}
+Completion Rate: {{percentage}}%
+
+Status: {{PASS/FAIL}}
+```
+
+**If Validation Fails:**
+```output
+❌ Cannot update story status - incomplete tasks detected:
+
+Pending Tasks:
+- [ ] {{task_name_1}}
+  - [ ] {{subtask_name_1.1}}
+- [ ] {{task_name_2}}
+
+Please complete all tasks before updating Jira status.
+
+HALT execution.
+```
+
+#### Step 3: Load Jira Configuration
+
+**Action:** Read configuration for Jira connection details
+
+- [ ] Load `.bmad-core/data/jira-preferences.md`
+- [ ] Load `docs/jira-conf.md`
+- [ ] Extract provider, project key, cloud ID
+- [ ] Verify all required connection details present
+
+**Required Configuration in `docs/jira-conf.md`:**
+```markdown
+**Project Key:** PM
+**Project Name:** Prueba MCP
+**Cloud ID:** 3b04e1a3-a260-4679-bdc8-0440507fbe26
+**Jira URL:** https://siesa-test-sandbox.atlassian.net
+```
+
+**If Configuration Missing:**
+```output
+⚠️ Jira configuration not found in `docs/jira-conf.md`.
+
+Please run the `*jira-setup` command first to configure project-specific Jira integration.
+
+Required details:
+- Project Key
+- Cloud ID
+- Jira URL
+
+HALT execution until configuration is complete.
+```
+
+### Phase 2: QA Gate Validation (Conditional)
+
+#### Step 4: Check for QA Gates
+
+**Action:** Determine if story has QA gate requirements
+
+- [ ] Search story content for QA gate references
+- [ ] Check for `## QA Gates` section
+- [ ] Check for gate status fields
+- [ ] Identify if validation needed for "Done" transition
+
+**Detection Pattern:**
+```markdown
+## QA Gates
+
+### Gate: [Gate Name]
+- **Status:** PASS | FAIL | CONCERN | WAIVED
+```
+
+#### Step 5: Validate QA Gates (If Transitioning to "Done")
+
+**Action:** If target status is "Done" and QA gates exist, validate them
+
+- [ ] Parse all QA gate sections
+- [ ] Extract gate names and status values
+- [ ] Check each gate status
+- [ ] Verify no FAIL, CONCERN, or WAIVED states
+- [ ] Confirm all gates show PASS
+
+**Validation Logic:**
+```
+QA Gate Validation:
+{{gate_name_1}}: {{status_1}}
+{{gate_name_2}}: {{status_2}}
+
+Overall Status: {{PASS/FAIL}}
+```
+
+**If QA Gates Fail:**
+```output
+❌ Cannot transition to Done - QA gate requirements not met:
+
+QA Gate Status:
+- {{gate_name_1}}: {{status}} ❌
+- {{gate_name_2}}: {{status}} ❌
+
+Requirements for Done:
+✓ All gates must show status: PASS
+✗ Cannot have: FAIL, CONCERN, or WAIVED
+
+Please resolve QA issues before marking story as Done.
+
+HALT execution.
+```
+
+**If QA Gates Pass:**
+```output
+✅ QA Gates Validation: PASSED
+
+All quality gates show PASS status. Story is ready for Done transition.
+```
+
+### Phase 3: Load or Fetch Available Statuses
+
+#### Step 6: Check for Cached Statuses in jira-conf.md
+
+**Action:** Check if statuses are already cached in configuration
+
+- [ ] Read `docs/jira-conf.md` file
+- [ ] Look for "Available Story Statuses" section
+- [ ] Check if section exists and contains status list (lines starting with `-`)
+- [ ] If statuses found: parse and use them (go to Step 8)
+- [ ] If statuses NOT found: proceed to Step 7 to fetch from Jira
+
+**Expected Cached Format:**
+```markdown
+## Available Story Statuses
+
+- To Do
+- In Progress
+- Done
+```
+
+#### Step 7: Fetch Statuses from Jira via MCP (If Not Cached)
+
+**Action:** Query Jira MCP to get available statuses for the project
+
+- [ ] Call Jira MCP to get project statuses or workflow information
+- [ ] Extract list of status names from response
+- [ ] Build formatted status list
+- [ ] Proceed to Step 7b to cache them
+
+**MCP Call Options:**
+
+Option 1 - Get statuses from an existing issue:
+```
+Tool: mcp_gitkraken_issues_get_detail
+Parameters:
+  - provider: jira
+  - issue_id: {{jira_key}}
+  - project_name: {{project_key}}
+```
+
+Option 2 - Query project metadata (if available in MCP):
+```
+Tool: mcp_jira_get_project_statuses (if exists)
+Parameters:
+  - project_key: {{project_key}}
+```
+
+**Extract Statuses from Response:**
+```json
+{
+  "transitions": [
+    {"id": "10", "name": "To Do"},
+    {"id": "20", "name": "In Progress"},
+    {"id": "30", "name": "Done"}
+  ]
+}
+```
+
+- Parse transition names or status names
+- Deduplicate status list
+- Sort alphabetically or by workflow order
+
+**If MCP Call Fails:**
+```output
+❌ Unable to retrieve statuses from Jira via MCP.
+
+Possible causes:
+- MCP connection issue
+- Invalid Jira credentials
+- No issues exist in project to query
+
+Manual Configuration Required:
+Please add statuses manually to `docs/jira-conf.md`:
+
+## Available Story Statuses
+
+- To Do
+- In Progress
+- Done
+
+HALT execution.
+```
+
+#### Step 7b: Cache Statuses in jira-conf.md
+
+**Action:** Write fetched statuses to configuration file for future use
+
+- [ ] Read current `docs/jira-conf.md` content
+- [ ] Locate insertion point (after Jira URL, before closing notes)
+- [ ] Format statuses as markdown list
+- [ ] Insert "Available Story Statuses" section
+- [ ] Write updated content back to file
+
+**Insert Format:**
+```markdown
+## Available Story Statuses
+
+_Automatically retrieved from Jira on {{date}}. Edit this list if your workflow changes._
+
+{{#each statuses}}
+- {{name}}
+{{/each}}
+```
+
+**Success Output:**
+```output
+✅ Statuses retrieved from Jira and cached in jira-conf.md
+
+Found {{status_count}} statuses:
+{{#each statuses}}
+- {{name}}
+{{/each}}
+
+These statuses are now cached for future use.
+```
+
+#### Step 8: Present Available Statuses to User
+
+```elicit
+path: Select target status
+format: |
+  Story "{{story_title}}" is ready for status update.
+  
+  Current Status: {{current_status}}
+  Jira Issue: {{jira_key}}
+  
+  Available Statuses:
+  {{#each statuses}}
+  {{@index}}. {{name}}
+  {{/each}}
+  
+  Select target status (enter number):
+```
+
+**Action:** Wait for user selection and validate input
+
+- [ ] Display numbered list of statuses from jira-conf.md
+- [ ] Accept user input (number)
+- [ ] Validate selection is within range (1 to status count)
+- [ ] Extract selected status name
+
+#### Step 9: Confirm Transition
+
+```elicit
+path: Confirm status update
+format: |
+  Ready to update story in Jira:
+  
+  Story: {{story_title}}
+  Jira Issue: {{jira_key}}
+  Current Status: {{current_status}}
+  New Status: {{selected_status}}
+  
+  All Prerequisites Validated:
+  ✅ All tasks completed
+  {{#if qaGatesRequired}}✅ QA gates passed{{/if}}
+  ✅ Jira connection configured
+  
+  Proceed with update? (yes/no):
+```
+
+### Phase 4: Execute Jira Transition
+
+#### Step 10: Update Jira Issue Status
+
+**Action:** Use MCP Jira integration to update the issue status
+
+- [ ] Extract Jira issue key from story metadata
+- [ ] Extract selected status name from user choice
+- [ ] Call Jira MCP to update issue status
+- [ ] Add automation comment
+- [ ] Verify status update succeeded
+
+**MCP Call Pattern:**
+```
+Tool: mcp_gitkraken_issues_update_status (or equivalent Jira MCP tool)
+Parameters:
+  - provider: {{jira_provider}}
+  - issue_id: {{jira_key}}
+  - status: {{selected_status_name}}
+  - comment: "Story status updated via BMAD automation"
+```
+
+**Expected Response:**
+```json
+{
+  "success": true,
+  "issue_key": "PROJ-123",
+  "new_status": "Done",
+  "transition_date": "2025-12-11T10:30:00Z"
+}
+```
+
+#### Step 11: Update Local Story File
+
+**Action:** Update the status field in the story document
+
+- [ ] Read current story file content
+- [ ] Locate status field line
+- [ ] Replace status value with new status
+- [ ] Write updated content back to file
+- [ ] Preserve all other content unchanged
+
+**Update Pattern:**
+```markdown
+Before:
+**Status:** Ready for Review
+
+After:
+**Status:** Done
+```
+
+**File Update Logic:**
+- Use precise string replacement
+- Match exact indentation and formatting
+- Only modify status field
+- Preserve markdown structure
+
+### Phase 5: Completion & Reporting
+
+#### Step 12: Generate Completion Report
+
+**Action:** Provide clear confirmation of completed action
+
+```output
+✅ Story Status Updated Successfully
+
+Story: {{story_title}}
+Jira Issue: {{jira_key}}
+
+Previous Status: {{old_status}}
+New Status: {{new_status}}
+
+Updated:
+✅ Jira issue transitioned
+✅ Local story file updated
+
+Timestamp: {{completion_timestamp}}
+
+Next Steps:
+{{#if new_status_is_done}}
+- Story is marked as Done
+- Implementation cycle complete
+{{else}}
+- Continue workflow in new status
+- Monitor story progress in Jira
+{{/if}}
+```
+
+**Completion Checklist:**
+- [ ] Jira issue successfully transitioned
+- [ ] Local story file status updated
+- [ ] User notified of completion
+- [ ] No errors or warnings
+
+## Error Handling
+
+### Common Errors and Solutions
+
+**Error: Missing Jira Issue Key**
+```output
+❌ Story file does not contain Jira issue key.
+
+Expected format:
+**Jira Issue Key:** PROJ-123
+
+Please sync story to Jira first using sync-story-to-jira task.
+```
+
+**Error: Invalid Transition**
+```output
+❌ Selected transition not available for current issue status.
+
+Available transitions for {{current_status}}:
+- {{transition_1}}
+- {{transition_2}}
+
+Please select a valid transition.
+```
+
+**Error: Jira Connection Failed**
+```output
+❌ Unable to connect to Jira.
+
+Possible causes:
+- Invalid credentials in jira-preferences.md
+- Network connectivity issues
+- Jira API rate limit exceeded
+
+Please verify Jira configuration and try again.
+```
+
+**Error: Permission Denied**
+```output
+❌ Insufficient permissions to transition issue {{jira_key}}.
+
+Required permissions:
+- Transition Issues
+- Edit Issues
+
+Please contact your Jira administrator.
+```
+
+## Output Format
+
+### Success Output Template
+```markdown
+## Story Status Update Report
+
+**Story:** {{story_title}}
+**Jira Issue:** {{jira_key}}
+**File:** {{story_file_path}}
+
+### Validation Results
+✅ All tasks completed ({{task_count}}/{{task_count}})
+{{#if qaGatesPresent}}✅ QA gates passed ({{gate_count}}/{{gate_count}}){{/if}}
+
+### Transition Details
+- **Previous Status:** {{old_status}}
+- **New Status:** {{new_status}}
+- **Transition Date:** {{timestamp}}
+- **Updated By:** BMAD Automation
+
+### Actions Completed
+1. ✅ Validated local task completion
+{{#if qaGatesPresent}}2. ✅ Validated QA gate requirements{{/if}}
+3. ✅ Transitioned Jira issue
+4. ✅ Updated local story file
+
+---
+Story successfully transitioned to {{new_status}}.
+```
+
+## Configuration Reference
+
+### Required Configuration Files
+
+**`docs/jira-conf.md`:**
+```markdown
+# Jira Project Configuration
+
+**Project Key:** PM
+**Project Name:** Prueba MCP
+**Cloud ID:** 3b04e1a3-a260-4679-bdc8-0440507fbe26
+**Jira URL:** https://siesa-test-sandbox.atlassian.net
+```
+
+**`.bmad-core/data/jira-preferences.md`:**
+Must contain Jira connection details and authentication credentials.
+
+### How Statuses are Managed (Smart Caching)
+
+This task uses **intelligent status caching** to balance efficiency and accuracy:
+
+**Flow:**
+1. First checks if statuses are cached in `docs/jira-conf.md`
+2. If cached: Uses cached statuses (fast, no API calls)
+3. If NOT cached: Queries Jira via MCP to fetch current statuses
+4. Caches fetched statuses in `jira-conf.md` for future use
+5. Presents statuses to user for selection
+
+**Benefits:**
+- ✅ **First-run auto-discovery**: Automatically fetches statuses from Jira on first use
+- ✅ **Token-efficient**: Cached statuses avoid repeated MCP calls
+- ✅ **Always accurate**: Sources from Jira, not hardcoded
+- ✅ **Transparent**: Cached in readable markdown format
+- ✅ **Updatable**: Edit `jira-conf.md` if workflow changes
+- ✅ **Zero manual setup**: No need to manually configure statuses
+
+**Refresh Cached Statuses:**
+If your Jira workflow changes, you can:
+- Delete the "Available Story Statuses" section from `jira-conf.md` and re-run command to re-fetch
+- Or manually edit the status list in `jira-conf.md`
+
+**Technical Note:**
+Statuses are retrieved by querying an existing Jira issue's available transitions. This ensures only valid, workflow-approved statuses are presented.
+
+## Notes
+
+- This task is non-destructive - it only updates status, not content
+- QA gate validation only enforced when transitioning to "Done"
+- Task completion must be 100% before any transition
+- Local story file is updated to match Jira status
+- All transitions are logged in Jira with automation comment
+- User can configure custom transitions per project
+- Task validates before executing to prevent invalid state changes