diff --git a/src/modules/bmm/workflows/debug/README.md b/src/modules/bmm/workflows/debug/README.md
new file mode 100644
index 00000000..9ceac9b4
--- /dev/null
+++ b/src/modules/bmm/workflows/debug/README.md
@@ -0,0 +1,71 @@
+# Debug Workflows
+
+This directory contains all debug-related workflows for systematic bug analysis, root cause investigation, and defect resolution.
+
+## Available Workflows
+
+### Core Inspection Workflows
+
+- **`inspect/`** - Comprehensive Fagan inspection (6-phase systematic defect analysis)
+- **`quick-debug/`** - Rapid triage and initial assessment for simple issues
+- **`root-cause/`** - Focused root cause analysis using fishbone methodology
+- **`pattern-analysis/`** - Analyze code changes for defect patterns and systemic issues
+
+### Advanced Debugging Workflows
+
+- **`wolf-fence/`** - Binary search debugging to isolate bug location efficiently
+- **`delta-minimize/`** - Reduce failing test case to minimal reproduction
+- **`assert-analyze/`** - Analyze code for missing assertions and invariants
+- **`static-scan/`** - Comprehensive static analysis for common defects
+
+### Production Support Workflows
+
+- **`instrument/`** - Design strategic logging and monitoring points
+- **`walkthrough-prep/`** - Generate materials for code walkthrough sessions
+
+### Validation & Documentation
+
+- **`validate-fix/`** - Verify proposed fixes address root cause without side effects
+- **`debug-report/`** - Generate comprehensive debug reports from analysis sessions
+
+## Workflow Execution
+
+All workflows are executed through the Debug Agent (Diana) using the `*command` syntax:
+
+```
+*inspect - Execute Fagan inspection
+*quick-debug - Rapid triage
+*root-cause - Root cause analysis
+*validate-fix - Fix validation
+```
+
+## Workflow Structure
+
+Each workflow directory contains:
+
+- `workflow.yaml` - Workflow configuration and metadata
+- `instructions.md` - Step-by-step execution instructions
+- `template.yaml` or `template.md` - Output templates (if applicable)
+
+## Integration with Knowledge Base
+
+Workflows automatically load relevant knowledge fragments from `bmad/debug/knowledge/` based on the `debug-index.csv` index.
+
+## Tags and Categories
+
+Workflows are tagged for easy discovery:
+
+- `inspection` - Formal inspection methodologies
+- `analysis` - Root cause and pattern analysis
+- `automation` - Automated debugging tools
+- `production` - Production debugging support
+- `validation` - Fix and quality validation
+- `documentation` - Report generation
+
+## Best Practices
+
+1. Start with `quick-debug` for initial triage
+2. Use `inspect` for comprehensive analysis
+3. Execute `root-cause` when symptoms are clear but causes are unclear
+4. Run `validate-fix` before implementing any solution
+5. Generate `debug-report` to capture lessons learned
diff --git a/src/modules/bmm/workflows/debug/assert-analyze/instructions.md b/src/modules/bmm/workflows/debug/assert-analyze/instructions.md
new file mode 100644
index 00000000..bf23e10c
--- /dev/null
+++ b/src/modules/bmm/workflows/debug/assert-analyze/instructions.md
@@ -0,0 +1,333 @@
+# assertion-analysis
+
+Analyze code for missing assertions and defensive programming opportunities.
+
+## Context
+
+This task systematically identifies locations where assertions, preconditions, postconditions, and invariants should be added to catch bugs early and make code self-documenting. Assertions act as executable documentation and early warning systems for violations of expected behavior.
+
+## Task Execution
+
+### Phase 1: Code Analysis
+
+#### Identify Assertion Candidates
+
+**Function Boundaries:**
+
+1. **Preconditions** (Entry assertions):
+ - Parameter validation (null, range, type)
+ - Required state before execution
+ - Resource availability
+ - Permission/authorization checks
+
+2. **Postconditions** (Exit assertions):
+ - Return value constraints
+ - State changes completed
+ - Side effects occurred
+ - Resources properly managed
+
+3. **Invariants** (Always true):
+ - Class/object state consistency
+ - Data structure integrity
+ - Relationship maintenance
+ - Business rule enforcement
+
+**Critical Code Sections:**
+
+- Before/after state mutations
+- Around external system calls
+- At algorithm checkpoints
+- After complex calculations
+- Before resource usage
+
+### Phase 2: Assertion Category Analysis
+
+#### Type 1: Safety Assertions
+
+Prevent dangerous operations:
+
+```
+- Null/undefined checks before dereference
+- Array bounds before access
+- Division by zero prevention
+- Type safety before operations
+- Resource availability before use
+```
+
+#### Type 2: Correctness Assertions
+
+Verify algorithmic correctness:
+
+```
+- Loop invariants maintained
+- Sorted order preserved
+- Tree balance maintained
+- Graph properties held
+- Mathematical properties true
+```
+
+#### Type 3: Contract Assertions
+
+Enforce API contracts:
+
+```
+- Method preconditions met
+- Return values valid
+- State transitions legal
+- Callbacks invoked correctly
+- Events fired appropriately
+```
+
+#### Type 4: Security Assertions
+
+Validate security constraints:
+
+```
+- Input sanitization complete
+- Authorization verified
+- Rate limits enforced
+- Encryption applied
+- Audit trail updated
+```
+
+### Phase 3: Automated Detection
+
+#### Static Analysis Patterns
+
+**Missing Null Checks:**
+
+1. Identify all dereferences (obj.prop, obj->member)
+2. Trace back to find validation
+3. Flag unvalidated accesses
+
+**Missing Range Checks:**
+
+1. Find array/collection accesses
+2. Identify index sources
+3. Verify bounds checking exists
+
+**Missing State Validation:**
+
+1. Identify state-dependent operations
+2. Check for state verification
+3. Flag unverified state usage
+
+**Missing Return Validation:**
+
+1. Find function calls that can fail
+2. Check if return values are validated
+3. Flag unchecked returns
+
+### Phase 4: Assertion Generation
+
+#### Generate Appropriate Assertions
+
+**For Different Languages:**
+
+**JavaScript/TypeScript:**
+
+```javascript
+console.assert(condition, 'message');
+if (!condition) throw new Error('message');
+```
+
+**Python:**
+
+```python
+assert condition, "message"
+if not condition: raise AssertionError("message")
+```
+
+**Java:**
+
+```java
+assert condition : "message";
+if (!condition) throw new AssertionError("message");
+```
+
+**C/C++:**
+
+```c
+assert(condition);
+if (!condition) { /* handle error */ }
+```
+
+#### Assertion Templates
+
+**Null/Undefined Check:**
+
+```
+assert(param != null, "Parameter 'param' cannot be null");
+```
+
+**Range Check:**
+
+```
+assert(index >= 0 && index < array.length,
+ `Index ${index} out of bounds [0, ${array.length})`);
+```
+
+**State Check:**
+
+```
+assert(this.isInitialized, "Object must be initialized before use");
+```
+
+**Type Check:**
+
+```
+assert(typeof value === 'number', `Expected number, got ${typeof value}`);
+```
+
+**Invariant Check:**
+
+```
+assert(this.checkInvariant(), "Class invariant violated");
+```
+
+## Output Format
+
+````markdown
+# Assertion Analysis Report
+
+## Summary
+
+**Files Analyzed:** [count]
+**Current Assertions:** [count]
+**Recommended Additions:** [count]
+**Critical Missing:** [count]
+**Coverage Improvement:** [before]% → [after]%
+
+## Critical Assertions Needed
+
+### Priority 1: Safety Critical
+
+Location: [file:line]
+
+```[language]
+// Current code
+[code without assertion]
+
+// Recommended addition
+[assertion to add]
+[protected code]
+```
+````
+
+**Reason:** [Why this assertion is critical]
+**Risk Without:** [What could go wrong]
+
+### Priority 2: Correctness Verification
+
+[Similar format for each recommendation]
+
+### Priority 3: Contract Enforcement
+
+[Similar format for each recommendation]
+
+## Assertion Coverage by Component
+
+| Component | Current | Recommended | Priority |
+| ---------- | ------- | ----------- | -------------- |
+| [Module A] | [count] | [count] | [High/Med/Low] |
+| [Module B] | [count] | [count] | [High/Med/Low] |
+
+## Detailed Recommendations
+
+### File: [path/to/file]
+
+#### Function: [functionName]
+
+**Missing Preconditions:**
+
+```[language]
+// Add at function entry:
+assert(param1 != null, "param1 required");
+assert(param2 > 0, "param2 must be positive");
+```
+
+**Missing Postconditions:**
+
+```[language]
+// Add before return:
+assert(result.isValid(), "Result must be valid");
+```
+
+**Missing Invariants:**
+
+```[language]
+// Add after state changes:
+assert(this.items.length <= this.maxSize, "Size limit exceeded");
+```
+
+## Implementation Strategy
+
+### Phase 1: Critical Safety (Immediate)
+
+1. Add null checks for all pointer dereferences
+2. Add bounds checks for array accesses
+3. Add division by zero prevention
+
+### Phase 2: Correctness (This Sprint)
+
+1. Add algorithm invariants
+2. Add state validation
+3. Add return value checks
+
+### Phase 3: Comprehensive (Next Sprint)
+
+1. Add contract assertions
+2. Add security validations
+3. Add performance assertions
+
+## Configuration Recommendations
+
+### Development Mode
+
+```[language]
+// Enable all assertions
+ASSERT_LEVEL = "all"
+ASSERT_THROW = true
+ASSERT_LOG = true
+```
+
+### Production Mode
+
+```[language]
+// Keep only critical assertions
+ASSERT_LEVEL = "critical"
+ASSERT_THROW = false
+ASSERT_LOG = true
+```
+
+## Benefits Analysis
+
+### Bug Prevention
+
+- Catch [X]% more bugs in development
+- Reduce production incidents by [Y]%
+- Decrease debugging time by [Z]%
+
+### Documentation Value
+
+- Self-documenting code contracts
+- Clear API expectations
+- Explicit invariants
+
+### Testing Support
+
+- Faster test failure identification
+- Better test coverage visibility
+- Clearer failure messages
+
+```
+
+## Completion Criteria
+- [ ] Code analysis completed
+- [ ] Assertion candidates identified
+- [ ] Priority levels assigned
+- [ ] Assertions generated with proper messages
+- [ ] Implementation plan created
+- [ ] Configuration strategy defined
+- [ ] Benefits quantified
+```
diff --git a/src/modules/bmm/workflows/debug/assert-analyze/workflow.yaml b/src/modules/bmm/workflows/debug/assert-analyze/workflow.yaml
index e931c6f7..07fbda3f 100644
--- a/src/modules/bmm/workflows/debug/assert-analyze/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/assert-analyze/workflow.yaml
@@ -1,11 +1,25 @@
-# Assert Analyze Workflow Configuration
-name: "assert-analyze"
-description: "Analyze code for missing assertions and invariants to improve defensive programming."
-author: "Diana"
+# Debug Workflow: Assertion Analysis
+name: debug-assert-analyze
+description: "Analyze code for missing assertions and invariants. Suggests defensive programming improvements."
+author: "BMad"
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
installed_path: "{project-root}/bmad/bmm/workflows/debug/assert-analyze"
instructions: "{installed_path}/instructions.md"
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/common-defects.md"
-standalone: true
+template: false
+
+tags:
+ - debug
+ - assertions
+ - defensive-programming
+ - prevention
+
+execution_hints:
+ interactive: false
+ autonomous: true
+ iterative: false
diff --git a/src/modules/bmm/workflows/debug/debug-report/instructions.md b/src/modules/bmm/workflows/debug/debug-report/instructions.md
new file mode 100644
index 00000000..c7150bf6
--- /dev/null
+++ b/src/modules/bmm/workflows/debug/debug-report/instructions.md
@@ -0,0 +1,305 @@
+# debug-report-generation
+
+Generate comprehensive debug report from analysis session.
+
+## Context
+
+This task consolidates all debugging findings, analyses, and recommendations into a comprehensive report for stakeholders and future reference.
+
+## Task Execution
+
+### Step 1: Gather Session Data
+
+Collect all relevant information:
+
+1. Original bug description and symptoms
+2. Analysis performed (inspections, root cause, patterns)
+3. Evidence collected (logs, code, metrics)
+4. Findings and conclusions
+5. Fix attempts and results
+6. Recommendations made
+
+### Step 2: Structure Report
+
+Organize information hierarchically:
+
+1. Executive Summary (1 page max)
+2. Detailed Findings
+3. Technical Analysis
+4. Recommendations
+5. Appendices
+
+### Step 3: Generate Report Sections
+
+#### Executive Summary
+
+- Problem statement (1-2 sentences)
+- Impact assessment (users, systems, business)
+- Root cause (brief)
+- Recommended fix (high-level)
+- Estimated effort and risk
+
+#### Detailed Findings
+
+- Symptoms observed
+- Reproduction steps
+- Environmental factors
+- Timeline of issue
+
+#### Technical Analysis
+
+- Code examination results
+- Root cause analysis
+- Pattern detection findings
+- Test coverage gaps
+- Performance impacts
+
+#### Recommendations
+
+- Immediate fixes
+- Short-term improvements
+- Long-term prevention
+- Process enhancements
+
+### Step 4: Add Supporting Evidence
+
+Include relevant:
+
+- Code snippets
+- Log excerpts
+- Stack traces
+- Performance metrics
+- Test results
+- Screenshots (if applicable)
+
+### Step 5: Quality Review
+
+Ensure report:
+
+- Is technically accurate
+- Uses clear, concise language
+- Includes all critical information
+- Provides actionable recommendations
+- Is appropriately formatted
+
+## Output Format
+
+````markdown
+# Debug Analysis Report
+
+**Report ID:** DBG-[timestamp]
+**Date:** [current date]
+**Analyst:** Debug Agent (Diana)
+**Severity:** [Critical/High/Medium/Low]
+**Status:** [Resolved/In Progress/Pending]
+
+---
+
+## Executive Summary
+
+**Problem:** [1-2 sentence problem statement]
+
+**Impact:** [Quantified impact on users/system]
+
+**Root Cause:** [Brief root cause description]
+
+**Solution:** [High-level fix description]
+
+**Effort Required:** [Hours/Days estimate]
+**Risk Level:** [High/Medium/Low]
+
+---
+
+## 1. Problem Description
+
+### Symptoms
+
+[Detailed symptoms observed]
+
+### Reproduction
+
+1. [Step 1]
+2. [Step 2]
+3. [Expected vs Actual]
+
+### Environment
+
+- **System:** [OS, version]
+- **Application:** [Version, build]
+- **Dependencies:** [Relevant versions]
+- **Configuration:** [Key settings]
+
+### Timeline
+
+- **First Observed:** [Date/time]
+- **Frequency:** [How often]
+- **Last Occurrence:** [Date/time]
+
+---
+
+## 2. Technical Analysis
+
+### Root Cause Analysis
+
+[Detailed root cause with evidence]
+
+### Code Analysis
+
+```[language]
+// Problematic code
+[code snippet]
+```
+````
+
+**Issue:** [What's wrong with the code]
+
+### Pattern Analysis
+
+[Any patterns detected]
+
+### Test Coverage
+
+- **Current Coverage:** [percentage]
+- **Gap Identified:** [What's not tested]
+- **Risk Areas:** [Untested critical paths]
+
+---
+
+## 3. Impact Assessment
+
+### Severity Matrix
+
+| Aspect | Impact | Severity |
+| -------------- | ------------------- | -------------- |
+| Users Affected | [number/percentage] | [High/Med/Low] |
+| Data Integrity | [description] | [High/Med/Low] |
+| Performance | [metrics] | [High/Med/Low] |
+| Security | [assessment] | [High/Med/Low] |
+
+### Business Impact
+
+[Business consequences of the issue]
+
+---
+
+## 4. Solution & Recommendations
+
+### Immediate Fix
+
+```[language]
+// Corrected code
+[code snippet]
+```
+
+**Validation:** [How to verify fix works]
+
+### Short-term Improvements
+
+1. [Improvement 1]
+2. [Improvement 2]
+
+### Long-term Prevention
+
+1. [Strategy 1]
+2. [Strategy 2]
+
+### Process Enhancements
+
+1. [Process improvement]
+2. [Tool/automation suggestion]
+
+---
+
+## 5. Implementation Plan
+
+### Phase 1: Immediate (0-2 days)
+
+- [ ] Apply code fix
+- [ ] Add regression test
+- [ ] Deploy to staging
+
+### Phase 2: Short-term (1 week)
+
+- [ ] Improve test coverage
+- [ ] Add monitoring
+- [ ] Update documentation
+
+### Phase 3: Long-term (1 month)
+
+- [ ] Refactor problematic area
+- [ ] Implement prevention measures
+- [ ] Team training on issue
+
+---
+
+## 6. Verification & Testing
+
+### Test Cases
+
+1. **Test:** [Name]
+ **Steps:** [How to test]
+ **Expected:** [Result]
+
+### Regression Testing
+
+[Areas requiring regression testing]
+
+### Monitoring
+
+[Metrics to monitor post-fix]
+
+---
+
+## 7. Lessons Learned
+
+### What Went Wrong
+
+[Root causes beyond the code]
+
+### What Could Improve
+
+[Process/tool improvements]
+
+### Knowledge Sharing
+
+[Information to share with team]
+
+---
+
+## Appendices
+
+### A. Full Stack Traces
+
+[Complete error traces]
+
+### B. Log Excerpts
+
+[Relevant log entries]
+
+### C. Performance Metrics
+
+[Before/after metrics]
+
+### D. Related Issues
+
+[Links to similar problems]
+
+### E. References
+
+[Documentation, articles, tools used]
+
+---
+
+**Report Generated:** [timestamp]
+**Next Review:** [date for follow-up]
+
+```
+
+## Completion Criteria
+- [ ] All sections completed
+- [ ] Evidence included
+- [ ] Recommendations actionable
+- [ ] Report reviewed for accuracy
+- [ ] Formatted for readability
+- [ ] Ready for distribution
+```
diff --git a/src/modules/bmm/workflows/debug/debug-report/template.yaml b/src/modules/bmm/workflows/debug/debug-report/template.yaml
new file mode 100644
index 00000000..6cbc09d8
--- /dev/null
+++ b/src/modules/bmm/workflows/debug/debug-report/template.yaml
@@ -0,0 +1,339 @@
+#
+template:
+ id: defect-analysis-template-v1
+ name: Defect Analysis Report
+ version: 1.0
+ output:
+ format: markdown
+ filename: docs/debug/defect-{{defect_id}}.md
+ title: "Defect Analysis Report - DEF-{{defect_id}}"
+
+workflow:
+ mode: rapid
+ elicitation: false
+
+sections:
+ - id: header
+ title: Report Header
+ instruction: Generate report header with metadata
+ sections:
+ - id: metadata
+ title: Report Metadata
+ type: key-value
+ instruction: |
+ Defect ID: DEF-{{defect_id}}
+ Date: {{current_date}}
+ Analyst: {{analyst_name}}
+ Component: {{affected_component}}
+
+ - id: classification
+ title: Defect Classification
+ instruction: Categorize and classify the defect
+ sections:
+ - id: basic-info
+ title: Basic Information
+ type: key-value
+ instruction: |
+ Type: {{defect_type}}
+ Severity: {{severity_level}}
+ Priority: {{priority_level}}
+ Status: {{current_status}}
+ Environment: {{environment}}
+ - id: categorization
+ title: Categorization
+ type: key-value
+ instruction: |
+ Category: {{defect_category}}
+ Subcategory: {{defect_subcategory}}
+ Root Cause Type: {{root_cause_type}}
+ Detection Method: {{how_detected}}
+
+ - id: description
+ title: Defect Description
+ instruction: Comprehensive defect details
+ sections:
+ - id: summary
+ title: Summary
+ type: text
+ instruction: Brief one-line defect summary
+ - id: detailed
+ title: Detailed Description
+ type: paragraphs
+ instruction: Complete description of the defect and its behavior
+ - id: expected
+ title: Expected Behavior
+ type: paragraphs
+ instruction: What should happen under normal conditions
+ - id: actual
+ title: Actual Behavior
+ type: paragraphs
+ instruction: What actually happens when the defect occurs
+ - id: delta
+ title: Delta Analysis
+ type: paragraphs
+ instruction: Analysis of the difference between expected and actual
+
+ - id: reproduction
+ title: Reproduction
+ instruction: How to reproduce the defect
+ sections:
+ - id: prerequisites
+ title: Prerequisites
+ type: bullet-list
+ instruction: Required setup, data, or conditions before reproduction
+ - id: steps
+ title: Steps to Reproduce
+ type: numbered-list
+ instruction: Exact steps to trigger the defect
+ - id: frequency
+ title: Frequency
+ type: key-value
+ instruction: |
+ Reproducibility: {{reproducibility_rate}}
+ Occurrence Pattern: {{occurrence_pattern}}
+ Triggers: {{trigger_conditions}}
+
+ - id: technical-analysis
+ title: Technical Analysis
+ instruction: Deep technical investigation
+ sections:
+ - id: location
+ title: Code Location
+ type: key-value
+ instruction: |
+ File: {{file_path}}
+ Function/Method: {{function_name}}
+ Line Numbers: {{line_numbers}}
+ Module: {{module_name}}
+ - id: code
+ title: Code Snippet
+ type: code-block
+ instruction: |
+ [[LLM: Include the defective code with proper syntax highlighting]]
+ - id: mechanism
+ title: Defect Mechanism
+ type: paragraphs
+ instruction: Detailed explanation of how the defect works
+ - id: data-flow
+ title: Data Flow Analysis
+ type: paragraphs
+ instruction: How data flows through the defective code
+ - id: control-flow
+ title: Control Flow Analysis
+ type: paragraphs
+ instruction: Control flow issues contributing to the defect
+
+ - id: impact-assessment
+ title: Impact Assessment
+ instruction: Comprehensive impact analysis
+ sections:
+ - id: user-impact
+ title: User Impact
+ type: key-value
+ instruction: |
+ Affected Users: {{users_affected}}
+ User Experience: {{ux_impact}}
+ Workaround Available: {{workaround_exists}}
+ Workaround Description: {{workaround_details}}
+ - id: system-impact
+ title: System Impact
+ type: key-value
+ instruction: |
+ Performance: {{performance_impact}}
+ Stability: {{stability_impact}}
+ Security: {{security_impact}}
+ Data Integrity: {{data_impact}}
+ - id: business-impact
+ title: Business Impact
+ type: key-value
+ instruction: |
+ Revenue Impact: {{revenue_impact}}
+ Reputation Risk: {{reputation_risk}}
+ Compliance Issues: {{compliance_impact}}
+ SLA Violations: {{sla_impact}}
+
+ - id: root-cause
+ title: Root Cause
+ instruction: Root cause identification
+ sections:
+ - id: immediate
+ title: Immediate Cause
+ type: paragraphs
+ instruction: The direct cause of the defect
+ - id: underlying
+ title: Underlying Cause
+ type: paragraphs
+ instruction: The deeper systemic cause
+ - id: contributing
+ title: Contributing Factors
+ type: bullet-list
+ instruction: Factors that contributed to the defect
+ - id: prevention-failure
+ title: Prevention Failure
+ type: paragraphs
+ instruction: Why existing processes didn't prevent this defect
+
+ - id: fix-analysis
+ title: Fix Analysis
+ instruction: Solution proposals
+ sections:
+ - id: proposed-fix
+ title: Proposed Fix
+ type: code-block
+ instruction: |
+ [[LLM: Include the corrected code with proper syntax highlighting]]
+ - id: explanation
+ title: Fix Explanation
+ type: paragraphs
+ instruction: Detailed explanation of how the fix works
+ - id: alternatives
+ title: Alternative Solutions
+ type: numbered-list
+ instruction: Other possible solutions with pros/cons
+ - id: tradeoffs
+ title: Trade-offs
+ type: bullet-list
+ instruction: Trade-offs of the chosen solution
+
+ - id: testing-strategy
+ title: Testing Strategy
+ instruction: Comprehensive test plan
+ sections:
+ - id: unit-tests
+ title: Unit Tests Required
+ type: checkbox-list
+ instruction: Unit tests to validate the fix
+ - id: integration-tests
+ title: Integration Tests Required
+ type: checkbox-list
+ instruction: Integration tests needed
+ - id: regression-tests
+ title: Regression Tests Required
+ type: checkbox-list
+ instruction: Regression tests to ensure no breaks
+ - id: edge-cases
+ title: Edge Cases to Test
+ type: bullet-list
+ instruction: Edge cases that must be tested
+ - id: performance-tests
+ title: Performance Tests
+ type: bullet-list
+ instruction: Performance tests if applicable
+
+ - id: risk-assessment
+ title: Risk Assessment
+ instruction: Fix implementation risks
+ sections:
+ - id: fix-risk
+ title: Fix Risk
+ type: key-value
+ instruction: |
+ Implementation Risk: {{implementation_risk}}
+ Regression Risk: {{regression_risk}}
+ Side Effects: {{potential_side_effects}}
+ - id: mitigation
+ title: Mitigation Strategy
+ type: paragraphs
+ instruction: How to mitigate identified risks
+ - id: rollback
+ title: Rollback Plan
+ type: numbered-list
+ instruction: Steps to rollback if fix causes issues
+
+ - id: quality-metrics
+ title: Quality Metrics
+ instruction: Defect and code quality metrics
+ sections:
+ - id: defect-metrics
+ title: Defect Metrics
+ type: key-value
+ instruction: |
+ Escape Stage: {{escape_stage}}
+ Detection Time: {{time_to_detect}}
+ Fix Time: {{time_to_fix}}
+ Test Coverage Before: {{coverage_before}}
+ Test Coverage After: {{coverage_after}}
+ - id: code-metrics
+ title: Code Quality Metrics
+ type: key-value
+ instruction: |
+ Cyclomatic Complexity: {{complexity_score}}
+ Code Duplication: {{duplication_percentage}}
+ Technical Debt: {{tech_debt_impact}}
+
+ - id: prevention-strategy
+ title: Prevention Strategy
+ instruction: How to prevent similar defects
+ sections:
+ - id: immediate-prevention
+ title: Immediate Prevention
+ type: bullet-list
+ instruction: Quick wins to prevent recurrence
+ - id: longterm-prevention
+ title: Long-term Prevention
+ type: bullet-list
+ instruction: Strategic prevention measures
+ - id: process-improvements
+ title: Process Improvements
+ type: bullet-list
+ instruction: Process changes to prevent similar defects
+ - id: tool-enhancements
+ title: Tool Enhancements
+ type: bullet-list
+ instruction: Tool improvements needed
+
+ - id: related-information
+ title: Related Information
+ instruction: Additional context
+ optional: true
+ sections:
+ - id: similar-defects
+ title: Similar Defects
+ type: bullet-list
+ instruction: Links to similar defects in the system
+ - id: related-issues
+ title: Related Issues
+ type: bullet-list
+ instruction: Related tickets or issues
+ - id: dependencies
+ title: Dependencies
+ type: bullet-list
+ instruction: Dependencies affected by this defect
+ - id: documentation
+ title: Documentation Updates Required
+ type: bullet-list
+ instruction: Documentation that needs updating
+
+ - id: action-items
+ title: Action Items
+ instruction: Tasks and assignments
+ sections:
+ - id: actions-table
+ title: Action Items Table
+ type: table
+ columns: [Action, Owner, Due Date, Status]
+ instruction: |
+ [[LLM: Create table with specific action items, owners, and dates]]
+
+ - id: approval
+ title: Approval & Sign-off
+ instruction: Review and approval tracking
+ sections:
+ - id: signoff
+ title: Sign-off
+ type: key-value
+ instruction: |
+ Developer: {{developer_name}} - {{developer_date}}
+ QA: {{qa_name}} - {{qa_date}}
+ Lead: {{lead_name}} - {{lead_date}}
+
+ - id: footer
+ title: Report Footer
+ instruction: Closing metadata
+ sections:
+ - id: timestamps
+ title: Report Timestamps
+ type: key-value
+ instruction: |
+ Report Generated: {{generation_timestamp}}
+ Last Updated: {{last_update}}
diff --git a/src/modules/bmm/workflows/debug/debug-report/workflow.yaml b/src/modules/bmm/workflows/debug/debug-report/workflow.yaml
index 445921a6..43de7f29 100644
--- a/src/modules/bmm/workflows/debug/debug-report/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/debug-report/workflow.yaml
@@ -1,11 +1,70 @@
-# Debug Report Workflow Configuration
-name: "debug-report"
-description: "Generate comprehensive debug report from current session with findings and recommendations."
-author: "Diana"
+# Debug Workflow: Debug Report Generation
+name: debug-report
+description: "Generate comprehensive debug report consolidating all findings, analyses, and recommendations from debugging session."
+author: "BMad Core"
+version: "2.0"
+# BMAD Core Configuration
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
installed_path: "{project-root}/bmad/bmm/workflows/debug/debug-report"
instructions: "{installed_path}/instructions.md"
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
-standalone: true
+template: "{installed_path}/template.yaml"
+
+# Output configuration
+default_output_file: "{output_folder}/debug/debug-summary-{{date}}.md"
+
+# Knowledge Base Requirements (BMAD Core)
+knowledge_dependencies:
+ - "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
+ - "{project-root}/bmad/bmm/knowledge/debug/common-defects.md"
+
+tags:
+ - debug
+ - documentation
+ - reporting
+ - bmad-core
+
+execution_hints:
+ interactive: false
+ autonomous: true
+ iterative: false
+ validation_required: true
+ comprehensive: true
+
+# BMAD Core Workflow Steps
+steps:
+ - id: "load_config"
+ name: "Load Configuration"
+ type: "config"
+ required: true
+
+ - id: "load_knowledge"
+ name: "Load Knowledge Base"
+ type: "knowledge"
+ dependencies: "knowledge_dependencies"
+ required: true
+
+ - id: "execute_workflow"
+ name: "Generate Debug Report"
+ type: "workflow"
+ source: "instructions"
+ template: "template"
+ required: true
+ sections: ["executive-summary", "findings", "analysis", "recommendations", "lessons-learned"]
+
+ - id: "validate_output"
+ name: "Validate Report Quality"
+ type: "validation"
+ required: true
+ criteria: ["completeness", "clarity", "actionability", "professional-format"]
+
+ - id: "save_output"
+ name: "Save Debug Report"
+ type: "output"
+ destination: "default_output_file"
+ required: true
diff --git a/src/modules/bmm/workflows/debug/delta-minimize/instructions.md b/src/modules/bmm/workflows/debug/delta-minimize/instructions.md
new file mode 100644
index 00000000..f431f1d9
--- /dev/null
+++ b/src/modules/bmm/workflows/debug/delta-minimize/instructions.md
@@ -0,0 +1,228 @@
+# delta-minimization
+
+Automatically reduce failing test cases to minimal reproduction.
+
+## Context
+
+Delta debugging systematically minimizes failure-inducing inputs to find the smallest test case that still triggers a bug. This dramatically simplifies debugging by removing irrelevant complexity and isolating the essential trigger conditions.
+
+## Task Execution
+
+### Phase 1: Initial Setup
+
+#### Capture Failing State
+
+1. Record original failing test case:
+ - Input data
+ - Configuration settings
+ - Environment state
+ - Execution parameters
+2. Verify bug reproduction
+3. Measure initial complexity metrics:
+ - Input size
+ - Number of operations
+ - Data structure depth
+ - Configuration parameters
+
+### Phase 2: Minimization Strategy
+
+#### Select Minimization Approach
+
+**For Data Inputs:**
+
+1. **Binary reduction**: Remove half of input, test if still fails
+2. **Line-by-line**: For text/config files
+3. **Field elimination**: For structured data (JSON, XML)
+4. **Value simplification**: Replace complex values with simple ones
+
+**For Code/Test Cases:**
+
+1. **Statement removal**: Delete non-essential lines
+2. **Function inlining**: Replace calls with minimal implementations
+3. **Loop unrolling**: Convert loops to minimal iterations
+4. **Conditional simplification**: Remove unnecessary branches
+
+**For Configuration:**
+
+1. **Parameter elimination**: Remove non-essential settings
+2. **Default substitution**: Replace with default values
+3. **Range reduction**: Minimize numeric ranges
+
+### Phase 3: Delta Algorithm Implementation
+
+#### Core Algorithm
+
+```
+1. Start with failing test case T
+2. While reduction is possible:
+ a. Generate smaller candidate C from T
+ b. Test if C still triggers bug
+ c. If yes: T = C (accept reduction)
+ d. If no: Try different reduction
+3. Return minimal T
+```
+
+#### Automated Reduction Process
+
+**Step 1: Coarse-Grained Reduction**
+
+1. Try removing large chunks (50%)
+2. Binary search for largest removable section
+3. Continue until no large removals possible
+
+**Step 2: Fine-Grained Reduction**
+
+1. Try removing individual elements
+2. Test each element for necessity
+3. Build minimal required set
+
+**Step 3: Simplification Pass**
+
+1. Replace complex values with simpler equivalents:
+ - Long strings → "a"
+ - Large numbers → 0 or 1
+ - Complex objects → empty objects
+2. Maintain bug reproduction
+
+### Phase 4: Validation
+
+#### Verify Minimality
+
+1. Confirm bug still reproduces
+2. Verify no further reduction possible
+3. Test that adding any removed element doesn't affect bug
+4. Document reduction ratio achieved
+
+#### Create Clean Reproduction
+
+1. Format minimal test case
+2. Remove all comments/documentation
+3. Standardize naming (var1, var2, etc.)
+4. Ensure standalone execution
+
+## Intelligent Reduction Strategies
+
+### Pattern-Based Reduction
+
+Recognize common patterns and apply targeted reductions:
+
+- **Array operations**: Reduce to 2-3 elements
+- **Nested structures**: Flatten where possible
+- **Async operations**: Convert to synchronous
+- **External dependencies**: Mock with minimal stubs
+
+### Semantic-Aware Reduction
+
+Maintain semantic validity while reducing:
+
+- Preserve type constraints
+- Maintain referential integrity
+- Keep required relationships
+- Honor invariants
+
+### Parallel Exploration
+
+Test multiple reduction paths simultaneously:
+
+- Try different reduction strategies
+- Explore various simplification orders
+- Combine successful reductions
+
+## Output Format
+
+````markdown
+# Delta Debugging Minimization Report
+
+## Original Test Case
+
+**Size:** [original size/complexity]
+**Components:** [number of elements/lines/fields]
+**Execution Time:** [duration]
+
+```[format]
+[original test case - abbreviated if too long]
+```
+````
+
+## Minimization Process
+
+**Iterations:** [number]
+**Time Taken:** [duration]
+**Reduction Achieved:** [percentage]
+
+### Reduction Path
+
+1. [First major reduction] - Removed [what], Size: [new size]
+2. [Second reduction] - Simplified [what], Size: [new size]
+3. [Continue for significant reductions...]
+
+## Minimal Reproduction
+
+### Test Case
+
+```[language]
+// Minimal test case that reproduces bug
+[minimized code/data]
+```
+
+### Requirements
+
+- **Environment:** [minimal environment needed]
+- **Dependencies:** [only essential dependencies]
+- **Configuration:** [minimal config]
+
+### Execution
+
+```bash
+# Command to reproduce
+[exact command]
+```
+
+### Expected vs Actual
+
+**Expected:** [what should happen]
+**Actual:** [what happens (the bug)]
+
+## Analysis
+
+### Essential Elements
+
+These elements are required for reproduction:
+
+1. [Critical element 1] - Remove this and bug disappears
+2. [Critical element 2] - Essential for triggering condition
+3. [Continue for all essential elements]
+
+### Removed Elements
+
+These were safely removed without affecting the bug:
+
+- [Category]: [what was removed and why it's non-essential]
+- [Continue for major categories]
+
+### Insights Gained
+
+[What the minimization reveals about the bug's nature]
+
+## Root Cause Hypothesis
+
+Based on minimal reproduction:
+[What the essential elements suggest about root cause]
+
+## Next Steps
+
+1. Debug the minimal case using other techniques
+2. Focus on interaction between essential elements
+3. Test fix against both minimal and original cases
+
+```
+
+## Completion Criteria
+- [ ] Original failing case captured
+- [ ] Minimization algorithm executed
+- [ ] Minimal reproduction achieved
+- [ ] Bug still reproduces with minimal case
+- [ ] No further reduction possible
+- [ ] Essential elements identified
+- [ ] Clean reproduction documented
+```
diff --git a/src/modules/bmm/workflows/debug/delta-minimize/workflow.yaml b/src/modules/bmm/workflows/debug/delta-minimize/workflow.yaml
index 3a2ed96a..5772bb61 100644
--- a/src/modules/bmm/workflows/debug/delta-minimize/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/delta-minimize/workflow.yaml
@@ -1,11 +1,66 @@
-# Delta Minimize Workflow Configuration
-name: "delta-minimize"
-description: "Automatically reduce failing test case to minimal reproduction by systematic elimination."
-author: "Diana"
+# Debug Workflow: Delta Minimization
+name: debug-delta-minimize
+description: "Automatically reduce failing test case to minimal reproduction. Essential for complex input-dependent failures."
+author: "BMad Core"
+version: "2.0"
+# BMAD Core Configuration
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
installed_path: "{project-root}/bmad/bmm/workflows/debug/delta-minimize"
instructions: "{installed_path}/instructions.md"
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
-standalone: true
+template: false
+
+# Knowledge Base Requirements (BMAD Core)
+knowledge_dependencies:
+ - "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
+
+tags:
+ - debug
+ - minimization
+ - test-reduction
+ - advanced
+ - bmad-core
+
+execution_hints:
+ interactive: true
+ autonomous: false
+ iterative: true
+ validation_required: true
+ algorithmic: true
+
+# BMAD Core Workflow Steps
+steps:
+ - id: "load_config"
+ name: "Load Configuration"
+ type: "config"
+ required: true
+
+ - id: "load_knowledge"
+ name: "Load Knowledge Base"
+ type: "knowledge"
+ dependencies: "knowledge_dependencies"
+ required: true
+
+ - id: "execute_workflow"
+ name: "Execute Delta Minimization"
+ type: "workflow"
+ source: "instructions"
+ required: true
+ strategy: ["binary-reduction", "systematic-elimination", "invariant-preservation"]
+
+ - id: "validate_output"
+ name: "Validate Minimal Case"
+ type: "validation"
+ required: true
+ criteria: ["reproduction-confirmed", "minimal-achieved", "invariants-preserved"]
+
+ - id: "save_output"
+ name: "Save Minimal Test Case"
+ type: "output"
+ destination: "output_folder"
+ required: true
diff --git a/src/modules/bmm/workflows/debug/inspect/instructions.md b/src/modules/bmm/workflows/debug/inspect/instructions.md
index 4263d5de..3c67d99a 100644
--- a/src/modules/bmm/workflows/debug/inspect/instructions.md
+++ b/src/modules/bmm/workflows/debug/inspect/instructions.md
@@ -1,36 +1,119 @@
-# Fagan Inspection Instructions
+# Fagan Inspection Workflow
-## Overview
+Comprehensive Fagan inspection for systematic bug analysis and resolution.
-Execute a comprehensive Fagan inspection workflow to achieve 60-90% defect detection rates through systematic code review methodology.
+## Context
-## Methodology
+This workflow performs systematic defect analysis using the proven 6-phase Fagan inspection methodology, achieving 60-90% defect detection rates through formal peer review.
-This workflow implements the formal Fagan inspection process:
+## Prerequisites
-1. **Planning Phase** - Define scope, select participants, schedule sessions
-2. **Overview Phase** - Present code context and objectives to inspection team
-3. **Preparation Phase** - Individual reviewers study code using checklists
-4. **Inspection Meeting** - Systematic review to identify defects (not solutions)
-5. **Rework Phase** - Author addresses identified defects
-6. **Follow-up Phase** - Verify defect resolution
+- Clear bug description or symptom
+- Access to source code repository
+- Recent commit history available
+- Test suite and execution results
+- Environment and configuration details
-## Knowledge Integration
+## Instructions
-Consult the debug inspection checklist for systematic defect detection patterns and common issue categories.
+Execute the following phases in order:
-## Process Steps
+### Phase 1: Planning
-1. Load inspection checklist from knowledge base
-2. Define inspection scope and objectives
-3. Identify code artifacts for review
-4. Apply systematic inspection methodology
-5. Document findings with severity classification
-6. Generate inspection report with actionable recommendations
+1. Ask user for bug description if not already provided
+2. Identify inspection scope based on bug description
+3. Define inspection criteria and success metrics
+4. Load `debug-inspection-checklist.md` from knowledge base
+5. Determine affected components and stakeholders
+6. Document planning phase results
-## Expected Outputs
+### Phase 2: Overview
-- Comprehensive defect inventory
-- Severity-classified issue list
-- Inspection metrics and effectiveness data
-- Recommended next steps for resolution
+1. Analyze recent commits for context and potential causes (search git history)
+2. Review feature specifications and implementation plans
+3. Gather background context and related documentation
+4. Identify impact scope and affected systems
+5. Create preliminary timeline of issue
+6. Document overview findings
+
+### Phase 3: Preparation
+
+1. Systematic artifact examination:
+ - Execute code analysis using pattern detection (load `debug-patterns.md`)
+ - Analyze test coverage and execution results
+ - Review configuration and environment settings
+ - Check documentation consistency
+2. Perform dependency analysis and check for version conflicts
+3. Review performance metrics and resource usage (if applicable)
+4. Generate preliminary defect hypotheses
+5. Document preparation findings
+
+### Phase 4: Inspection Meeting
+
+1. Execute systematic defect identification using `common-defects.md`:
+ - Logic defects: Algorithm errors, control flow issues
+ - Interface defects: API misuse, parameter mismatches
+ - Data defects: Type mismatches, validation failures
+ - Documentation defects: Outdated or incorrect documentation
+2. Perform root cause analysis using fishbone methodology
+3. Conduct impact assessment: Severity, scope, risk level
+4. Categorize defects by type and priority (P0-P3)
+5. Document inspection findings with evidence
+
+### Phase 5: Rework Planning
+
+1. Generate fix proposals with tradeoff analysis
+2. Design test strategy for validation
+3. Perform risk assessment for proposed changes
+4. Create implementation timeline and effort estimate
+5. Plan regression testing approach
+6. Document rework plan
+
+### Phase 6: Follow-up
+
+1. Provide recommendations for validating fix effectiveness
+2. List documentation updates needed
+3. Capture lessons learned for prevention
+4. Generate comprehensive debug report using template
+5. Save report to output folder
+
+## Output Requirements
+
+Generate a structured debug report containing:
+
+- Executive Summary (problem, impact, root cause, solution)
+- Detailed Problem Description (symptoms, reproduction, environment, timeline)
+- Technical Analysis (root cause, code analysis, patterns, test coverage)
+- Impact Assessment (severity matrix, business impact)
+- Solution Recommendations (immediate fix, short-term, long-term, process improvements)
+- Implementation Plan (steps, timeline, validation)
+- Lessons Learned
+
+## Completion Criteria
+
+- [ ] All 6 phases completed systematically
+- [ ] Root cause identified with evidence trail
+- [ ] Fix recommendations provided with tradeoffs
+- [ ] Test strategy defined for validation
+- [ ] Risk assessment completed
+- [ ] Debug report generated and saved
+- [ ] Lessons learned documented
+
+## Elicitation Points
+
+
+Bug Description: Ask user to provide detailed bug description including:
+- What is the expected behavior?
+- What is the actual behavior?
+- When was this first observed?
+- How frequently does it occur?
+- Which environment(s) are affected?
+
+
+
+Additional Context: Ask if user can provide:
+- Related issue/ticket numbers
+- Recent changes or deployments
+- Error messages or stack traces
+- Steps to reproduce
+
diff --git a/src/modules/bmm/workflows/debug/inspect/template.yaml b/src/modules/bmm/workflows/debug/inspect/template.yaml
new file mode 100644
index 00000000..52266c31
--- /dev/null
+++ b/src/modules/bmm/workflows/debug/inspect/template.yaml
@@ -0,0 +1,234 @@
+#
+template:
+ id: debug-report-template-v1
+ name: Debug Analysis Report
+ version: 1.0
+ output:
+ format: markdown
+ filename: docs/debug/debug-report-{{timestamp}}.md
+ title: "Debug Analysis Report - {{problem_title}}"
+
+workflow:
+ mode: rapid
+ elicitation: false
+
+sections:
+ - id: header
+ title: Report Header
+ instruction: Generate report header with metadata
+ sections:
+ - id: metadata
+ title: Report Metadata
+ type: key-value
+ instruction: |
+ Report ID: DBG-{{timestamp}}
+ Date: {{current_date}}
+ Analyst: Debug Agent (Diana)
+ Severity: {{severity_level}}
+ Status: {{status}}
+
+ - id: executive-summary
+ title: Executive Summary
+ instruction: Provide concise summary under 200 words
+ sections:
+ - id: problem
+ title: Problem
+ type: text
+ instruction: 1-2 sentence problem statement
+ - id: impact
+ title: Impact
+ type: text
+ instruction: Quantified impact on users/system
+ - id: root-cause
+ title: Root Cause
+ type: text
+ instruction: Brief root cause description
+ - id: solution
+ title: Solution
+ type: text
+ instruction: High-level fix description
+ - id: metrics
+ title: Key Metrics
+ type: key-value
+ instruction: |
+ Effort Required: {{effort_estimate}}
+ Risk Level: {{risk_level}}
+
+ - id: problem-description
+ title: Problem Description
+ instruction: Detailed problem analysis
+ sections:
+ - id: symptoms
+ title: Symptoms
+ type: paragraphs
+ instruction: Detailed symptoms observed
+ - id: reproduction
+ title: Reproduction
+ type: numbered-list
+ instruction: Step-by-step reproduction steps with expected vs actual
+ - id: environment
+ title: Environment
+ type: bullet-list
+ instruction: |
+ - System: {{system_info}}
+ - Application: {{application_version}}
+ - Dependencies: {{dependencies_list}}
+ - Configuration: {{configuration_details}}
+ - id: timeline
+ title: Timeline
+ type: bullet-list
+ instruction: |
+ - First Observed: {{first_observed}}
+ - Frequency: {{occurrence_frequency}}
+ - Last Occurrence: {{last_occurrence}}
+
+ - id: technical-analysis
+ title: Technical Analysis
+ instruction: Deep technical investigation results
+ sections:
+ - id: root-cause-analysis
+ title: Root Cause Analysis
+ type: paragraphs
+ instruction: Detailed root cause with evidence
+ - id: code-analysis
+ title: Code Analysis
+ type: code-block
+ instruction: |
+ [[LLM: Include problematic code snippet with language specified]]
+ Issue: {{code_issue_description}}
+ - id: pattern-analysis
+ title: Pattern Analysis
+ type: paragraphs
+ instruction: Any patterns detected in the defect
+ - id: test-coverage
+ title: Test Coverage
+ type: bullet-list
+ instruction: |
+ - Current Coverage: {{coverage_percentage}}
+ - Gap Identified: {{coverage_gaps}}
+ - Risk Areas: {{untested_areas}}
+
+ - id: impact-assessment
+ title: Impact Assessment
+ instruction: Comprehensive impact analysis
+ sections:
+ - id: severity-matrix
+ title: Severity Matrix
+ type: table
+ columns: [Aspect, Impact, Severity]
+ instruction: |
+ [[LLM: Create table with Users Affected, Data Integrity, Performance, Security aspects]]
+ - id: business-impact
+ title: Business Impact
+ type: paragraphs
+ instruction: Business consequences of the issue
+
+ - id: solution-recommendations
+ title: Solution & Recommendations
+ instruction: Fix proposals and prevention strategies
+ sections:
+ - id: immediate-fix
+ title: Immediate Fix
+ type: code-block
+ instruction: |
+ [[LLM: Include corrected code with validation steps]]
+ - id: short-term
+ title: Short-term Improvements
+ type: bullet-list
+ instruction: Improvements for this sprint
+ - id: long-term
+ title: Long-term Prevention
+ type: bullet-list
+ instruction: Strategic prevention measures
+ - id: process
+ title: Process Enhancements
+ type: bullet-list
+ instruction: Process improvements to prevent recurrence
+
+ - id: implementation-plan
+ title: Implementation Plan
+ instruction: Phased approach to resolution
+ sections:
+ - id: phase1
+ title: "Phase 1: Immediate (0-2 days)"
+ type: checkbox-list
+ instruction: Critical fixes to apply immediately
+ - id: phase2
+ title: "Phase 2: Short-term (1 week)"
+ type: checkbox-list
+ instruction: Short-term improvements
+ - id: phase3
+ title: "Phase 3: Long-term (1 month)"
+ type: checkbox-list
+ instruction: Long-term strategic changes
+
+ - id: verification-testing
+ title: Verification & Testing
+ instruction: Validation strategy
+ sections:
+ - id: test-cases
+ title: Test Cases
+ type: numbered-list
+ instruction: Specific test cases to validate the fix
+ - id: regression
+ title: Regression Testing
+ type: paragraphs
+ instruction: Areas requiring regression testing
+ - id: monitoring
+ title: Monitoring
+ type: bullet-list
+ instruction: Metrics to monitor post-fix
+
+ - id: lessons-learned
+ title: Lessons Learned
+ instruction: Knowledge capture for prevention
+ sections:
+ - id: what-went-wrong
+ title: What Went Wrong
+ type: paragraphs
+ instruction: Root causes beyond the code
+ - id: improvements
+ title: What Could Improve
+ type: bullet-list
+ instruction: Process and tool improvements
+ - id: knowledge-sharing
+ title: Knowledge Sharing
+ type: bullet-list
+ instruction: Information to share with team
+
+ - id: appendices
+ title: Appendices
+ instruction: Supporting documentation
+ optional: true
+ sections:
+ - id: stack-traces
+ title: "Appendix A: Full Stack Traces"
+ type: code-block
+ instruction: Complete error traces if available
+ - id: logs
+ title: "Appendix B: Log Excerpts"
+ type: code-block
+ instruction: Relevant log entries
+ - id: metrics
+ title: "Appendix C: Performance Metrics"
+ type: paragraphs
+ instruction: Before/after performance data
+ - id: related
+ title: "Appendix D: Related Issues"
+ type: bullet-list
+ instruction: Links to similar problems
+ - id: references
+ title: "Appendix E: References"
+ type: bullet-list
+ instruction: Documentation, articles, tools used
+
+ - id: footer
+ title: Report Footer
+ instruction: Closing metadata
+ sections:
+ - id: timestamps
+ title: Report Timestamps
+ type: key-value
+ instruction: |
+ Report Generated: {{generation_timestamp}}
+ Next Review: {{follow_up_date}}
diff --git a/src/modules/bmm/workflows/debug/inspect/workflow.yaml b/src/modules/bmm/workflows/debug/inspect/workflow.yaml
index 1c183ac8..2ca5dfd9 100644
--- a/src/modules/bmm/workflows/debug/inspect/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/inspect/workflow.yaml
@@ -1,33 +1,72 @@
-# Fagan Inspection Workflow Configuration
-name: "inspect"
-description: "Execute comprehensive Fagan inspection workflow for systematic defect detection with 60-90% efficiency rates."
-author: "Diana"
+# Debug Workflow: Fagan Inspection
+name: debug-inspect
+description: "Comprehensive Fagan inspection for systematic bug analysis and resolution. Achieves 60-90% defect detection rates through formal 6-phase methodology."
+author: "BMad Core"
+version: "2.0"
-# Critical variables from config
+# BMAD Core Configuration
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
-document_output_language: "{config_source}:document_output_language"
-user_skill_level: "{config_source}:user_skill_level"
date: system-generated
-# Module path and component files
installed_path: "{project-root}/bmad/bmm/workflows/debug/inspect"
-template: false
instructions: "{installed_path}/instructions.md"
+template: "{installed_path}/template.yaml"
-# Knowledge base integration
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/debug-inspection-checklist.md"
+# Output configuration
+default_output_file: "{output_folder}/debug/debug-report-{{date}}.md"
-standalone: true
+# Knowledge Base Requirements (BMAD Core)
+knowledge_dependencies:
+ - "{project-root}/bmad/bmm/knowledge/debug/debug-inspection-checklist.md"
+ - "{project-root}/bmad/bmm/knowledge/debug/common-defects.md"
+ - "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
-web_bundle:
- name: "inspect"
- description: "Execute comprehensive Fagan inspection workflow for systematic defect detection with 60-90% efficiency rates."
- author: "Diana"
- instructions: "bmad/bmm/workflows/debug/inspect/instructions.md"
- template: false
- web_bundle_files:
- - "bmad/bmm/workflows/debug/inspect/instructions.md"
- - "bmad/bmm/knowledge/debug/debug-inspection-checklist.md"
+tags:
+ - debug
+ - inspection
+ - fagan
+ - quality
+ - bmad-core
+
+execution_hints:
+ interactive: true
+ autonomous: false
+ iterative: true
+ validation_required: true
+ high_accuracy: true
+
+# BMAD Core Workflow Steps
+steps:
+ - id: "load_config"
+ name: "Load Configuration"
+ type: "config"
+ required: true
+
+ - id: "load_knowledge"
+ name: "Load Knowledge Base"
+ type: "knowledge"
+ dependencies: "knowledge_dependencies"
+ required: true
+
+ - id: "execute_workflow"
+ name: "Execute Fagan Inspection"
+ type: "workflow"
+ source: "instructions"
+ template: "template"
+ required: true
+ phases: ["planning", "overview", "preparation", "inspection", "rework", "follow-up"]
+
+ - id: "validate_output"
+ name: "Validate Inspection Results"
+ type: "validation"
+ required: true
+ criteria: ["completeness", "accuracy", "actionability"]
+
+ - id: "save_output"
+ name: "Save Inspection Report"
+ type: "output"
+ destination: "default_output_file"
+ required: true
diff --git a/src/modules/bmm/workflows/debug/instrument/instructions.md b/src/modules/bmm/workflows/debug/instrument/instructions.md
new file mode 100644
index 00000000..98a63868
--- /dev/null
+++ b/src/modules/bmm/workflows/debug/instrument/instructions.md
@@ -0,0 +1,472 @@
+# instrumentation-analysis
+
+Design strategic logging and monitoring points for production debugging.
+
+## Context
+
+This task analyzes code to identify optimal locations for instrumentation (logging, metrics, tracing) that will aid in debugging production issues without impacting performance. It creates a comprehensive observability strategy.
+
+## Task Execution
+
+### Phase 1: Critical Path Analysis
+
+#### Identify Key Flows
+
+1. **User-Facing Paths**: Request → Response chains
+2. **Business-Critical Paths**: Payment, authentication, data processing
+3. **Performance-Sensitive Paths**: High-frequency operations
+4. **Error-Prone Paths**: Historical problem areas
+5. **Integration Points**: External service calls
+
+#### Map Decision Points
+
+- Conditional branches with business logic
+- State transitions
+- Error handling blocks
+- Retry mechanisms
+- Circuit breakers
+- Cache hits/misses
+
+### Phase 2: Instrumentation Strategy
+
+#### Level 1: Essential Instrumentation
+
+**Entry/Exit Points:**
+
+```
+- Service boundaries (API endpoints)
+- Function entry/exit for critical operations
+- Database transaction boundaries
+- External service calls
+- Message queue operations
+```
+
+**Error Conditions:**
+
+```
+- Exception catches
+- Validation failures
+- Timeout occurrences
+- Retry attempts
+- Fallback activations
+```
+
+**Performance Markers:**
+
+```
+- Operation start/end times
+- Queue depths
+- Resource utilization
+- Batch sizes
+- Cache effectiveness
+```
+
+#### Level 2: Diagnostic Instrumentation
+
+**State Changes:**
+
+```
+- User state transitions
+- Order/payment status changes
+- Configuration updates
+- Feature flag toggles
+- Circuit breaker state changes
+```
+
+**Business Events:**
+
+```
+- User actions (login, purchase, etc.)
+- System events (startup, shutdown)
+- Scheduled job execution
+- Data pipeline stages
+- Workflow transitions
+```
+
+#### Level 3: Deep Debugging
+
+**Detailed Tracing:**
+
+```
+- Parameter values for complex functions
+- Intermediate calculation results
+- Loop iteration counts
+- Branch decisions
+- SQL query parameters
+```
+
+### Phase 3: Implementation Patterns
+
+#### Structured Logging Format
+
+**Standard Fields:**
+
+```json
+{
+ "timestamp": "ISO-8601",
+ "level": "INFO|WARN|ERROR",
+ "service": "service-name",
+ "trace_id": "correlation-id",
+ "span_id": "operation-id",
+ "user_id": "if-applicable",
+ "operation": "what-is-happening",
+ "duration_ms": "for-completed-ops",
+ "status": "success|failure",
+ "error": "error-details-if-any",
+ "metadata": {
+ "custom": "fields"
+ }
+}
+```
+
+#### Performance-Conscious Patterns
+
+**Sampling Strategy:**
+
+```
+- 100% for errors
+- 10% for normal operations
+- 1% for high-frequency paths
+- Dynamic adjustment based on load
+```
+
+**Async Logging:**
+
+```
+- Buffer non-critical logs
+- Batch write to reduce I/O
+- Use separate thread/process
+- Implement backpressure handling
+```
+
+**Conditional Logging:**
+
+```
+- Debug level only in development
+- Info level in staging
+- Warn/Error in production
+- Dynamic level adjustment via config
+```
+
+### Phase 4: Metrics Design
+
+#### Key Metrics to Track
+
+**RED Metrics:**
+
+- **Rate**: Requests per second
+- **Errors**: Error rate/count
+- **Duration**: Response time distribution
+
+**USE Metrics:**
+
+- **Utilization**: Resource usage percentage
+- **Saturation**: Queue depth, wait time
+- **Errors**: Resource allocation failures
+
+**Business Metrics:**
+
+- Transaction success rate
+- Feature usage
+- User journey completion
+- Revenue impact
+
+#### Metric Implementation
+
+**Counter Examples:**
+
+```
+requests_total{method="GET", endpoint="/api/users", status="200"}
+errors_total{type="database", operation="insert"}
+```
+
+**Histogram Examples:**
+
+```
+request_duration_seconds{method="GET", endpoint="/api/users"}
+database_query_duration_ms{query_type="select", table="users"}
+```
+
+**Gauge Examples:**
+
+```
+active_connections{service="database"}
+queue_depth{queue="email"}
+```
+
+### Phase 5: Tracing Strategy
+
+#### Distributed Tracing Points
+
+**Span Creation:**
+
+```
+- HTTP request handling
+- Database operations
+- Cache operations
+- External API calls
+- Message publishing/consuming
+- Background job execution
+```
+
+**Context Propagation:**
+
+```
+- HTTP headers (X-Trace-Id)
+- Message metadata
+- Database comments
+- Log correlation
+```
+
+## Output Format
+
+````markdown
+# Instrumentation Analysis Report
+
+## Executive Summary
+
+**Components Analyzed:** [count]
+**Current Coverage:** [percentage]
+**Recommended Additions:** [count]
+**Performance Impact:** [minimal/low/moderate]
+**Implementation Effort:** [hours/days]
+
+## Critical Instrumentation Points
+
+### Priority 1: Immediate Implementation
+
+#### Service: [ServiceName]
+
+**Entry Points:**
+
+```[language]
+// Location: [file:line]
+// Current: No logging
+// Recommended:
+logger.info("Request received", {
+ method: req.method,
+ path: req.path,
+ user_id: req.user?.id,
+ trace_id: req.traceId
+});
+```
+````
+
+**Error Handling:**
+
+```[language]
+// Location: [file:line]
+// Current: Silent failure
+// Recommended:
+logger.error("Database operation failed", {
+ operation: "user_update",
+ user_id: userId,
+ error: err.message,
+ stack: err.stack,
+ retry_count: retries
+});
+```
+
+**Performance Tracking:**
+
+```[language]
+// Location: [file:line]
+// Recommended:
+const startTime = Date.now();
+try {
+ const result = await expensiveOperation();
+ metrics.histogram('operation_duration_ms', Date.now() - startTime, {
+ operation: 'expensive_operation',
+ status: 'success'
+ });
+ return result;
+} catch (error) {
+ metrics.histogram('operation_duration_ms', Date.now() - startTime, {
+ operation: 'expensive_operation',
+ status: 'failure'
+ });
+ throw error;
+}
+```
+
+### Priority 2: Enhanced Observability
+
+[Similar format for medium priority points]
+
+### Priority 3: Deep Debugging
+
+[Similar format for low priority points]
+
+## Logging Strategy
+
+### Log Levels by Environment
+
+| Level | Development | Staging | Production |
+| ----- | ----------- | ------- | ---------- |
+| DEBUG | ✓ | ✓ | ✗ |
+| INFO | ✓ | ✓ | Sampled |
+| WARN | ✓ | ✓ | ✓ |
+| ERROR | ✓ | ✓ | ✓ |
+
+### Sampling Configuration
+
+```yaml
+sampling:
+ default: 0.01 # 1% sampling
+ rules:
+ - path: '/health'
+ sample_rate: 0.001 # 0.1% for health checks
+ - path: '/api/critical/*'
+ sample_rate: 0.1 # 10% for critical APIs
+ - level: 'ERROR'
+ sample_rate: 1.0 # 100% for errors
+```
+
+## Metrics Implementation
+
+### Application Metrics
+
+```[language]
+// Metric definitions
+const metrics = {
+ // Counters
+ requests: new Counter('http_requests_total', ['method', 'path', 'status']),
+ errors: new Counter('errors_total', ['type', 'operation']),
+
+ // Histograms
+ duration: new Histogram('request_duration_ms', ['method', 'path']),
+ dbDuration: new Histogram('db_query_duration_ms', ['operation', 'table']),
+
+ // Gauges
+ connections: new Gauge('active_connections', ['type']),
+ queueSize: new Gauge('queue_size', ['queue_name'])
+};
+```
+
+### Dashboard Queries
+
+```sql
+-- Error rate by endpoint
+SELECT
+ endpoint,
+ sum(errors) / sum(requests) as error_rate
+FROM metrics
+WHERE time > now() - 1h
+GROUP BY endpoint
+
+-- P95 latency
+SELECT
+ endpoint,
+ percentile(duration, 0.95) as p95_latency
+FROM metrics
+WHERE time > now() - 1h
+GROUP BY endpoint
+```
+
+## Tracing Implementation
+
+### Trace Context
+
+```[language]
+// Trace context propagation
+class TraceContext {
+ constructor(traceId, spanId, parentSpanId) {
+ this.traceId = traceId || generateId();
+ this.spanId = spanId || generateId();
+ this.parentSpanId = parentSpanId;
+ }
+
+ createChild() {
+ return new TraceContext(this.traceId, generateId(), this.spanId);
+ }
+}
+
+// Usage
+middleware.use((req, res, next) => {
+ req.trace = new TraceContext(
+ req.headers['x-trace-id'],
+ req.headers['x-span-id'],
+ req.headers['x-parent-span-id']
+ );
+ next();
+});
+```
+
+## Performance Considerations
+
+### Impact Analysis
+
+| Instrumentation Type | CPU Impact | Memory Impact | I/O Impact |
+| -------------------- | ---------- | ------------- | -------------- |
+| Structured Logging | < 1% | < 10MB | Async buffered |
+| Metrics Collection | < 0.5% | < 5MB | Batched |
+| Distributed Tracing | < 2% | < 20MB | Sampled |
+
+### Optimization Techniques
+
+1. Use async logging with buffers
+2. Implement sampling for high-frequency paths
+3. Batch metric submissions
+4. Use conditional compilation for debug logs
+5. Implement circuit breakers for logging systems
+
+## Implementation Plan
+
+### Phase 1: Week 1
+
+- [ ] Implement critical error logging
+- [ ] Add service boundary instrumentation
+- [ ] Set up basic metrics
+
+### Phase 2: Week 2
+
+- [ ] Add performance tracking
+- [ ] Implement distributed tracing
+- [ ] Create initial dashboards
+
+### Phase 3: Week 3
+
+- [ ] Add business event tracking
+- [ ] Implement sampling strategies
+- [ ] Performance optimization
+
+## Monitoring & Alerts
+
+### Critical Alerts
+
+```yaml
+- name: high_error_rate
+ condition: error_rate > 0.01
+ severity: critical
+
+- name: high_latency
+ condition: p95_latency > 1000ms
+ severity: warning
+
+- name: service_down
+ condition: health_check_failures > 3
+ severity: critical
+```
+
+## Validation Checklist
+
+- [ ] No sensitive data in logs
+- [ ] Trace IDs properly propagated
+- [ ] Sampling rates appropriate
+- [ ] Performance impact acceptable
+- [ ] Dashboards created
+- [ ] Alerts configured
+- [ ] Documentation updated
+
+```
+
+## Completion Criteria
+- [ ] Critical paths identified
+- [ ] Instrumentation points mapped
+- [ ] Logging strategy defined
+- [ ] Metrics designed
+- [ ] Tracing plan created
+- [ ] Performance impact assessed
+- [ ] Implementation plan created
+- [ ] Monitoring strategy defined
+```
diff --git a/src/modules/bmm/workflows/debug/instrument/workflow.yaml b/src/modules/bmm/workflows/debug/instrument/workflow.yaml
index 0cb98b5c..b996213f 100644
--- a/src/modules/bmm/workflows/debug/instrument/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/instrument/workflow.yaml
@@ -1,11 +1,25 @@
-# Instrument Workflow Configuration
-name: "instrument"
-description: "Design strategic logging and monitoring points for enhanced debugging visibility."
-author: "Diana"
+# Debug Workflow: Instrumentation Design
+name: debug-instrument
+description: "Design strategic logging and monitoring points. Creates instrumentation plan for production debugging."
+author: "BMad"
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
installed_path: "{project-root}/bmad/bmm/workflows/debug/instrument"
instructions: "{installed_path}/instructions.md"
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
-standalone: true
+template: false
+
+tags:
+ - debug
+ - instrumentation
+ - observability
+ - production
+
+execution_hints:
+ interactive: true
+ autonomous: false
+ iterative: false
diff --git a/src/modules/bmm/workflows/debug/pattern-analysis/instructions.md b/src/modules/bmm/workflows/debug/pattern-analysis/instructions.md
index 06a6153a..30fe908b 100644
--- a/src/modules/bmm/workflows/debug/pattern-analysis/instructions.md
+++ b/src/modules/bmm/workflows/debug/pattern-analysis/instructions.md
@@ -1,35 +1,199 @@
-# Pattern Analysis Instructions
+# pattern-detection
-## Overview
+Analyze code and commit history for defect patterns and systemic issues.
-Analyze recent commits, code changes, and development patterns to identify systematic defect patterns and areas of risk concentration.
+## Context
-## Analysis Dimensions
+This task identifies recurring defect patterns, systemic issues, and common problem areas to enable proactive quality improvements.
-1. **Temporal Patterns** - Timing of defect introduction
-2. **Spatial Patterns** - Code regions with high defect density
-3. **Author Patterns** - Developer-specific issue trends
-4. **Change Patterns** - Types of modifications causing issues
-5. **Dependency Patterns** - Component interaction problems
-6. **Testing Patterns** - Coverage gaps and blind spots
+## Task Execution
-## Process Steps
+### Step 1: Historical Analysis
-1. **Data Collection** - Gather commit history, bug reports, test results
-2. **Pattern Recognition** - Identify recurring defect categories
-3. **Hotspot Analysis** - Map defect concentration areas
-4. **Trend Analysis** - Track pattern evolution over time
-5. **Risk Assessment** - Evaluate pattern impact and likelihood
-6. **Prevention Strategy** - Recommend pattern-breaking interventions
+#### Recent Commits Analysis
-## Knowledge Integration
+1. Review last 20-50 commits for:
+ - Files frequently modified (hotspots)
+ - Repeated fix attempts
+ - Revert commits indicating instability
+ - Emergency/hotfix patterns
-Reference common defects catalog for pattern matching and classification of identified issues.
+#### Bug History Review
-## Expected Outputs
+1. Analyze recent bug reports for:
+ - Common symptoms
+ - Recurring locations
+ - Similar root causes
+ - Fix patterns
-- Defect pattern summary with frequency data
-- Risk hotspot identification and mapping
-- Trend analysis with predictive indicators
-- Targeted prevention recommendations
-- Process improvement suggestions
+### Step 2: Code Pattern Detection
+
+#### Anti-Pattern Identification
+
+Look for common problematic patterns:
+
+- God objects/functions (excessive responsibility)
+- Copy-paste code (DRY violations)
+- Dead code (unused functions/variables)
+- Complex conditionals (cyclomatic complexity)
+- Long parameter lists
+- Inappropriate intimacy (tight coupling)
+
+#### Vulnerability Patterns
+
+Check for security/reliability issues:
+
+- Input validation gaps
+- Error handling inconsistencies
+- Resource leak patterns
+- Race condition indicators
+- SQL injection risks
+- XSS vulnerabilities
+
+### Step 3: Architectural Pattern Analysis
+
+#### Dependency Issues
+
+- Circular dependencies
+- Version conflicts
+- Missing abstractions
+- Leaky abstractions
+- Inappropriate dependencies
+
+#### Design Smells
+
+- Violated SOLID principles
+- Missing design patterns where needed
+- Over-engineering indicators
+- Technical debt accumulation
+
+### Step 4: Team Pattern Analysis
+
+#### Development Patterns
+
+- Rush commits (end of sprint)
+- Incomplete implementations
+- Missing tests for bug fixes
+- Documentation gaps
+- Code review oversights
+
+#### Communication Patterns
+
+- Misunderstood requirements
+- Incomplete handoffs
+- Knowledge silos
+- Missing context in commits
+
+### Step 5: Pattern Correlation
+
+1. Group related patterns by:
+ - Component/module
+ - Developer/team
+ - Time period
+ - Feature area
+
+2. Identify correlations:
+ - Patterns that appear together
+ - Cascade effects
+ - Root pattern causing others
+
+## Output Format
+
+```markdown
+# Defect Pattern Analysis Report
+
+## Executive Summary
+
+[High-level overview of key patterns found]
+
+## Critical Patterns Detected
+
+### Pattern 1: [Pattern Name]
+
+**Type:** [Anti-pattern/Vulnerability/Design/Process]
+**Frequency:** [Number of occurrences]
+**Locations:**
+
+- [file:line]
+- [file:line]
+
+**Description:** [What the pattern is]
+**Impact:** [Why it matters]
+**Example:** [Code snippet or commit reference]
+**Recommendation:** [How to address]
+
+## Hotspot Analysis
+
+### High-Change Files
+
+1. [filename] - [change count] changes, [bug count] bugs
+2. [filename] - [change count] changes, [bug count] bugs
+
+### Complex Areas
+
+1. [component] - Complexity score: [number]
+2. [component] - Complexity score: [number]
+
+## Systemic Issues
+
+### Issue 1: [Issue Name]
+
+**Pattern Indicators:**
+
+- [Pattern that indicates this issue]
+- [Another indicator]
+
+**Root Cause:** [Underlying systemic problem]
+**Affected Areas:** [Components/teams affected]
+**Priority:** [Critical/High/Medium/Low]
+**Remediation Strategy:** [How to fix systematically]
+
+## Trend Analysis
+
+### Improving Areas
+
+- [Area showing positive trends]
+
+### Degrading Areas
+
+- [Area showing negative trends]
+
+### Stable Problem Areas
+
+- [Persistent issues not getting better or worse]
+
+## Recommendations
+
+### Immediate Actions
+
+1. [Quick win to address patterns]
+2. [Another quick action]
+
+### Short-term Improvements
+
+1. [1-2 sprint improvements]
+2. [Process changes needed]
+
+### Long-term Strategy
+
+1. [Architectural changes]
+2. [Team/process evolution]
+
+## Prevention Checklist
+
+- [ ] Add static analysis for [pattern]
+- [ ] Implement pre-commit hooks for [issue]
+- [ ] Create coding standards for [area]
+- [ ] Add automated tests for [vulnerability]
+- [ ] Improve documentation for [component]
+```
+
+## Completion Criteria
+
+- [ ] Historical analysis completed
+- [ ] Code patterns identified
+- [ ] Architectural issues found
+- [ ] Team patterns analyzed
+- [ ] Correlations established
+- [ ] Recommendations provided
+- [ ] Prevention strategies defined
diff --git a/src/modules/bmm/workflows/debug/pattern-analysis/workflow.yaml b/src/modules/bmm/workflows/debug/pattern-analysis/workflow.yaml
index 15b6fa52..54d017ff 100644
--- a/src/modules/bmm/workflows/debug/pattern-analysis/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/pattern-analysis/workflow.yaml
@@ -1,33 +1,29 @@
-# Pattern Analysis Workflow Configuration
-name: "pattern-analysis"
-description: "Analyze recent commits and code changes for defect patterns and systematic issues."
-author: "Diana"
+# Debug Workflow: Pattern Analysis
+name: debug-pattern-analysis
+description: "Analyze recent commits and code changes for defect patterns and systemic issues."
+author: "BMad"
-# Critical variables from config
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
-document_output_language: "{config_source}:document_output_language"
-user_skill_level: "{config_source}:user_skill_level"
date: system-generated
-# Module path and component files
installed_path: "{project-root}/bmad/bmm/workflows/debug/pattern-analysis"
-template: false
instructions: "{installed_path}/instructions.md"
+template: false
-# Knowledge base integration
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/common-defects.md"
+knowledge_fragments:
+ - "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
+ - "{project-root}/bmad/bmm/knowledge/debug/common-defects.md"
-standalone: true
+tags:
+ - debug
+ - pattern-detection
+ - analysis
+ - prevention
-web_bundle:
- name: "pattern-analysis"
- description: "Analyze recent commits and code changes for defect patterns and systematic issues."
- author: "Diana"
- instructions: "bmad/bmm/workflows/debug/pattern-analysis/instructions.md"
- template: false
- web_bundle_files:
- - "bmad/bmm/workflows/debug/pattern-analysis/instructions.md"
- - "bmad/bmm/knowledge/debug/common-defects.md"
+execution_hints:
+ interactive: false
+ autonomous: true
+ iterative: true
diff --git a/src/modules/bmm/workflows/debug/quick-debug/instructions.md b/src/modules/bmm/workflows/debug/quick-debug/instructions.md
index f50b9dda..f2497013 100644
--- a/src/modules/bmm/workflows/debug/quick-debug/instructions.md
+++ b/src/modules/bmm/workflows/debug/quick-debug/instructions.md
@@ -1,31 +1,59 @@
-# Quick Debug Instructions
+# Quick Debug Workflow
-## Overview
+Rapid triage and initial analysis for simple issues.
-Perform rapid triage and initial analysis for simple issues requiring immediate attention or time-critical situations.
+## Context
-## When to Use
+This workflow provides fast initial assessment of bugs and issues, classifying severity and determining next steps without full formal inspection.
-- Production issues requiring immediate response
-- Simple bugs with obvious symptoms
-- Initial triage before deeper investigation
-- Time-critical debugging scenarios
+## Prerequisites
-## Process Steps
+- Bug description or symptom
+- Basic reproduction information
-1. **Symptom Capture** - Document observed behavior and error conditions
-2. **Environment Assessment** - Verify system state and recent changes
-3. **Pattern Matching** - Apply common debug patterns from knowledge base
-4. **Quick Verification** - Test immediate hypotheses
-5. **Triage Decision** - Determine if quick fix is appropriate or deeper analysis needed
+## Instructions
-## Knowledge Integration
+### Step 1: Initial Triage
-Leverage debug patterns guide for rapid pattern recognition and common issue resolution strategies.
+1. Ask user for issue description
+2. Classify severity (P0-P3)
+3. Determine urgency and impact
+4. Assess complexity (simple, moderate, complex)
-## Expected Outputs
+### Step 2: Quick Analysis
-- Issue classification and severity assessment
-- Initial hypothesis with supporting evidence
-- Quick fix recommendations (if applicable)
-- Escalation path for complex issues requiring full investigation
+1. Review error messages or symptoms
+2. Check for known patterns in `debug-patterns.md`
+3. Identify likely component or area
+4. Assess if quick fix is possible
+
+### Step 3: Recommend Next Steps
+
+Based on complexity:
+
+- **Simple:** Provide immediate fix suggestion
+- **Moderate:** Recommend `*root-cause` workflow
+- **Complex:** Recommend `*inspect` workflow for full Fagan inspection
+
+### Step 4: Document Findings
+
+Provide brief summary with:
+
+- Severity classification
+- Initial assessment
+- Recommended next steps
+- Estimated effort
+
+## Completion Criteria
+
+- [ ] Issue classified by severity
+- [ ] Initial assessment provided
+- [ ] Next steps recommended
+- [ ] Findings documented
+
+
+Issue Description: Ask user to describe:
+- What is happening?
+- Expected vs actual behavior
+- How critical is this?
+
diff --git a/src/modules/bmm/workflows/debug/quick-debug/workflow.yaml b/src/modules/bmm/workflows/debug/quick-debug/workflow.yaml
index c6575800..4d6c4469 100644
--- a/src/modules/bmm/workflows/debug/quick-debug/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/quick-debug/workflow.yaml
@@ -1,33 +1,63 @@
-# Quick Debug Workflow Configuration
-name: "quick-debug"
-description: "Rapid triage and initial analysis for simple issues requiring immediate attention."
-author: "Diana"
+# Debug Workflow: Quick Debug
+name: debug-quick
+description: "Rapid triage and initial analysis for simple issues. Provides immediate assessment and suggested next steps."
+author: "BMad Core"
+version: "2.0"
-# Critical variables from config
+# BMAD Core Configuration
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
-document_output_language: "{config_source}:document_output_language"
-user_skill_level: "{config_source}:user_skill_level"
date: system-generated
-# Module path and component files
installed_path: "{project-root}/bmad/bmm/workflows/debug/quick-debug"
-template: false
instructions: "{installed_path}/instructions.md"
+template: false
-# Knowledge base integration
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
+# Knowledge Base Requirements
+knowledge_dependencies:
+ - "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
+ - "{project-root}/bmad/bmm/knowledge/debug/common-defects.md"
-standalone: true
+tags:
+ - debug
+ - triage
+ - quick-analysis
+ - bmad-core
-web_bundle:
- name: "quick-debug"
- description: "Rapid triage and initial analysis for simple issues requiring immediate attention."
- author: "Diana"
- instructions: "bmad/bmm/workflows/debug/quick-debug/instructions.md"
- template: false
- web_bundle_files:
- - "bmad/bmm/workflows/debug/quick-debug/instructions.md"
- - "bmad/bmm/knowledge/debug/debug-patterns.md"
+execution_hints:
+ interactive: true
+ autonomous: false
+ iterative: false
+ validation_required: true
+
+# BMAD Core Workflow Steps
+steps:
+ - id: "load_config"
+ name: "Load Configuration"
+ type: "config"
+ required: true
+
+ - id: "load_knowledge"
+ name: "Load Knowledge Base"
+ type: "knowledge"
+ dependencies: "knowledge_dependencies"
+ required: true
+
+ - id: "execute_workflow"
+ name: "Execute Quick Debug"
+ type: "workflow"
+ source: "instructions"
+ required: true
+
+ - id: "validate_output"
+ name: "Validate Results"
+ type: "validation"
+ required: true
+
+ - id: "save_output"
+ name: "Save Results"
+ type: "output"
+ destination: "output_folder"
+ required: true
diff --git a/src/modules/bmm/workflows/debug/root-cause/instructions.md b/src/modules/bmm/workflows/debug/root-cause/instructions.md
index 00d52786..ad36c76e 100644
--- a/src/modules/bmm/workflows/debug/root-cause/instructions.md
+++ b/src/modules/bmm/workflows/debug/root-cause/instructions.md
@@ -1,36 +1,178 @@
-# Root Cause Analysis Instructions
+# Root Cause Analysis Workflow
-## Overview
+Focused root cause analysis using fishbone (Ishikawa) methodology and 5-Whys technique.
-Execute systematic root cause analysis using fishbone (Ishikawa) methodology to identify underlying system issues beyond immediate symptoms.
+## Context
-## Fishbone Methodology
+This workflow performs systematic root cause analysis to identify the underlying causes of defects, moving beyond symptoms to address fundamental issues.
-Systematic analysis across six primary categories:
+## Prerequisites
-1. **Methods** - Processes, procedures, standards
-2. **Machines** - Tools, technology, infrastructure
-3. **Materials** - Data, inputs, dependencies
-4. **Measurements** - Metrics, monitoring, detection
-5. **Environment** - Context, conditions, constraints
-6. **People** - Skills, training, communication
+- Clear symptom or problem statement
+- Access to system logs and error messages
+- Knowledge of recent changes or deployments
+- Understanding of system architecture
+- Access to code repository
-## Process Steps
+## Instructions
-1. **Problem Definition** - Clearly articulate the observed issue
-2. **Category Analysis** - Systematically examine each fishbone category
-3. **Contributing Factor Identification** - Map potential causes to categories
-4. **Evidence Collection** - Gather supporting data for hypotheses
-5. **Root Cause Prioritization** - Rank causes by likelihood and impact
-6. **Verification Testing** - Validate root cause hypotheses
+Execute the following steps in order:
-## Knowledge Integration
+### Step 1: Problem Definition
-Use root cause checklist for systematic category exploration and common cause patterns.
+1. Ask user for problem/symptom description if not already provided
+2. Clearly state the problem/symptom
+3. Define when it occurs (timing, frequency, patterns)
+4. Define where it occurs (component, environment, scope)
+5. Quantify the impact (users affected, severity level P0-P3)
+6. Document problem statement clearly
-## Expected Outputs
+### Step 2: Fishbone Analysis Categories
-- Comprehensive fishbone diagram
-- Prioritized root cause candidates with evidence
-- Verification plan for top hypotheses
-- Preventive measures to avoid recurrence
+Load `root-cause-checklist.md` and analyze the problem across these six dimensions:
+
+#### People (Developer/User factors)
+
+- Knowledge gaps or misunderstandings
+- Communication breakdowns between teams
+- Incorrect assumptions made during development
+- User behavior patterns contributing to issue
+- Training or documentation gaps
+
+#### Process (Development/Deployment)
+
+- Missing validation or review steps
+- Inadequate testing coverage
+- Deployment procedures not followed
+- Code review gaps or oversights
+- Documentation process failures
+
+#### Technology (Tools/Infrastructure)
+
+- Framework limitations or bugs
+- Library bugs or incompatibilities
+- Infrastructure issues or constraints
+- Tool configuration problems
+- Version compatibility issues
+
+#### Environment (System/Configuration)
+
+- Environment-specific settings or differences
+- Resource constraints (memory, CPU, disk)
+- External dependencies or integrations
+- Network or connectivity issues
+- Configuration drift between environments
+
+#### Data (Input/State)
+
+- Invalid or unexpected input data
+- Data corruption or inconsistency
+- State management issues
+- Race conditions or timing problems
+- Data validation gaps
+
+#### Methods (Algorithms/Design)
+
+- Algorithm flaws or inefficiencies
+- Design pattern misuse
+- Architecture limitations
+- Performance bottlenecks
+- Logic errors in implementation
+
+### Step 3: 5-Whys Deep Dive
+
+For each potential cause identified in Step 2:
+
+1. Ask "Why does this happen?" - Document the answer
+2. For each answer, ask "Why?" again - Go deeper
+3. Continue asking "Why?" until reaching the root cause (typically 5 iterations)
+4. Document the complete chain of causation
+5. Ensure the final "Why" points to something actionable
+
+Example:
+
+- Problem: Application crashes
+- Why? Memory leak
+- Why? Objects not released
+- Why? Event listeners not removed
+- Why? Component unmount not handled
+- Why? Framework lifecycle not understood → ROOT CAUSE
+
+### Step 4: Evidence Collection
+
+For each identified root cause:
+
+- Gather supporting evidence (logs, stack traces, metrics, code examples)
+- Verify through reproduction or testing
+- Rule out alternative explanations
+- Cross-reference with `common-defects.md` patterns
+- Establish confidence level (High/Medium/Low)
+- Document evidence trail clearly
+
+### Step 5: Root Cause Prioritization
+
+Rank root causes using this matrix:
+
+| Root Cause | Likelihood | Impact | Effort | Risk | Priority |
+| ---------- | ---------- | ------ | ------ | ---- | -------- |
+
+Scoring criteria:
+
+- **Likelihood:** Probability this is the true cause (High/Medium/Low)
+- **Impact:** Severity if this is the cause (Critical/High/Medium/Low)
+- **Effort:** Complexity to address (High/Medium/Low)
+- **Risk:** Potential for recurrence if not fixed (High/Medium/Low)
+- **Priority:** Overall priority (P0-P3)
+
+### Step 6: Recommendations
+
+For the highest priority root causes:
+
+1. Propose specific fixes to address root cause
+2. Suggest preventive measures to avoid recurrence
+3. Recommend process improvements
+4. Identify monitoring or instrumentation needs
+5. Create validation plan for proposed fixes
+
+## Output Requirements
+
+Generate a structured root cause analysis document containing:
+
+- Analysis metadata (ID, date, analyst, method)
+- Problem statement (what, when, where, impact)
+- Fishbone diagram (ASCII or description)
+- Analysis for all 6 categories (People, Process, Technology, Environment, Data, Methods)
+- 5-Whys analysis for top causes
+- Evidence supporting each root cause
+- Prioritization matrix
+- Recommendations for fixes and prevention
+- Next steps and validation plan
+
+## Completion Criteria
+
+- [ ] Problem clearly defined with quantified impact
+- [ ] All 6 fishbone categories analyzed
+- [ ] 5-Whys performed for top causes
+- [ ] Evidence collected and documented
+- [ ] Root causes prioritized by likelihood and impact
+- [ ] Recommendations provided with validation plan
+- [ ] Root cause analysis report generated and saved
+
+## Elicitation Points
+
+
+Problem/Symptom: Ask user to describe:
+- What is the observable problem or symptom?
+- When does it occur (always, intermittently, specific conditions)?
+- Where does it occur (which environment, component, user segment)?
+- What is the impact (how many users, severity, business impact)?
+
+
+
+Additional Context: Ask if available:
+- Recent changes or deployments
+- Error messages or logs
+- Reproduction steps
+- Related issues or patterns
+- User reports or feedback
+
diff --git a/src/modules/bmm/workflows/debug/root-cause/template.yaml b/src/modules/bmm/workflows/debug/root-cause/template.yaml
new file mode 100644
index 00000000..6bb08f61
--- /dev/null
+++ b/src/modules/bmm/workflows/debug/root-cause/template.yaml
@@ -0,0 +1,268 @@
+#
+template:
+ id: root-cause-template-v1
+ name: Root Cause Analysis
+ version: 1.0
+ output:
+ format: markdown
+ filename: docs/debug/rca-{{timestamp}}.md
+ title: "Root Cause Analysis: {{problem_title}}"
+
+workflow:
+ mode: rapid
+ elicitation: false
+
+sections:
+ - id: header
+ title: Analysis Header
+ instruction: Generate analysis header with metadata
+ sections:
+ - id: metadata
+ title: Analysis Metadata
+ type: key-value
+ instruction: |
+ Analysis ID: RCA-{{timestamp}}
+ Date: {{current_date}}
+ Analyst: {{analyst_name}}
+ Method: Fishbone (Ishikawa) Diagram + 5-Whys
+
+ - id: problem-statement
+ title: Problem Statement
+ instruction: Clear problem definition
+ sections:
+ - id: what
+ title: What
+ type: text
+ instruction: Clear description of the problem
+ - id: when
+ title: When
+ type: text
+ instruction: Timing and frequency of occurrence
+ - id: where
+ title: Where
+ type: text
+ instruction: Location/component affected
+ - id: impact
+ title: Impact
+ type: text
+ instruction: Quantified impact on system/users
+
+ - id: fishbone-analysis
+ title: Fishbone Analysis
+ instruction: |
+ [[LLM: Create ASCII fishbone diagram showing all 6 categories branching into the problem]]
+ sections:
+ - id: diagram
+ title: Fishbone Diagram
+ type: code-block
+ instruction: |
+ ```
+ {{problem_title}}
+ |
+ People ---------------+--------------- Process
+ \ | /
+ \ | /
+ \ | /
+ \ | /
+ \ | /
+ Technology ----------+---------- Environment
+ \ | /
+ \ | /
+ \ | /
+ \ | /
+ \ | /
+ Data -----------+----------- Methods
+ ```
+ - id: people
+ title: People (Developer/User Factors)
+ type: bullet-list
+ instruction: Knowledge gaps, communication issues, training needs, user behavior
+ - id: process
+ title: Process (Development/Deployment)
+ type: bullet-list
+ instruction: Development process, deployment procedures, code review, testing
+ - id: technology
+ title: Technology (Tools/Infrastructure)
+ type: bullet-list
+ instruction: Framework limitations, library issues, tool configurations, infrastructure
+ - id: environment
+ title: Environment (System/Configuration)
+ type: bullet-list
+ instruction: Environment differences, resource constraints, external dependencies
+ - id: data
+ title: Data (Input/State)
+ type: bullet-list
+ instruction: Input validation, data integrity, state management, race conditions
+ - id: methods
+ title: Methods (Algorithms/Design)
+ type: bullet-list
+ instruction: Algorithm correctness, design patterns, architecture decisions
+
+ - id: five-whys
+ title: 5-Whys Analysis
+ instruction: Deep dive to root cause
+ sections:
+ - id: symptom
+ title: Primary Symptom
+ type: text
+ instruction: Starting point for analysis
+ - id: why1
+ title: "1. Why?"
+ type: text
+ instruction: First level cause
+ - id: why2
+ title: "2. Why?"
+ type: text
+ instruction: Second level cause
+ - id: why3
+ title: "3. Why?"
+ type: text
+ instruction: Third level cause
+ - id: why4
+ title: "4. Why?"
+ type: text
+ instruction: Fourth level cause
+ - id: why5
+ title: "5. Why?"
+ type: text
+ instruction: Fifth level cause (root cause)
+ - id: root-cause
+ title: Root Cause
+ type: text
+ instruction: Final identified root cause
+
+ - id: evidence-validation
+ title: Evidence & Validation
+ instruction: Support for conclusions
+ sections:
+ - id: evidence
+ title: Supporting Evidence
+ type: bullet-list
+ instruction: List all evidence supporting the root cause conclusion
+ - id: verification
+ title: Verification Method
+ type: paragraphs
+ instruction: How to verify this is the true root cause
+ - id: confidence
+ title: Confidence Level
+ type: key-value
+ instruction: |
+ Rating: {{confidence_rating}}
+ Justification: {{confidence_justification}}
+
+ - id: root-cause-summary
+ title: Root Cause Summary
+ instruction: Consolidated findings
+ sections:
+ - id: primary
+ title: Primary Root Cause
+ type: key-value
+ instruction: |
+ Cause: {{primary_root_cause}}
+ Category: {{cause_category}}
+ Evidence: {{primary_evidence}}
+ - id: contributing
+ title: Contributing Factors
+ type: numbered-list
+ instruction: Secondary factors that contributed to the problem
+ - id: eliminated
+ title: Eliminated Possibilities
+ type: numbered-list
+ instruction: Potential causes that were ruled out and why
+
+ - id: impact-analysis
+ title: Impact Analysis
+ instruction: Scope and consequences
+ sections:
+ - id: direct
+ title: Direct Impact
+ type: paragraphs
+ instruction: Immediate consequences of the problem
+ - id: indirect
+ title: Indirect Impact
+ type: paragraphs
+ instruction: Secondary effects and ripple impacts
+ - id: recurrence
+ title: Risk of Recurrence
+ type: key-value
+ instruction: |
+ Probability: {{recurrence_probability}}
+ Without intervention: {{risk_without_fix}}
+
+ - id: recommendations
+ title: Recommended Actions
+ instruction: Solutions and prevention
+ sections:
+ - id: immediate
+ title: Immediate Actions
+ type: checkbox-list
+ instruction: Actions to take right now to address the issue
+ - id: short-term
+ title: Short-term Solutions
+ type: checkbox-list
+ instruction: Solutions to implement within the current sprint
+ - id: long-term
+ title: Long-term Prevention
+ type: checkbox-list
+ instruction: Strategic changes to prevent recurrence
+ - id: process-improvements
+ title: Process Improvements
+ type: bullet-list
+ instruction: Process changes to prevent similar issues
+
+ - id: implementation-priority
+ title: Implementation Priority
+ instruction: Action prioritization
+ sections:
+ - id: priority-matrix
+ title: Priority Matrix
+ type: table
+ columns: [Action, Priority, Effort, Impact, Timeline]
+ instruction: |
+ [[LLM: Create prioritized action table with High/Medium/Low ratings]]
+
+ - id: verification-plan
+ title: Verification Plan
+ instruction: Ensuring fix effectiveness
+ sections:
+ - id: success-criteria
+ title: Success Criteria
+ type: bullet-list
+ instruction: How we'll know the root cause is addressed
+ - id: validation-steps
+ title: Validation Steps
+ type: numbered-list
+ instruction: Steps to validate the fix works
+ - id: monitoring-metrics
+ title: Monitoring Metrics
+ type: bullet-list
+ instruction: Metrics to track to ensure problem doesn't recur
+
+ - id: lessons-learned
+ title: Lessons Learned
+ instruction: Knowledge capture
+ sections:
+ - id: insights
+ title: Key Insights
+ type: bullet-list
+ instruction: What we learned from this analysis
+ - id: prevention
+ title: Prevention Strategies
+ type: bullet-list
+ instruction: How to prevent similar issues in the future
+ - id: knowledge-transfer
+ title: Knowledge Transfer
+ type: bullet-list
+ instruction: Information to share with the team
+
+ - id: footer
+ title: Analysis Footer
+ instruction: Closing information
+ sections:
+ - id: completion
+ title: Completion Details
+ type: key-value
+ instruction: |
+ Analysis Completed: {{completion_timestamp}}
+ Review Date: {{review_date}}
+ Owner: {{action_owner}}
diff --git a/src/modules/bmm/workflows/debug/root-cause/workflow.yaml b/src/modules/bmm/workflows/debug/root-cause/workflow.yaml
index 3c9f430a..9158254a 100644
--- a/src/modules/bmm/workflows/debug/root-cause/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/root-cause/workflow.yaml
@@ -1,33 +1,71 @@
-# Root Cause Analysis Workflow Configuration
-name: "root-cause"
-description: "Execute focused root cause analysis using fishbone methodology to identify underlying system issues."
-author: "Diana"
+# Debug Workflow: Root Cause Analysis
+name: debug-root-cause
+description: "Focused root cause analysis using fishbone (Ishikawa) methodology and 5-Whys technique to identify underlying defect causes."
+author: "BMad Core"
+version: "2.0"
-# Critical variables from config
+# BMAD Core Configuration
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
-document_output_language: "{config_source}:document_output_language"
-user_skill_level: "{config_source}:user_skill_level"
date: system-generated
-# Module path and component files
installed_path: "{project-root}/bmad/bmm/workflows/debug/root-cause"
-template: false
instructions: "{installed_path}/instructions.md"
+template: "{installed_path}/template.yaml"
-# Knowledge base integration
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/root-cause-checklist.md"
+# Output configuration
+default_output_file: "{output_folder}/debug/rca-{{date}}.md"
-standalone: true
+# Knowledge Base Requirements (BMAD Core)
+knowledge_dependencies:
+ - "{project-root}/bmad/bmm/knowledge/debug/root-cause-checklist.md"
+ - "{project-root}/bmad/bmm/knowledge/debug/common-defects.md"
-web_bundle:
- name: "root-cause"
- description: "Execute focused root cause analysis using fishbone methodology to identify underlying system issues."
- author: "Diana"
- instructions: "bmad/bmm/workflows/debug/root-cause/instructions.md"
- template: false
- web_bundle_files:
- - "bmad/bmm/workflows/debug/root-cause/instructions.md"
- - "bmad/bmm/knowledge/debug/root-cause-checklist.md"
+tags:
+ - debug
+ - root-cause
+ - fishbone
+ - analysis
+ - bmad-core
+
+execution_hints:
+ interactive: true
+ autonomous: false
+ iterative: true
+ validation_required: true
+ methodical: true
+
+# BMAD Core Workflow Steps
+steps:
+ - id: "load_config"
+ name: "Load Configuration"
+ type: "config"
+ required: true
+
+ - id: "load_knowledge"
+ name: "Load Knowledge Base"
+ type: "knowledge"
+ dependencies: "knowledge_dependencies"
+ required: true
+
+ - id: "execute_workflow"
+ name: "Execute Root Cause Analysis"
+ type: "workflow"
+ source: "instructions"
+ template: "template"
+ required: true
+ methods: ["fishbone", "5-whys", "timeline-analysis"]
+
+ - id: "validate_output"
+ name: "Validate RCA Results"
+ type: "validation"
+ required: true
+ criteria: ["root-cause-identified", "evidence-supported", "actionable-recommendations"]
+
+ - id: "save_output"
+ name: "Save RCA Report"
+ type: "output"
+ destination: "default_output_file"
+ required: true
diff --git a/src/modules/bmm/workflows/debug/static-scan/instructions.md b/src/modules/bmm/workflows/debug/static-scan/instructions.md
new file mode 100644
index 00000000..15c4fb5f
--- /dev/null
+++ b/src/modules/bmm/workflows/debug/static-scan/instructions.md
@@ -0,0 +1,294 @@
+# static-analysis
+
+Comprehensive static analysis for defect detection and code quality assessment.
+
+## Context
+
+This task performs deep static analysis to identify bugs, anti-patterns, security vulnerabilities, and code quality issues without executing the code. It combines multiple analysis techniques to provide a comprehensive view of potential problems.
+
+## Task Execution
+
+### Phase 1: Multi-Layer Analysis
+
+#### Layer 1: Syntax and Style Analysis
+
+1. **Syntax Errors**: Malformed code that won't compile/run
+2. **Style Violations**: Inconsistent formatting, naming conventions
+3. **Dead Code**: Unreachable code, unused variables/functions
+4. **Code Duplication**: Copy-paste code blocks
+
+#### Layer 2: Semantic Analysis
+
+1. **Type Issues**: Type mismatches, implicit conversions
+2. **Logic Errors**: Always true/false conditions, impossible states
+3. **Resource Leaks**: Unclosed files, unreleased memory
+4. **API Misuse**: Incorrect parameter order, deprecated methods
+
+#### Layer 3: Flow Analysis
+
+1. **Control Flow**: Infinite loops, unreachable code, missing returns
+2. **Data Flow**: Uninitialized variables, unused assignments
+3. **Exception Flow**: Unhandled exceptions, empty catch blocks
+4. **Null Flow**: Potential null dereferences
+
+#### Layer 4: Security Analysis
+
+1. **Injection Vulnerabilities**: SQL, XSS, command injection
+2. **Authentication Issues**: Hardcoded credentials, weak crypto
+3. **Data Exposure**: Sensitive data in logs, unencrypted storage
+4. **Access Control**: Missing authorization, privilege escalation
+
+### Phase 2: Pattern Detection
+
+#### Anti-Patterns to Detect
+
+**Code Smells:**
+
+```
+- God Classes/Functions (too much responsibility)
+- Long Parameter Lists (>3-4 parameters)
+- Feature Envy (excessive external data access)
+- Data Clumps (repeated parameter groups)
+- Primitive Obsession (overuse of primitives)
+- Switch Statements (missing polymorphism)
+- Lazy Class (too little responsibility)
+- Speculative Generality (unused abstraction)
+- Message Chains (deep coupling)
+- Middle Man (unnecessary delegation)
+```
+
+**Performance Issues:**
+
+```
+- N+1 Queries (database inefficiency)
+- Synchronous I/O in async context
+- Inefficient Algorithms (O(n²) when O(n) possible)
+- Memory Leaks (retained references)
+- Excessive Object Creation (GC pressure)
+- String Concatenation in Loops
+- Missing Indexes (database)
+- Blocking Operations (thread starvation)
+```
+
+**Concurrency Issues:**
+
+```
+- Race Conditions (unsynchronized access)
+- Deadlocks (circular wait)
+- Thread Leaks (unclosed threads)
+- Missing Volatile (visibility issues)
+- Double-Checked Locking (broken pattern)
+- Lock Contention (performance bottleneck)
+```
+
+### Phase 3: Complexity Analysis
+
+#### Metrics Calculation
+
+1. **Cyclomatic Complexity**: Number of linearly independent paths
+2. **Cognitive Complexity**: How difficult code is to understand
+3. **Halstead Metrics**: Program vocabulary and difficulty
+4. **Maintainability Index**: Composite maintainability score
+5. **Technical Debt**: Estimated time to fix all issues
+6. **Test Coverage**: Lines/branches/functions covered
+
+#### Thresholds
+
+```
+Cyclomatic Complexity:
+- Good: < 10
+- Acceptable: 10-20
+- Complex: 20-50
+- Untestable: > 50
+
+Cognitive Complexity:
+- Simple: < 5
+- Moderate: 5-10
+- Complex: 10-15
+- Very Complex: > 15
+```
+
+### Phase 4: Dependency Analysis
+
+#### Identify Issues
+
+1. **Circular Dependencies**: A→B→C→A cycles
+2. **Version Conflicts**: Incompatible dependency versions
+3. **Security Vulnerabilities**: Known CVEs in dependencies
+4. **License Conflicts**: Incompatible license combinations
+5. **Outdated Packages**: Dependencies needing updates
+6. **Unused Dependencies**: Declared but not used
+
+### Phase 5: Architecture Analysis
+
+#### Structural Issues
+
+1. **Layer Violations**: Cross-layer dependencies
+2. **Module Coupling**: High interdependence
+3. **Missing Abstractions**: Direct implementation dependencies
+4. **Inconsistent Patterns**: Mixed architectural styles
+5. **God Objects**: Central points of failure
+
+## Automated Tools Integration
+
+Simulate output from common static analysis tools:
+
+**ESLint/TSLint** (JavaScript/TypeScript)
+**Pylint/Flake8** (Python)
+**SonarQube** (Multi-language)
+**PMD/SpotBugs** (Java)
+**RuboCop** (Ruby)
+**SwiftLint** (Swift)
+
+## Output Format
+
+````markdown
+# Static Analysis Report
+
+## Executive Summary
+
+**Files Analyzed:** [count]
+**Total Issues:** [count]
+**Critical:** [count] | **High:** [count] | **Medium:** [count] | **Low:** [count]
+**Technical Debt:** [hours/days estimated]
+**Code Coverage:** [percentage]
+
+## Critical Issues (Immediate Action Required)
+
+### Issue 1: [Security Vulnerability]
+
+**File:** [path:line]
+**Category:** Security
+**Rule:** [CWE-ID or rule name]
+
+```[language]
+// Vulnerable code
+[code snippet]
+```
+````
+
+**Risk:** [Description of security risk]
+**Fix:**
+
+```[language]
+// Secure code
+[fixed code]
+```
+
+### Issue 2: [Logic Error]
+
+[Similar format]
+
+## High Priority Issues
+
+### Category: Performance
+
+| File | Line | Issue | Impact | Fix Effort |
+| ------ | ------ | --------------- | ------------ | ---------- |
+| [file] | [line] | N+1 Query | High latency | 2 hours |
+| [file] | [line] | O(n²) algorithm | CPU spike | 4 hours |
+
+### Category: Reliability
+
+[Similar table format]
+
+## Code Quality Metrics
+
+### Complexity Analysis
+
+| File | Cyclomatic | Cognitive | Maintainability | Action |
+| ------ | ---------- | --------- | --------------- | -------- |
+| [file] | 45 (High) | 28 (High) | 35 (Low) | Refactor |
+| [file] | 32 (Med) | 18 (Med) | 55 (Med) | Review |
+
+### Duplication Analysis
+
+**Total Duplication:** [percentage]
+**Largest Duplicate:** [lines] lines in [files]
+
+### Top Duplicated Blocks:
+
+1. [File A:lines] ↔ [File B:lines] - [line count] lines
+2. [File C:lines] ↔ [File D:lines] - [line count] lines
+
+## Anti-Pattern Detection
+
+### God Classes
+
+1. **[ClassName]** - [methods] methods, [lines] lines
+ - Responsibilities: [list]
+ - Suggested Split: [recommendations]
+
+### Long Methods
+
+1. **[methodName]** - [lines] lines, complexity: [score]
+ - Extract Methods: [suggestions]
+
+## Security Scan Results
+
+### Vulnerabilities by Category
+
+- Injection: [count]
+- Authentication: [count]
+- Data Exposure: [count]
+- Access Control: [count]
+
+### Detailed Findings
+
+[List each with severity, location, and fix]
+
+## Dependency Analysis
+
+### Security Vulnerabilities
+
+| Package | Version | CVE | Severity | Fixed Version |
+| ------- | ------- | -------- | -------- | ------------- |
+| [pkg] | [ver] | [CVE-ID] | Critical | [ver] |
+
+### Outdated Dependencies
+
+| Package | Current | Latest | Breaking Changes |
+| ------- | ------- | ------ | ---------------- |
+| [pkg] | [ver] | [ver] | [Yes/No] |
+
+## Recommendations
+
+### Immediate Actions (This Sprint)
+
+1. Fix all critical security vulnerabilities
+2. Resolve high-severity logic errors
+3. Update vulnerable dependencies
+
+### Short-term (Next Sprint)
+
+1. Refactor high-complexity functions
+2. Remove code duplication
+3. Add missing error handling
+
+### Long-term (Technical Debt)
+
+1. Architectural improvements
+2. Comprehensive refactoring
+3. Test coverage improvement
+
+## Trend Analysis
+
+**Compared to Last Scan:**
+
+- Issues: [+/-X]
+- Complexity: [+/-Y]
+- Coverage: [+/-Z%]
+- Technical Debt: [+/-N hours]
+
+```
+
+## Completion Criteria
+- [ ] All analysis layers completed
+- [ ] Issues categorized by severity
+- [ ] Metrics calculated
+- [ ] Anti-patterns identified
+- [ ] Security vulnerabilities found
+- [ ] Dependencies analyzed
+- [ ] Recommendations prioritized
+- [ ] Fixes suggested for critical issues
+```
diff --git a/src/modules/bmm/workflows/debug/static-scan/workflow.yaml b/src/modules/bmm/workflows/debug/static-scan/workflow.yaml
index ff3dae5a..b29ec510 100644
--- a/src/modules/bmm/workflows/debug/static-scan/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/static-scan/workflow.yaml
@@ -1,11 +1,67 @@
-# Static Scan Workflow Configuration
-name: "static-scan"
-description: "Perform comprehensive static analysis for common defects using automated tools and manual inspection."
-author: "Diana"
+# Debug Workflow: Static Analysis Scan
+name: debug-static-scan
+description: "Perform comprehensive static analysis for common defects. Identifies anti-patterns, security issues, and code smells."
+author: "BMad Core"
+version: "2.0"
+# BMAD Core Configuration
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
installed_path: "{project-root}/bmad/bmm/workflows/debug/static-scan"
instructions: "{installed_path}/instructions.md"
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/common-defects.md"
-standalone: true
+template: false
+
+# Knowledge Base Requirements (BMAD Core)
+knowledge_dependencies:
+ - "{project-root}/bmad/bmm/knowledge/debug/common-defects.md"
+ - "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
+
+tags:
+ - debug
+ - static-analysis
+ - security
+ - quality
+ - bmad-core
+
+execution_hints:
+ interactive: false
+ autonomous: true
+ iterative: false
+ validation_required: true
+ comprehensive: true
+
+# BMAD Core Workflow Steps
+steps:
+ - id: "load_config"
+ name: "Load Configuration"
+ type: "config"
+ required: true
+
+ - id: "load_knowledge"
+ name: "Load Knowledge Base"
+ type: "knowledge"
+ dependencies: "knowledge_dependencies"
+ required: true
+
+ - id: "execute_workflow"
+ name: "Execute Static Analysis"
+ type: "workflow"
+ source: "instructions"
+ required: true
+ analyzers: ["security", "performance", "maintainability", "reliability"]
+
+ - id: "validate_output"
+ name: "Validate Analysis Results"
+ type: "validation"
+ required: true
+ criteria: ["comprehensive-coverage", "actionable-findings", "risk-prioritized"]
+
+ - id: "save_output"
+ name: "Save Analysis Report"
+ type: "output"
+ destination: "output_folder"
+ required: true
diff --git a/src/modules/bmm/workflows/debug/validate-fix/instructions.md b/src/modules/bmm/workflows/debug/validate-fix/instructions.md
new file mode 100644
index 00000000..b2d56b7c
--- /dev/null
+++ b/src/modules/bmm/workflows/debug/validate-fix/instructions.md
@@ -0,0 +1,103 @@
+# Fix Validation Workflow
+
+Verify proposed fix addresses root cause without introducing side effects.
+
+## Context
+
+This workflow systematically validates that a proposed fix actually addresses the root cause and doesn't introduce new issues or regressions.
+
+## Prerequisites
+
+- Identified root cause
+- Proposed fix (code, configuration, or process change)
+- Understanding of system architecture
+- Access to test suite
+
+## Instructions
+
+### Step 1: Root Cause Alignment
+
+1. Review the identified root cause from analysis
+2. Examine the proposed fix in detail
+3. Verify fix directly addresses root cause (not just symptoms)
+4. Check if fix is complete or requires additional changes
+5. Document alignment assessment
+
+### Step 2: Side Effect Analysis
+
+1. Identify all components affected by the fix
+2. Analyze potential ripple effects
+3. Check for dependency impacts
+4. Review similar code patterns that might be affected
+5. Assess performance implications
+6. Document potential side effects
+
+### Step 3: Regression Risk Assessment
+
+Rate regression risk for each category:
+
+- **Code Changes:** Lines changed, complexity, critical paths
+- **Test Coverage:** Existing test coverage of affected areas
+- **Integration Points:** Number of integration points affected
+- **Deployment Risk:** Configuration or infrastructure changes needed
+
+Risk Levels:
+
+- **High:** Critical paths, low test coverage, many integration points
+- **Medium:** Moderate complexity, good test coverage, some integration points
+- **Low:** Simple changes, high test coverage, isolated changes
+
+### Step 4: Test Strategy Validation
+
+1. Review existing tests covering affected areas
+2. Identify gaps in test coverage
+3. Recommend new tests needed to validate fix
+4. Suggest regression tests to prevent recurrence
+5. Verify test strategy is comprehensive
+
+### Step 5: Validation Recommendations
+
+Provide structured recommendations:
+
+1. **Fix Assessment:** Does fix address root cause? (Yes/No/Partial)
+2. **Regression Risk:** High/Medium/Low with justification
+3. **Required Tests:** List specific tests needed
+4. **Additional Changes:** Any complementary changes needed
+5. **Monitoring:** Metrics or logs to watch post-deployment
+6. **Approval:** Recommend approval status (Approved/Needs Work/Rejected)
+
+## Output Requirements
+
+Generate validation report containing:
+
+- Root cause alignment assessment
+- Side effect analysis with affected components
+- Regression risk matrix by category
+- Test strategy recommendations
+- Monitoring and rollback plan
+- Final recommendation with justification
+
+## Completion Criteria
+
+- [ ] Root cause alignment verified
+- [ ] Side effects identified and documented
+- [ ] Regression risk assessed by category
+- [ ] Test strategy validated and gaps identified
+- [ ] Monitoring recommendations provided
+- [ ] Final approval recommendation given
+
+## Elicitation Points
+
+
+Proposed Fix: Ask user to provide:
+- What is the proposed fix? (code changes, configuration, process)
+- What root cause does it address?
+- What testing has been done?
+
+
+
+Additional Context: Ask if available:
+- Why was this approach chosen?
+- Are there alternative approaches considered?
+- What is the rollback plan?
+
diff --git a/src/modules/bmm/workflows/debug/validate-fix/workflow.yaml b/src/modules/bmm/workflows/debug/validate-fix/workflow.yaml
index 7510c793..70217573 100644
--- a/src/modules/bmm/workflows/debug/validate-fix/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/validate-fix/workflow.yaml
@@ -1,11 +1,67 @@
-# Validate Fix Workflow Configuration
-name: "validate-fix"
-description: "Verify proposed fix addresses root cause without introducing side effects or regressions."
-author: "Diana"
+# Debug Workflow: Fix Validation
+name: debug-validate-fix
+description: "Verify proposed fix addresses root cause without side effects. Includes regression risk assessment."
+author: "BMad Core"
+version: "2.0"
+# BMAD Core Configuration
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
installed_path: "{project-root}/bmad/bmm/workflows/debug/validate-fix"
instructions: "{installed_path}/instructions.md"
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/debug-inspection-checklist.md"
-standalone: true
+template: false
+
+# Knowledge Base Requirements (BMAD Core)
+knowledge_dependencies:
+ - "{project-root}/bmad/bmm/knowledge/debug/common-defects.md"
+ - "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
+
+tags:
+ - debug
+ - validation
+ - quality
+ - risk-assessment
+ - bmad-core
+
+execution_hints:
+ interactive: true
+ autonomous: false
+ iterative: false
+ validation_required: true
+ risk_assessment: true
+
+# BMAD Core Workflow Steps
+steps:
+ - id: "load_config"
+ name: "Load Configuration"
+ type: "config"
+ required: true
+
+ - id: "load_knowledge"
+ name: "Load Knowledge Base"
+ type: "knowledge"
+ dependencies: "knowledge_dependencies"
+ required: true
+
+ - id: "execute_workflow"
+ name: "Execute Fix Validation"
+ type: "workflow"
+ source: "instructions"
+ required: true
+ phases: ["fix-analysis", "regression-check", "side-effects-assessment", "validation"]
+
+ - id: "validate_output"
+ name: "Validate Assessment Results"
+ type: "validation"
+ required: true
+ criteria: ["fix-effectiveness", "risk-assessment-complete", "recommendations-clear"]
+
+ - id: "save_output"
+ name: "Save Validation Report"
+ type: "output"
+ destination: "output_folder"
+ required: true
diff --git a/src/modules/bmm/workflows/debug/walkthrough-prep/instructions.md b/src/modules/bmm/workflows/debug/walkthrough-prep/instructions.md
new file mode 100644
index 00000000..11f98d12
--- /dev/null
+++ b/src/modules/bmm/workflows/debug/walkthrough-prep/instructions.md
@@ -0,0 +1,363 @@
+# walkthrough-prep
+
+Generate comprehensive materials for code walkthrough sessions.
+
+## Context
+
+This task prepares all necessary documentation, checklists, and presentation materials for conducting effective code walkthroughs. It ensures reviewers have everything needed to provide valuable feedback while minimizing meeting time.
+
+## Task Execution
+
+### Phase 1: Scope Analysis
+
+#### Determine Walkthrough Type
+
+1. **Feature Walkthrough**: New functionality
+2. **Bug Fix Walkthrough**: Defect resolution
+3. **Refactoring Walkthrough**: Code improvement
+4. **Architecture Walkthrough**: Design decisions
+5. **Security Walkthrough**: Security-focused review
+
+#### Identify Key Components
+
+1. Changed files and their purposes
+2. Dependencies affected
+3. Test coverage added/modified
+4. Documentation updates
+5. Configuration changes
+
+### Phase 2: Material Generation
+
+#### 1. Executive Summary
+
+Create high-level overview:
+
+- Purpose and goals
+- Business value/impact
+- Technical approach
+- Key decisions made
+- Risks and mitigations
+
+#### 2. Technical Overview
+
+**Architecture Diagram:**
+
+```
+[Component A] → [Component B] → [Component C]
+ ↓ ↓ ↓
+[Database] [External API] [Cache]
+```
+
+**Data Flow:**
+
+```
+1. User Input → Validation
+2. Validation → Processing
+3. Processing → Storage
+4. Storage → Response
+```
+
+**Sequence Diagram:**
+
+```
+User → Frontend: Request
+Frontend → Backend: API Call
+Backend → Database: Query
+Database → Backend: Results
+Backend → Frontend: Response
+Frontend → User: Display
+```
+
+#### 3. Code Change Summary
+
+**Statistics:**
+
+- Files changed: [count]
+- Lines added: [count]
+- Lines removed: [count]
+- Test coverage: [before]% → [after]%
+- Complexity change: [delta]
+
+**Change Categories:**
+
+- New features: [list]
+- Modifications: [list]
+- Deletions: [list]
+- Refactoring: [list]
+
+### Phase 3: Review Checklist Generation
+
+#### Core Review Areas
+
+**Functionality Checklist:**
+
+- [ ] Requirements met
+- [ ] Edge cases handled
+- [ ] Error handling complete
+- [ ] Performance acceptable
+- [ ] Backwards compatibility maintained
+
+**Code Quality Checklist:**
+
+- [ ] Naming conventions followed
+- [ ] DRY principle applied
+- [ ] SOLID principles followed
+- [ ] Comments appropriate
+- [ ] No code smells
+
+**Testing Checklist:**
+
+- [ ] Unit tests added
+- [ ] Integration tests updated
+- [ ] Edge cases tested
+- [ ] Performance tested
+- [ ] Regression tests pass
+
+**Security Checklist:**
+
+- [ ] Input validation implemented
+- [ ] Authentication checked
+- [ ] Authorization verified
+- [ ] Data sanitized
+- [ ] Secrets not exposed
+
+**Documentation Checklist:**
+
+- [ ] Code comments updated
+- [ ] README updated
+- [ ] API docs updated
+- [ ] Changelog updated
+- [ ] Deployment docs updated
+
+### Phase 4: Presentation Structure
+
+#### Slide/Section Outline
+
+**1. Introduction (2 min)**
+
+- Problem statement
+- Solution overview
+- Success criteria
+
+**2. Technical Approach (5 min)**
+
+- Architecture decisions
+- Implementation choices
+- Trade-offs made
+
+**3. Code Walkthrough (15 min)**
+
+- Key components tour
+- Critical logic explanation
+- Integration points
+
+**4. Testing Strategy (3 min)**
+
+- Test coverage
+- Test scenarios
+- Performance results
+
+**5. Discussion (5 min)**
+
+- Open questions
+- Concerns
+- Suggestions
+
+### Phase 5: Supporting Documentation
+
+#### Code Snippets
+
+Extract and annotate key code sections:
+
+```[language]
+// BEFORE: Original implementation
+[original code]
+
+// AFTER: New implementation
+[new code]
+
+// KEY CHANGES:
+// 1. [Change 1 explanation]
+// 2. [Change 2 explanation]
+```
+
+#### Test Cases
+
+Document critical test scenarios:
+
+```[language]
+// Test Case 1: [Description]
+// Input: [test input]
+// Expected: [expected output]
+// Covers: [what it validates]
+```
+
+#### Performance Metrics
+
+If applicable:
+
+- Execution time: [before] → [after]
+- Memory usage: [before] → [after]
+- Database queries: [before] → [after]
+
+## Output Format
+
+````markdown
+# Code Walkthrough Package: [Feature/Fix Name]
+
+## Quick Reference
+
+**Date:** [scheduled date]
+**Duration:** [estimated time]
+**Presenter:** [name]
+**Reviewers:** [list]
+**Repository:** [link]
+**Branch/PR:** [link]
+
+## Executive Summary
+
+[2-3 paragraph overview]
+
+## Agenda
+
+1. Introduction (2 min)
+2. Technical Overview (5 min)
+3. Code Walkthrough (15 min)
+4. Testing & Validation (3 min)
+5. Q&A (5 min)
+
+## Pre-Review Checklist
+
+**For Reviewers - Complete Before Meeting:**
+
+- [ ] Read executive summary
+- [ ] Review changed files list
+- [ ] Note initial questions
+- [ ] Check test results
+
+## Technical Overview
+
+### Architecture
+
+[Include diagrams]
+
+### Key Changes
+
+| Component | Type | Description | Risk |
+| --------- | ------------- | -------------- | -------------- |
+| [name] | [New/Mod/Del] | [what changed] | [Low/Med/High] |
+
+### Dependencies
+
+**Added:** [list]
+**Modified:** [list]
+**Removed:** [list]
+
+## Code Highlights
+
+### Critical Section 1: [Name]
+
+**File:** [path]
+**Purpose:** [why this is important]
+
+```[language]
+[annotated code snippet]
+```
+````
+
+**Discussion Points:**
+
+- [Question or concern]
+- [Alternative considered]
+
+### Critical Section 2: [Name]
+
+[Similar format]
+
+## Testing Summary
+
+### Coverage
+
+- Unit Tests: [count] tests, [%] coverage
+- Integration Tests: [count] tests
+- Manual Testing: [checklist items]
+
+### Key Test Scenarios
+
+1. [Scenario]: [Result]
+2. [Scenario]: [Result]
+
+## Review Checklist
+
+### Must Review
+
+- [ ] [Critical file/function]
+- [ ] [Security-sensitive code]
+- [ ] [Performance-critical section]
+
+### Should Review
+
+- [ ] [Important logic]
+- [ ] [API changes]
+- [ ] [Database changes]
+
+### Nice to Review
+
+- [ ] [Refactoring]
+- [ ] [Documentation]
+- [ ] [Tests]
+
+## Known Issues & Decisions
+
+### Open Questions
+
+1. [Question needing group input]
+2. [Design decision to validate]
+
+### Technical Debt
+
+- [Debt item]: [Planned resolution]
+
+### Future Improvements
+
+- [Improvement]: [Timeline]
+
+## Post-Review Action Items
+
+**To be filled during review:**
+
+- [ ] Action: [description] - Owner: [name]
+- [ ] Action: [description] - Owner: [name]
+
+## Appendix
+
+### A. Full File List
+
+[Complete list of changed files]
+
+### B. Test Results
+
+[Test execution summary]
+
+### C. Performance Benchmarks
+
+[If applicable]
+
+### D. Related Documentation
+
+- [Design Doc]: [link]
+- [Requirements]: [link]
+- [Previous Reviews]: [link]
+
+```
+
+## Completion Criteria
+- [ ] Scope analyzed
+- [ ] Executive summary written
+- [ ] Technical overview created
+- [ ] Code highlights selected
+- [ ] Review checklist generated
+- [ ] Presentation structure defined
+- [ ] Supporting docs prepared
+- [ ] Package formatted for distribution
+```
diff --git a/src/modules/bmm/workflows/debug/walkthrough-prep/workflow.yaml b/src/modules/bmm/workflows/debug/walkthrough-prep/workflow.yaml
index 45782ae2..1ca78b72 100644
--- a/src/modules/bmm/workflows/debug/walkthrough-prep/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/walkthrough-prep/workflow.yaml
@@ -1,11 +1,28 @@
-# Walkthrough Prep Workflow Configuration
-name: "walkthrough-prep"
-description: "Generate materials for code walkthrough session including inspection guides and focus areas."
-author: "Diana"
+# Debug Workflow: Walkthrough Preparation
+name: debug-walkthrough-prep
+description: "Generate materials for code walkthrough session. Creates review checklist and presentation outline."
+author: "BMad"
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
installed_path: "{project-root}/bmad/bmm/workflows/debug/walkthrough-prep"
-instructions: "{instructions_path}/instructions.md"
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/debug-inspection-checklist.md"
-standalone: true
+instructions: "{installed_path}/instructions.md"
+template: false
+
+knowledge_fragments:
+ - "{project-root}/bmad/bmm/knowledge/debug/debug-inspection-checklist.md"
+
+tags:
+ - debug
+ - code-review
+ - walkthrough
+ - collaboration
+
+execution_hints:
+ interactive: true
+ autonomous: false
+ iterative: false
diff --git a/src/modules/bmm/workflows/debug/wolf-fence/instructions.md b/src/modules/bmm/workflows/debug/wolf-fence/instructions.md
index 0adaf65d..9c4eecce 100644
--- a/src/modules/bmm/workflows/debug/wolf-fence/instructions.md
+++ b/src/modules/bmm/workflows/debug/wolf-fence/instructions.md
@@ -1,42 +1,168 @@
-# Wolf Fence Binary Search Debugging Instructions
+# wolf-fence-search
-## Overview
+Binary search debugging to systematically isolate bug location.
-Execute binary search debugging methodology to efficiently isolate bug location through systematic code region elimination.
+## Context
-## Wolf Fence Principle
+This task implements the Wolf Fence algorithm (binary search debugging) to efficiently locate bugs by repeatedly dividing the search space in half. Named after the problem: "There's one wolf in Alaska; how do you find it? Build a fence down the middle, wait for the wolf to howl, determine which side it's on, and repeat."
-"There's one wolf in Alaska; how do you find it? First build a fence down the middle of the state, wait for the wolf to howl, then go to the side where you heard it."
+## Task Execution
-## Methodology
+### Phase 1: Initial Analysis
-1. **Define Search Space** - Identify code region containing the bug
-2. **Bisection Strategy** - Divide region into two equal parts
-3. **Test Point Selection** - Choose midpoint for testing
-4. **Behavior Verification** - Determine which half contains the bug
-5. **Recursive Narrowing** - Repeat process on identified half
-6. **Isolation Completion** - Continue until bug location is isolated
+1. Identify the boundaries of the problem space:
+ - Entry point where system is working
+ - Exit point where bug manifests
+ - Code path between these points
+2. Determine testable checkpoints
+3. Calculate optimal division points
-## Process Steps
+### Phase 2: Binary Search Implementation
-1. **Establish Known Good/Bad Points** - Verify working and failing states
-2. **Binary Division** - Split code/data/timeline into halves
-3. **Midpoint Testing** - Insert test points or checkpoints
-4. **Result Analysis** - Determine which side exhibits the bug
-5. **Range Refinement** - Focus search on problematic half
-6. **Iteration** - Repeat until precise location identified
+#### Step 1: Divide Search Space
-## Application Scenarios
+1. Identify midpoint of current search area
+2. Insert diagnostic checkpoint at midpoint:
+ - Add assertion to verify expected state
+ - Add logging to capture actual state
+ - Add breakpoint if interactive debugging available
-- Code regression debugging
-- Data corruption location
-- Timeline-based issue isolation
-- Configuration problem hunting
-- Memory corruption detection
+#### Step 2: Test and Observe
-## Expected Outputs
+1. Execute code up to checkpoint
+2. Verify if bug has manifested:
+ - State is correct → Bug is in second half
+ - State is incorrect → Bug is in first half
+ - Cannot determine → Need better checkpoint
-- Precise bug location identification
-- Minimal reproduction case
-- Verification test points
-- Isolated code region for detailed analysis
+#### Step 3: Narrow Focus
+
+1. Select the half containing the bug
+2. Repeat division process
+3. Continue until bug location is isolated to:
+ - Single function
+ - Few lines of code
+ - Specific data transformation
+
+### Phase 3: Refinement
+
+#### For Complex Bugs
+
+1. **Multi-dimensional search**: When bug depends on multiple factors
+ - Apply binary search on each dimension
+ - Create test matrix for combinations
+
+2. **Time-based search**: For timing/concurrency issues
+ - Binary search on execution timeline
+ - Add timestamps to narrow race conditions
+
+3. **Data-based search**: For data-dependent bugs
+ - Binary search on input size
+ - Isolate problematic data patterns
+
+### Phase 4: Bug Isolation
+
+Once narrowed to small code section:
+
+1. Analyze the isolated code thoroughly
+2. Identify exact failure mechanism
+3. Verify bug reproduction in isolation
+4. Document minimal reproduction case
+
+## Automated Implementation
+
+### Checkpoint Generation Strategy
+
+```markdown
+1. Identify all function boundaries in path
+2. Select optimal checkpoint locations:
+ - Function entry/exit points
+ - Loop boundaries
+ - Conditional branches
+ - Data transformations
+
+3. Insert non-invasive checkpoints:
+ - Use existing logging if available
+ - Add temporary assertions
+ - Leverage existing test infrastructure
+```
+
+### Search Optimization
+
+- Start with coarse-grained divisions (module/class level)
+- Progressively move to fine-grained (function/line level)
+- Skip obviously correct sections based on static analysis
+- Prioritize high-probability areas based on:
+ - Recent changes
+ - Historical bug density
+ - Code complexity metrics
+
+## Output Format
+
+````markdown
+# Wolf Fence Debug Analysis
+
+## Search Summary
+
+**Initial Scope:** [entry point] → [exit point]
+**Final Location:** [specific file:line]
+**Iterations Required:** [number]
+**Time to Isolate:** [duration]
+
+## Search Path
+
+### Iteration 1
+
+- **Search Space:** [full range]
+- **Checkpoint:** [location]
+- **Result:** Bug in [first/second] half
+- **Evidence:** [what was observed]
+
+### Iteration 2
+
+- **Search Space:** [narrowed range]
+- **Checkpoint:** [location]
+- **Result:** Bug in [first/second] half
+- **Evidence:** [what was observed]
+
+[Continue for all iterations...]
+
+## Bug Location
+
+**File:** [path]
+**Function:** [name]
+**Lines:** [range]
+**Description:** [what the bug is]
+
+## Minimal Reproduction
+
+```[language]
+// Minimal code to reproduce
+[code snippet]
+```
+````
+
+## Root Cause
+
+[Brief explanation of why bug occurs]
+
+## Recommended Fix
+
+[Suggested solution]
+
+## Verification Points
+
+- [ ] Bug reproducible at isolated location
+- [ ] Fix resolves issue at checkpoint
+- [ ] No regression in other checkpoints
+
+```
+
+## Completion Criteria
+- [ ] Search space properly bounded
+- [ ] Binary search completed
+- [ ] Bug location isolated
+- [ ] Minimal reproduction created
+- [ ] Root cause identified
+- [ ] Fix recommendation provided
+```
diff --git a/src/modules/bmm/workflows/debug/wolf-fence/workflow.yaml b/src/modules/bmm/workflows/debug/wolf-fence/workflow.yaml
index 9ad7cca5..45c9f663 100644
--- a/src/modules/bmm/workflows/debug/wolf-fence/workflow.yaml
+++ b/src/modules/bmm/workflows/debug/wolf-fence/workflow.yaml
@@ -1,33 +1,66 @@
-# Wolf Fence Binary Search Debugging Workflow Configuration
-name: "wolf-fence"
-description: "Execute binary search debugging to isolate bug location efficiently through systematic code region elimination."
-author: "Diana"
+# Debug Workflow: Wolf Fence (Binary Search)
+name: debug-wolf-fence
+description: "Execute binary search debugging to isolate bug location efficiently. Highly effective for large codebases."
+author: "BMad Core"
+version: "2.0"
-# Critical variables from config
+# BMAD Core Configuration
config_source: "{project-root}/bmad/bmm/config.yaml"
output_folder: "{config_source}:output_folder"
user_name: "{config_source}:user_name"
communication_language: "{config_source}:communication_language"
-document_output_language: "{config_source}:document_output_language"
-user_skill_level: "{config_source}:user_skill_level"
date: system-generated
-# Module path and component files
installed_path: "{project-root}/bmad/bmm/workflows/debug/wolf-fence"
-template: false
instructions: "{installed_path}/instructions.md"
+template: false
-# Knowledge base integration
-knowledge_base: "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
+# Knowledge Base Requirements (BMAD Core)
+knowledge_dependencies:
+ - "{project-root}/bmad/bmm/knowledge/debug/debug-patterns.md"
-standalone: true
+tags:
+ - debug
+ - binary-search
+ - isolation
+ - advanced
+ - bmad-core
-web_bundle:
- name: "wolf-fence"
- description: "Execute binary search debugging to isolate bug location efficiently through systematic code region elimination."
- author: "Diana"
- instructions: "bmad/bmm/workflows/debug/wolf-fence/instructions.md"
- template: false
- web_bundle_files:
- - "bmad/bmad/bmm/workflows/debug/wolf-fence/instructions.md"
- - "bmad/bmm/knowledge/debug/debug-patterns.md"
+execution_hints:
+ interactive: true
+ autonomous: false
+ iterative: true
+ validation_required: true
+ systematic: true
+
+# BMAD Core Workflow Steps
+steps:
+ - id: "load_config"
+ name: "Load Configuration"
+ type: "config"
+ required: true
+
+ - id: "load_knowledge"
+ name: "Load Knowledge Base"
+ type: "knowledge"
+ dependencies: "knowledge_dependencies"
+ required: true
+
+ - id: "execute_workflow"
+ name: "Execute Binary Search Debugging"
+ type: "workflow"
+ source: "instructions"
+ required: true
+ strategy: ["divide-and-conquer", "bisection", "isolation"]
+
+ - id: "validate_output"
+ name: "Validate Bug Location"
+ type: "validation"
+ required: true
+ criteria: ["location-identified", "reproduction-confirmed", "evidence-documented"]
+
+ - id: "save_output"
+ name: "Save Wolf Fence Results"
+ type: "output"
+ destination: "output_folder"
+ required: true