# JIRA Cleanup Utility ## Purpose Specialized utility for safe and efficient JIRA cleanup operations that maintain BMAD documentation as the source of truth while preserving data integrity and team productivity. ## Safety-First Design Principles ### 1. Preview Before Action **Every cleanup operation MUST show what will change before execution** ``` PREVIEW MODE (Default): - Generate detailed cleanup report - Show all affected issues and changes - Calculate impact and risk assessment - Require explicit confirmation EXECUTION MODE (After approval): - Create backup automatically - Apply changes incrementally - Verify each step - Maintain audit trail ``` ### 2. Progressive Risk Management **Operations are categorized by risk level with appropriate safeguards** ``` LOW RISK (Auto-approved): ✅ Field value normalization ✅ Missing field population ✅ Link updates ✅ Status corrections MEDIUM RISK (Confirmation required): ⚠️ Issue archival ⚠️ Sprint closures ⚠️ Bulk status changes ⚠️ Attachment optimization HIGH RISK (Manual approval required): 🔒 Issue deletion 🔒 Epic consolidation 🔒 Major field changes 🔒 Data migration ``` ### 3. Comprehensive Backup Strategy **Automatic backup before any destructive operation** ```json { "backup_strategy": { "automatic": true, "verification": "hash_check", "retention": "30_days", "recovery_time": "< 1_hour" } } ``` ## Core Cleanup Operations ### Stale Issue Management #### Detection Criteria ```jql # Issues not updated in specified threshold updated < -{threshold}d AND status != Closed # Issues in completed status but not archived status in (Done, Resolved, Closed) AND updated < -30d # Issues abandoned mid-sprint sprint in closedSprints() AND status not in (Done, Resolved, Closed) ``` #### Safe Operations - **Archive**: Move to archive project preserving history - **Status Update**: Change to appropriate final status - **Sprint Cleanup**: Remove from active sprints - **Metadata Update**: Add cleanup tags and notes #### Risk Mitigation - Export issue data before changes - Preserve comment history - Maintain issue relationships - Update dependent references ### Orphan Resolution #### BMAD Alignment Check ```bash # Cross-reference JIRA issues with BMAD files find .bmad-core -name "*.storyimpl.md" -exec grep -l "PROJ-" {} \; jira export issues --jql "project = PROJ" --fields "key,summary" ``` #### Resolution Strategies 1. **Create Missing BMAD Documentation** - Generate story template from JIRA issue - Populate with existing JIRA data - Link bidirectionally - Tag as "retroactive documentation" 2. **Update Broken References** - Find moved/renamed BMAD files - Update JIRA issue links - Verify reference integrity - Document changes in audit trail 3. **Archive Legacy Items** - Identify pre-BMAD adoption issues - Export for historical record - Move to legacy archive project - Update status to reflect archival ### Duplicate Detection and Consolidation #### Similarity Analysis ```python def calculate_similarity(issue1, issue2): factors = { 'title_similarity': fuzzy_match(issue1.summary, issue2.summary), 'description_overlap': content_similarity(issue1.description, issue2.description), 'component_match': set_intersection(issue1.components, issue2.components), 'timeline_proximity': time_difference(issue1.created, issue2.created), 'reporter_pattern': same_reporter(issue1.reporter, issue2.reporter) } return weighted_score(factors) ``` #### Consolidation Process 1. **High Confidence (>90%)** - Automatic merge preparation - Transfer comments and attachments - Update all references - Close duplicate with link 2. **Medium Confidence (70-90%)** - Generate comparison report - Request manual review - Provide merge recommendations - Queue for team decision 3. **Low Confidence (50-70%)** - Flag for investigation - Add relationship links - Document similarities - Monitor for patterns ### Data Quality Improvement #### Field Completion Analysis ```sql -- Issues missing required fields SELECT key, summary, project FROM issues WHERE priority IS NULL OR component IS NULL OR story_points IS NULL -- Issues with invalid values SELECT key, field_name, field_value FROM custom_field_values WHERE field_value NOT IN (allowed_values) ``` #### Intelligent Field Population - **Priority Assignment**: Based on epic priority and issue type - **Component Inference**: From epic, labels, or description analysis - **Story Points Estimation**: ML-based estimation from similar issues - **Status Normalization**: Align with current workflow states ### Sprint Hygiene Maintenance #### Sprint Lifecycle Management ```python def analyze_sprint_health(sprint): metrics = { 'completion_rate': calculate_completion(sprint), 'days_since_end': days_since(sprint.end_date), 'incomplete_items': count_incomplete(sprint), 'velocity_impact': calculate_velocity_impact(sprint) } return cleanup_recommendations(metrics) ``` #### Cleanup Actions - **Close Completed Sprints**: Update status and archive artifacts - **Move Incomplete Items**: Transfer to appropriate future sprint or backlog - **Update Sprint Reports**: Generate final metrics and documentation - **Clean Sprint Metadata**: Remove temporary fields and assignments ### Attachment Optimization #### Storage Analysis ```bash # Find large attachments jira attachment list --size-threshold 10MB --age-threshold 90d # Identify duplicates jira attachment dedupe --project PROJ --similarity-threshold 95% # Analyze unused attachments jira attachment audit --linked-only false --age-threshold 180d ``` #### Optimization Strategies - **Compression**: Reduce file sizes without quality loss - **Deduplication**: Remove identical files across issues - **Archival**: Move old attachments to cold storage - **Format Conversion**: Convert to more efficient formats ## Execution Workflows ### Standard Cleanup Workflow #### Phase 1: Analysis and Planning ```bash # Generate comprehensive cleanup report jira cleanup analyze --project PROJ --output report.md # Review with team jira cleanup review --report report.md --stakeholders team-leads # Get approvals jira cleanup approve --report report.md --required-approvers 2 ``` #### Phase 2: Backup and Preparation ```bash # Create comprehensive backup jira cleanup backup --project PROJ --include-attachments # Verify backup integrity jira cleanup verify-backup --backup-id latest # Notify stakeholders jira cleanup notify --phase start --recipients all-users ``` #### Phase 3: Incremental Execution ```bash # Execute low-risk operations first jira cleanup execute --phase low-risk --auto-approve # Execute medium-risk with confirmations jira cleanup execute --phase medium-risk --require-confirmation # Execute high-risk with manual oversight jira cleanup execute --phase high-risk --manual-mode ``` #### Phase 4: Verification and Documentation ```bash # Verify all changes jira cleanup verify --compare-before-after # Generate audit trail jira cleanup audit-trail --session-id latest # Update documentation jira cleanup document --update-wiki --notify-team ``` ### Emergency Cleanup Workflow #### Rapid Response Process ```bash # Quick analysis jira cleanup quick-scan --project PROJ --critical-only # Immediate safe operations jira cleanup emergency --safe-only --auto-backup # Generate emergency report jira cleanup emergency-report --stakeholders executives ``` ## Configuration and Customization ### Cleanup Rules Configuration ```yaml # jira-project-config.yml cleanup section cleanup_rules: stale_threshold: days: 90 exclude_statuses: [Blocked, Waiting] exclude_labels: [keep-active, important] orphan_detection: require_bmad_reference: true auto_create_documentation: false archive_legacy_items: true duplicate_detection: similarity_threshold: 0.8 auto_merge_threshold: 0.95 manual_review_threshold: 0.7 data_quality: required_fields: [priority, component, story_points] auto_populate: true validation_rules: strict backup_settings: automatic: true retention_days: 30 verify_integrity: true compression: true approval_workflow: low_risk_auto_approve: true medium_risk_reviewers: [team-lead, project-manager] high_risk_reviewers: [stakeholder, jira-admin] ``` ### Team-Specific Customizations ```yaml team_preferences: notification_channels: [email, slack, jira-notifications] cleanup_schedule: weekly review_frequency: monthly audit_retention: 1_year risk_tolerance: data_modification: conservative bulk_operations: moderate automated_decisions: low ``` ## Integration with MCP Tools ### JIRA MCP Operations for Cleanup #### Issue Management ```python # Get stale issues stale_issues = mcp.jira_search( jql=f"updated < -{threshold_days}d AND status != Closed", fields="key,summary,status,updated,assignee" ) # Archive issues for issue in stale_issues: mcp.jira_update_issue( issue_key=issue.key, fields={"status": "Archived", "resolution": "Archived"} ) ``` #### Bulk Operations ```python # Batch update for efficiency issue_updates = [ { "issue_key": issue.key, "fields": calculate_field_updates(issue) } for issue in issues_to_update ] mcp.jira_batch_update_issues(updates=issue_updates) ``` #### Field Management ```python # Detect custom fields epic_field = mcp.jira_search_fields(keyword="epic")[0] sprint_field = mcp.jira_search_fields(keyword="sprint")[0] # Update with discovered field IDs mcp.jira_update_issue( issue_key="PROJ-123", additional_fields={ epic_field.id: "PROJ-456", sprint_field.id: sprint_id } ) ``` ## Safety Mechanisms ### Rollback Capabilities #### Automatic Rollback Triggers - **Data integrity violations**: Broken relationships detected - **Performance degradation**: Query times exceed thresholds - **User complaints**: Team reports issues with changes - **Validation failures**: Post-change verification fails #### Manual Rollback Process ```bash # List available rollback points jira cleanup rollback --list-sessions # Rollback specific operation jira cleanup rollback --session-id cleanup-2024-01-24-001 --operation "Operation 3" # Full session rollback jira cleanup rollback --session-id cleanup-2024-01-24-001 --full # Verify rollback success jira cleanup verify --session-id cleanup-2024-01-24-001 --post-rollback ``` ### Error Handling and Recovery #### Graceful Failure Management ```python def execute_cleanup_operation(operation): try: # Create checkpoint checkpoint = create_checkpoint() # Execute operation result = operation.execute() # Verify success if not verify_operation(result): rollback_to_checkpoint(checkpoint) raise OperationError("Verification failed") return result except Exception as e: # Log error with context logger.error(f"Cleanup failed: {e}", extra={ "operation": operation.name, "checkpoint": checkpoint.id, "affected_issues": operation.issue_count }) # Attempt recovery recovery_result = attempt_recovery(operation, checkpoint) # Notify stakeholders notify_cleanup_failure(operation, e, recovery_result) raise ``` ## Performance Optimization ### Batch Processing Strategy ```python def process_large_cleanup(issues, batch_size=100): """Process cleanup in batches to avoid timeouts and memory issues""" for batch in chunk_issues(issues, batch_size): # Process batch batch_result = process_batch(batch) # Verify batch success verify_batch_result(batch_result) # Rate limiting sleep(batch_delay) # Progress reporting report_progress(len(batch_result), len(issues)) ``` ### Resource Management - **API Rate Limiting**: Respect JIRA API limits - **Memory Management**: Process large datasets in chunks - **Connection Pooling**: Reuse connections efficiently - **Caching**: Cache frequently accessed data ## Compliance and Audit ### Audit Trail Requirements - **Change Documentation**: Every modification logged - **Approval Records**: All approvals tracked with timestamps - **Data Lineage**: Track data movement and transformations - **Access Logs**: Record who performed what actions ### Regulatory Compliance - **Data Retention**: Comply with organizational policies - **Change Management**: Follow established procedures - **Access Control**: Enforce role-based permissions - **Recovery Planning**: Maintain disaster recovery capabilities This utility ensures JIRA cleanup operations are safe, efficient, and aligned with BMAD documentation while maintaining compliance and data integrity standards.