BMAD-METHOD/bmad-agent/tasks/dynamic-claude-md-update-task.md

# Dynamic CLAUDE.md Update Task

## Purpose
Automatically generate and implement improvements to CLAUDE.md based on methodology learning and pattern recognition, with robust approval workflows for quality control.

## When to Execute
- After pattern recognition identifies significant improvement opportunities
- Following successful validation of methodology improvements
- When effectiveness metrics indicate CLAUDE.md guidance needs updates
- After accumulating sufficient learning data from multiple projects

## Update Categories

### 1. Automatic Updates (No Approval Required)

**Metrics and Performance Data:**
- Update effectiveness metrics with new measurement data
- Add successful pattern examples to guidance sections
- Include validated techniques in best practices
- Update git history references and milestone tracking

**Documentation Corrections:**
- Fix typos, formatting issues, or broken links
- Update outdated command examples or syntax
- Correct factual errors identified through usage
- Improve clarity of existing instructions without changing meaning

### 2. Minor Updates (Streamlined Approval)

**Process Refinements:**
- Add proven workflow optimizations
- Include validated efficiency improvements
- Integrate successful persona interaction patterns
- Update template or task recommendations

**Guidance Enhancements:**
- Add specific examples of successful implementations
- Include troubleshooting guidance for common issues
- Expand on existing best practices with detailed approaches
- Clarify ambiguous instructions based on user feedback

### 3. Major Updates (Full Approval Required)

**Methodology Changes:**
- Fundamental changes to workflow or process
- New personas or significant persona modifications
- Structural changes to task organization or execution
- Major revisions to self-improvement philosophy

**Architecture Modifications:**
- Changes to core BMAD principles or foundations
- New measurement frameworks or success criteria
- Significant updates to improvement processes
- Integration of new tools or technologies

## Dynamic Update Framework

### 1. Change Detection and Analysis

**Pattern-Based Improvements:**
```
Improvement Source: [Pattern Recognition/User Feedback/Performance Data]
Current CLAUDE.md Section: [Specific section requiring update]
Identified Issue: [What needs improvement]
Proposed Change: [Specific modification]
Expected Benefit: [How this improves methodology effectiveness]
Change Category: [Automatic/Minor/Major]
```

**Evidence Compilation:**
- Quantified performance improvements from new practices
- User feedback supporting need for change
- Pattern recognition data showing consistent benefits
- Validation results from testing improved approaches

### 2. Automated Change Generation

**Content Analysis:**
- Scan CLAUDE.md for outdated information or practices
- Identify sections that could benefit from new learnings
- Compare current guidance with validated improvements
- Flag inconsistencies between documentation and successful practices

**Improvement Suggestions:**
- Generate specific text modifications with tracked changes
- Propose new sections or organizational improvements
- Suggest removal of outdated or ineffective guidance
- Recommend integration of successful new approaches

**Impact Assessment:**
- Evaluate potential effects on existing workflows
- Assess compatibility with current persona instructions
- Identify dependencies or related changes needed
- Estimate implementation effort and risk level

### 3. Approval Workflow System

**Automatic Approval Process:**
```
Category: Automatic Updates
Criteria:
- Purely factual corrections or data updates
- Formatting or presentation improvements
- Addition of validated examples or metrics
- No changes to methodology or process

Implementation: Immediate with notification
Rollback: Automatic if issues detected
```

**Minor Update Approval:**
```
Category: Minor Updates
Criteria:
- Process refinements based on proven patterns
- Guidance enhancements that don't change core methodology
- Addition of new best practices or techniques
- Clarifications that improve understanding

Approval Process:
1. Present proposed changes with supporting evidence
2. Allow 24-48 hour review period for feedback
3. Implement if no objections raised
4. Monitor for issues and adjust if needed

Rollback: Available if problems arise
```

**Major Update Approval:**
```
Category: Major Updates
Criteria:
- Fundamental methodology changes
- New framework components or architecture
- Significant process modifications
- Changes affecting multiple personas or workflows

Approval Process:
1. Present comprehensive change proposal
2. Include detailed impact analysis and risk assessment
3. Provide implementation plan with rollback procedures
4. Require explicit user approval before proceeding
5. Implement in stages with validation checkpoints

Validation: Required at each implementation stage
Rollback: Full rollback plan mandatory
```

### 4. Implementation Process

**Staged Rollout:**
- Implement changes incrementally to validate effectiveness
- Monitor metrics and feedback during rollout
- Adjust implementation based on real-world results
- Complete rollout only after validation confirms benefits

**Version Control Integration:**
- Create git branches for major updates
- Tag versions for easy rollback capability
- Document all changes in improvement log
- Maintain history of CLAUDE.md evolution

**Quality Assurance:**
- Validate that changes don't conflict with existing guidance
- Ensure consistency across all BMAD documentation
- Test updated guidance with representative scenarios
- Confirm integration with persona instructions and tasks

### 5. Monitoring and Validation

**Effectiveness Tracking:**
- Monitor methodology performance after updates
- Compare metrics before and after changes
- Collect user feedback on updated guidance
- Track whether changes achieve expected benefits

**Issue Detection:**
- Automated monitoring for decreased performance
- User feedback channels for reporting problems
- Pattern recognition to identify new issues
- Regular health checks on methodology effectiveness

**Continuous Refinement:**
- Adjust updates based on post-implementation data
- Refine approval processes based on experience
- Improve change detection algorithms
- Enhance validation procedures

## CLAUDE.md Update Templates

### Automatic Update Template
```
## Automatic CLAUDE.md Update

**Section Updated:** [Specific section]
**Update Type:** [Metrics/Examples/Corrections]
**Changes Made:**
- [Specific change 1]
- [Specific change 2]

**Supporting Data:**
- [Evidence for update]

**Implementation Date:** [Timestamp]
**Validation:** [Automatic monitoring active]
```

### Minor Update Proposal
```
## Minor CLAUDE.md Update Proposal

**Section:** [Target section]
**Proposed Changes:**
[Detailed description of modifications]

**Justification:**
- Pattern recognition data: [Supporting evidence]
- Performance improvement: [Quantified benefits]
- User feedback: [Relevant feedback]

**Risk Assessment:** [Low/Medium impact analysis]
**Implementation Plan:** [Step-by-step approach]

**Approval Status:** [Pending/Approved/Rejected]
**Review Period:** [24-48 hours]
```

### Major Update Proposal
```
## Major CLAUDE.md Update Proposal

**Title:** [Descriptive title for major change]

**Current State:**
[Description of existing methodology/guidance]

**Proposed Changes:**
[Comprehensive description of modifications]

**Impact Analysis:**
- Affected personas: [List]
- Workflow changes: [Description]
- Training requirements: [If any]
- Compatibility issues: [None/Description]

**Benefits:**
- Quantified improvements: [Specific metrics]
- User value: [How this helps users]
- Methodology evolution: [Strategic advancement]

**Risk Mitigation:**
- Potential issues: [Identified risks]
- Mitigation strategies: [How to address]
- Rollback plan: [Detailed procedure]

**Implementation Timeline:**
- Phase 1: [Initial steps]
- Phase 2: [Validation phase]
- Phase 3: [Full implementation]

**Success Criteria:**
[How to measure successful implementation]

**Approval Required:** YES
**User Review:** [Comprehensive evaluation needed]
```

## Integration with Learning Systems

This dynamic update capability creates a truly **living methodology** that:

- **Evolves Based on Evidence**: Changes driven by data and proven results
- **Maintains Quality Control**: Robust approval processes prevent degradation
- **Enables Rapid Improvement**: Quick implementation of validated enhancements
- **Preserves Stability**: Careful change management prevents disruption
- **Supports Continuous Learning**: Methodology improves automatically over time

The result is CLAUDE.md that stays current with methodology advances while maintaining reliability and user trust through careful change management.