@pjmendonca/devflow 1.9.0

package/tooling/docs/templates/bug-report.md

@@ -0,0 +1,234 @@
+# Bug Report: [BUG-ID]# Bug Report: [BUG-ID]
+
+
+
+**Severity**: [Critical/High/Medium/Low]**Severity**: [Critical/High/Medium/Low]
+
+**Status**: Open**Status**: Open
+
+**Reported**: YYYY-MM-DD**Reported**: YYYY-MM-DD
+
+**Component**: [affected component/module]**Component**: [affected component/module]
+
+**Regression**: [Yes/No - was this working before?]
+
+## Summary
+
+## Summary
+
+[One-line description of the bug]
+
+[One-line description of the bug]
+
+## Steps to Reproduce
+
+## Steps to Reproduce
+
+1. [First step]
+
+1. [First step]2. [Second step]
+
+2. [Second step]3. [Third step]
+
+3. [Third step]
+
+## Expected Behavior
+
+**Reproducibility**: [Always / Sometimes (X%) / Rare / Unknown]
+
+[What should happen]
+
+## Expected Behavior
+
+## Actual Behavior
+
+[What should happen]
+
+[What actually happens]
+
+## Actual Behavior
+
+## Environment
+
+[What actually happens]
+
+- **OS**: [e.g., macOS 14.0, Windows 11, Ubuntu 22.04]
+
+## Environment- **Version**: [app version or commit hash]
+
+- **Browser/Runtime**: [if applicable]
+
+- **OS**: [e.g., macOS 14.0, Windows 11, Ubuntu 22.04]
+
+- **Version**: [app version or commit hash]## Logs/Screenshots
+
+- **Browser/Runtime**: [if applicable]
+
+- **Device/Hardware**: [if applicable]```
+
+- **Network**: [online/offline/slow connection if relevant][Paste relevant error logs here]
+
+```
+
+## Logs/Screenshots
+
+## Possible Root Cause
+
+```
+
+[Paste relevant error logs here][If you have any ideas about what might be causing this]
+
+```
+
+## Related Files
+
+## Root Cause Analysis
+
+- `path/to/file1.ts` - [why this file might be relevant]
+
+### 5 Whys Analysis- `path/to/file2.ts` - [why this file might be relevant]
+
+
+
+Use this technique to dig deeper into the root cause:## Notes
+
+
+
+1. **Why did this happen?**[Any additional context or information]
+
+   [First level cause]
+
+---
+
+2. **Why did that happen?**
+
+   [Second level cause]**To fix this bug, run:**
+
+```bash
+
+3. **Why did that happen?**./run-story.sh [BUG-ID] --bugfix
+
+   [Third level cause]```
+
+
+4. **Why did that happen?**
+   [Fourth level cause]
+
+5. **Why did that happen?**
+   [Root cause - this is usually the systemic issue]
+
+### Fault Tree
+
+Visualize possible causes:
+
+```
+[Bug Symptom]
+├── [Possible Cause A]
+│   ├── [Sub-cause A1]
+│   └── [Sub-cause A2]
+├── [Possible Cause B]
+│   └── [Sub-cause B1]
+└── [Possible Cause C] ← [Most likely]
+```
+
+### Root Cause Category
+
+Check the category that best describes this bug:
+
+- [ ] **Code Logic** - Algorithm or logic error
+- [ ] **Data Handling** - Incorrect data processing/validation
+- [ ] **State Management** - Race condition or state corruption
+- [ ] **Integration** - API/service communication issue
+- [ ] **Configuration** - Misconfiguration or environment issue
+- [ ] **Resource** - Memory, CPU, or resource exhaustion
+- [ ] **Concurrency** - Threading or async timing issue
+- [ ] **Edge Case** - Unhandled boundary condition
+- [ ] **Dependency** - Third-party library issue
+- [ ] **User Input** - Invalid input not properly handled
+- [ ] **Unknown** - Requires further investigation
+
+### Hypothesis
+
+**Most Likely Cause**: [Your best hypothesis about what's causing this]
+
+**Evidence Supporting This**:
+- [Evidence 1]
+- [Evidence 2]
+
+**Evidence Against This**:
+- [Counter-evidence 1]
+
+### Investigation Steps Taken
+
+| Step | What I Checked | Result |
+|------|----------------|--------|
+| 1 | [e.g., Checked logs] | [What I found] |
+| 2 | [e.g., Added debug output] | [What I found] |
+| 3 | [e.g., Tested in isolation] | [What I found] |
+
+## Related Files
+
+| File | Relevance | Confidence |
+|------|-----------|------------|
+| `path/to/file1.ts` | [why relevant] | High/Medium/Low |
+| `path/to/file2.ts` | [why relevant] | High/Medium/Low |
+
+## Impact Analysis
+
+### Users Affected
+- [ ] All users
+- [ ] Specific user segment: [describe]
+- [ ] Internal only
+- [ ] Rare edge case
+
+### Workaround Available
+- [ ] **Yes**: [describe workaround]
+- [ ] **No**: Users are blocked
+
+### Related Issues
+- Related to: #[issue-number]
+- Blocks: #[issue-number]
+- Caused by: [commit/PR reference]
+
+## Proposed Fix
+
+### Approach
+[Brief description of the fix approach]
+
+### Files to Modify
+1. `path/to/file1.ts` - [what to change]
+2. `path/to/file2.ts` - [what to change]
+
+### Tests to Add
+- [ ] Unit test for [specific scenario]
+- [ ] Integration test for [specific scenario]
+- [ ] Regression test to prevent recurrence
+
+### Rollback Plan
+[How to revert if the fix causes issues]
+
+## Prevention
+
+### How to Prevent Similar Bugs
+
+- [ ] Add input validation for [specific case]
+- [ ] Add automated test for [scenario]
+- [ ] Add monitoring/alerting for [condition]
+- [ ] Update documentation about [edge case]
+- [ ] Code review checklist item for [pattern]
+
+## Notes
+
+[Any additional context or information]
+
+---
+
+**To fix this bug, run:**
+```bash
+./run-story.sh [BUG-ID] --bugfix
+```
+
+**To investigate first:**
+```bash
+./run-story.sh [BUG-ID] --investigate
+```

package/tooling/docs/templates/migration-spec.md

@@ -0,0 +1,274 @@
+# Migration Specification: [MIGRATION-ID]
+
+**Priority**: [Critical/High/Medium/Low]
+**Status**: Planned
+**Created**: YYYY-MM-DD
+**Target Date**: YYYY-MM-DD
+**Estimated Downtime**: [None/Minutes/Hours]
+**Risk Level**: [Low/Medium/High/Critical]
+
+## Overview
+
+[Brief description of what is being migrated]
+
+## Motivation
+
+[Why this migration is necessary]
+
+- [Reason 1]
+- [Reason 2]
+- [Reason 3]
+
+## Current State
+
+| Component | Current Version | Target Version | Notes |
+|-----------|-----------------|----------------|-------|
+| [Dependency/Framework] | [current] | [target] | [breaking changes?] |
+
+## Impact Analysis
+
+### Users/Systems Affected
+- [ ] All users
+- [ ] Internal systems only
+- [ ] Specific feature: [describe]
+- [ ] Background processes
+
+### Risk Assessment
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| [Risk 1] | Low/Med/High | Low/Med/High | [Strategy] |
+| [Risk 2] | Low/Med/High | Low/Med/High | [Strategy] |
+
+## Pre-Migration Checklist
+
+### Preparation (1-2 weeks before)
+- [ ] Create rollback point: `./rollback-migration.sh --create [MIGRATION-ID]-pre`
+- [ ] Backup database (if applicable)
+- [ ] Review breaking changes documentation
+- [ ] Update test environment
+- [ ] Run full test suite on current version
+- [ ] Notify stakeholders
+- [ ] Schedule maintenance window (if needed)
+
+### Day Before
+- [ ] Verify rollback point exists
+- [ ] Test rollback procedure in staging
+- [ ] Confirm all team members are available
+- [ ] Prepare communication for users
+
+### Immediately Before
+- [ ] Final backup check
+- [ ] Verify monitoring is active
+- [ ] Clear deployment queue
+
+## Migration Steps
+
+### Phase 1: Preparation
+1. **Create rollback checkpoint**
+   ```bash
+   cd tooling/scripts
+   ./rollback-migration.sh --create [MIGRATION-ID]-pre
+   ```
+
+2. **Verify current state**
+   ```bash
+   # Run tests before migration
+   [test command here]
+   ```
+
+### Phase 2: Dependencies
+1. **Update package files**
+   - Files affected: `package.json` / `pubspec.yaml` / `requirements.txt`
+   - Changes:
+     ```diff
+     - "package": "^old-version"
+     + "package": "^new-version"
+     ```
+
+2. **Install new dependencies**
+   ```bash
+   # npm / yarn / flutter pub get / pip install
+   [install command]
+   ```
+
+### Phase 3: Code Changes
+1. **[Change Description 1]**
+   - Files affected: `path/to/file`
+   - Changes needed: [describe the code changes]
+   
+2. **[Change Description 2]**
+   - Files affected: `path/to/file`
+   - Changes needed: [describe the code changes]
+
+3. **[Change Description 3]**
+   - Files affected: `path/to/file`
+   - Changes needed: [describe the code changes]
+
+### Phase 4: Configuration
+1. **Update configuration files**
+   - Files: `config/...`
+   - Changes: [describe]
+
+### Phase 5: Verification
+1. **Run test suite**
+   ```bash
+   [test command]
+   ```
+
+2. **Manual smoke test**
+   - [ ] [Critical path 1]
+   - [ ] [Critical path 2]
+   - [ ] [Critical path 3]
+
+## Post-Migration
+
+- [ ] Run full test suite
+- [ ] Verify all critical paths manually
+- [ ] Check error logs for anomalies
+- [ ] Monitor performance metrics
+- [ ] Update documentation
+- [ ] Notify stakeholders of completion
+- [ ] Keep rollback point for [X days]
+
+## Breaking Changes
+
+| Change | What Breaks | How to Fix | Automated? |
+|--------|-------------|------------|------------|
+| [Change 1] | [What breaks] | [How to fix] | Yes/No |
+| [Change 2] | [What breaks] | [How to fix] | Yes/No |
+
+## Rollback Plan
+
+### Rollback Triggers
+Execute rollback if ANY of these occur:
+- [ ] Test suite failure rate > [X]%
+- [ ] Critical functionality broken
+- [ ] Performance degradation > [X]%
+- [ ] User-reported blocking issues
+- [ ] Deployment time exceeds [X] hours
+
+### Automated Rollback
+
+```bash
+# Quick rollback using saved checkpoint
+cd tooling/scripts
+./rollback-migration.sh [MIGRATION-ID]
+
+# Or restore from specific point
+./rollback-migration.sh --restore [MIGRATION-ID]-pre
+```
+
+### Manual Rollback Steps
+
+If automated rollback fails:
+
+1. **Restore dependencies**
+   ```bash
+   # Restore package files from backup
+   git checkout [pre-migration-commit] -- package.json package-lock.json
+   # Reinstall
+   npm install
+   ```
+
+2. **Restore code changes**
+   ```bash
+   # Revert to pre-migration commit
+   git checkout [pre-migration-commit] -- src/
+   ```
+
+3. **Restore configuration**
+   ```bash
+   git checkout [pre-migration-commit] -- config/
+   ```
+
+4. **Verify rollback**
+   ```bash
+   [test command]
+   ```
+
+5. **Notify stakeholders**
+   - Reason for rollback
+   - Next steps
+   - Timeline for retry
+
+### Rollback Verification
+- [ ] All tests pass
+- [ ] Critical paths working
+- [ ] No data corruption
+- [ ] Performance restored
+
+## Testing Plan
+
+### Automated Tests
+- [ ] Unit tests pass
+- [ ] Integration tests pass
+- [ ] E2E tests pass
+- [ ] Performance benchmarks acceptable
+
+### Manual Testing Checklist
+- [ ] [Critical user flow 1]
+- [ ] [Critical user flow 2]
+- [ ] [Edge case 1]
+- [ ] [Edge case 2]
+
+### Regression Tests
+- [ ] [Feature that might regress 1]
+- [ ] [Feature that might regress 2]
+
+## Communication Plan
+
+### Before Migration
+- **Who**: [stakeholders]
+- **When**: [X days before]
+- **What**: [brief about upcoming changes]
+
+### During Migration
+- **Channel**: [Slack/Email/Status page]
+- **Updates**: Every [X] minutes
+
+### After Migration
+- **Success**: [communication template]
+- **Failure/Rollback**: [communication template]
+
+## Dependencies
+
+| Dependency | Status | Owner | Notes |
+|------------|--------|-------|-------|
+| [Dep 1] | Ready/Pending | [Name] | [Notes] |
+| [Dep 2] | Ready/Pending | [Name] | [Notes] |
+
+## Lessons Learned
+
+*To be filled after migration*
+
+### What Went Well
+- 
+
+### What Could Be Improved
+- 
+
+### Action Items
+- 
+
+## Notes
+
+[Additional context, links to documentation, etc.]
+
+---
+
+**Commands:**
+
+```bash
+# Create pre-migration checkpoint
+./rollback-migration.sh --create [MIGRATION-ID]-pre
+
+# Run migration with Claude
+./run-story.sh [MIGRATION-ID] --migrate
+
+# Rollback if needed
+./rollback-migration.sh [MIGRATION-ID]
+
+# Preview rollback without executing
+./rollback-migration.sh [MIGRATION-ID] --dry-run
+```

package/tooling/docs/templates/refactor-spec.md

@@ -0,0 +1,86 @@
+# Refactoring Specification: [REFACTOR-ID]
+
+**Priority**: [High/Medium/Low]
+**Status**: Planned
+**Created**: YYYY-MM-DD
+**Estimated Effort**: [Small/Medium/Large]
+
+## Target
+
+[What code/component/module is being refactored]
+
+## Current State
+
+[Description of the current implementation and its problems]
+
+### Pain Points
+
+- [Pain point 1]
+- [Pain point 2]
+- [Pain point 3]
+
+### Code Smells
+
+- [ ] Long methods
+- [ ] Duplicate code
+- [ ] Complex conditionals
+- [ ] Poor naming
+- [ ] Missing abstractions
+- [ ] Tight coupling
+- [ ] Other: [describe]
+
+## Desired State
+
+[Description of what the code should look like after refactoring]
+
+### Goals
+
+- [ ] Improve readability
+- [ ] Reduce duplication
+- [ ] Improve testability
+- [ ] Improve performance
+- [ ] Reduce complexity
+- [ ] Other: [describe]
+
+## Affected Files
+
+| File | Changes |
+|------|---------|
+| `path/to/file1.ts` | [brief description] |
+| `path/to/file2.ts` | [brief description] |
+
+## Approach
+
+### Phase 1: [Name]
+[Description of first phase]
+
+### Phase 2: [Name]
+[Description of second phase]
+
+## Testing Strategy
+
+- [ ] Existing tests should continue to pass
+- [ ] Add tests for: [specific areas]
+- [ ] Manual testing needed for: [specific scenarios]
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| [Risk 1] | [How to mitigate] |
+| [Risk 2] | [How to mitigate] |
+
+## Rollback Plan
+
+[How to revert if something goes wrong]
+
+## Notes
+
+[Any additional context]
+
+---
+
+**To run this refactoring:**
+```bash
+./run-story.sh [REFACTOR-ID] --refactor
+```

package/tooling/docs/templates/tech-debt.md

@@ -0,0 +1,86 @@
+# Technical Debt: [DEBT-ID]
+
+**Priority**: [Critical/High/Medium/Low]
+**Status**: Identified
+**Created**: YYYY-MM-DD
+**Category**: [Code Quality/Architecture/Dependencies/Testing/Documentation]
+
+## Summary
+
+[One-line description of the technical debt]
+
+## Description
+
+[Detailed description of the technical debt and its impact]
+
+## Impact
+
+### Current Pain
+- [How this affects developers]
+- [How this affects performance]
+- [How this affects maintainability]
+
+### Risk if Not Addressed
+- [Risk 1]
+- [Risk 2]
+
+### Business Impact
+- [Slower feature development]
+- [Increased bug rate]
+- [Other impacts]
+
+## Location
+
+| File/Component | Issue |
+|----------------|-------|
+| `path/to/file1` | [specific issue] |
+| `path/to/file2` | [specific issue] |
+
+## Root Cause
+
+[How did this debt accumulate?]
+
+- [ ] Time pressure
+- [ ] Lack of understanding
+- [ ] Changing requirements
+- [ ] Outdated dependencies
+- [ ] Missing tests
+- [ ] Other: [describe]
+
+## Proposed Resolution
+
+### Option A: [Name]
+- **Effort**: [estimate]
+- **Risk**: [low/medium/high]
+- **Description**: [approach]
+
+### Option B: [Name]
+- **Effort**: [estimate]
+- **Risk**: [low/medium/high]
+- **Description**: [approach]
+
+### Recommended: [Option X]
+[Why this option is recommended]
+
+## Success Criteria
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] All existing tests pass
+- [ ] No performance regression
+
+## Dependencies
+
+- [What needs to happen first]
+- [Related debt items]
+
+## Notes
+
+[Additional context]
+
+---
+
+**To resolve this tech debt:**
+```bash
+./run-story.sh [DEBT-ID] --tech-debt
+```