fix: debugging workflows and instructions
This commit is contained in:
Marc R Kellerman
parent
3a43c99e4e
commit
2b0fe30f7b
|
|
@ -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
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -0,0 +1,339 @@
|
|||
# <!-- Powered by BMAD™ Core -->
|
||||
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}}
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
<elicit required="true">
|
||||
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?
|
||||
</elicit>
|
||||
|
||||
<elicit required="false">
|
||||
Additional Context: Ask if user can provide:
|
||||
- Related issue/ticket numbers
|
||||
- Recent changes or deployments
|
||||
- Error messages or stack traces
|
||||
- Steps to reproduce
|
||||
</elicit>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,234 @@
|
|||
# <!-- Powered by BMAD™ Core -->
|
||||
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}}
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
<elicit required="true">
|
||||
Issue Description: Ask user to describe:
|
||||
- What is happening?
|
||||
- Expected vs actual behavior
|
||||
- How critical is this?
|
||||
</elicit>
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
<elicit required="true">
|
||||
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)?
|
||||
</elicit>
|
||||
|
||||
<elicit required="false">
|
||||
Additional Context: Ask if available:
|
||||
- Recent changes or deployments
|
||||
- Error messages or logs
|
||||
- Reproduction steps
|
||||
- Related issues or patterns
|
||||
- User reports or feedback
|
||||
</elicit>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,268 @@
|
|||
# <!-- Powered by BMAD™ Core -->
|
||||
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}}
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
<elicit required="true">
|
||||
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?
|
||||
</elicit>
|
||||
|
||||
<elicit required="false">
|
||||
Additional Context: Ask if available:
|
||||
- Why was this approach chosen?
|
||||
- Are there alternative approaches considered?
|
||||
- What is the rollback plan?
|
||||
</elicit>
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue