@cloudkinetix/bmad-enhanced/expansion-packs/ck-jira-integration/utils/jira-cleanup.md

Cloud-Kinetix enhanced fork of BMAD-METHOD - Breakthrough Method of Agile AI-driven Development with robust versioning and unified validation.

# 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.