@codemcp/workflows 5.2.4 → 6.0.1

package/resources/workflows/sdd-bugfix.yaml

@@ -0,0 +1,381 @@
+# yaml-language-server: $schema=../state-machine-schema.json
+---
+name: 'sdd-bugfix'
+description: 'Test and specification-driven bugfix workflow: Reproduce → Specify → Test → Plan → Fix → Verify'
+initial_state: 'reproduce'
+
+# Enhanced metadata for better discoverability
+metadata:
+  domain: 'sdd'
+  complexity: 'medium'
+  bestFor:
+    - 'Systematic bug fixing'
+    - 'Test-driven bug resolution'
+    - 'Specification-driven debugging'
+    - 'Quality-focused fixes'
+  useCases:
+    - 'Fix complex bugs with clear specification'
+    - 'Resolve issues with comprehensive testing'
+    - 'Debug problems requiring systematic approach'
+  examples:
+    - 'Fix authentication flow bug with test coverage'
+    - 'Resolve data corruption issue with specification'
+    - 'Debug performance problem with systematic approach'
+
+# States with default instructions and transitions
+states:
+  reproduce:
+    description: 'Reproduce and understand the bug systematically'
+    default_instructions: |
+      **Systematically reproduce and understand the bug** to create a solid foundation for specification-driven fixing.
+
+      **STEP 1: Gather Comprehensive Information**
+      - Identify exact OS, browser/runtime versions, and hardware specs
+      - Document the precise sequence of actions that trigger the bug
+      - Collect error messages, logs, or stack traces
+      - Determine if bug occurs consistently or intermittently
+      - Assess how many users are affected and the business impact
+
+      **STEP 2: Create Reproduction Cases**
+      - Develop minimal, reliable reproduction steps
+      - Document the exact environment and conditions
+      - Create test data or scenarios that trigger the issue
+      - Verify the bug occurs consistently
+
+      **STEP 3: Understand the Problem**
+      - Clarify current (buggy) behavior
+      - Specify correct behavior that should occur
+      - Distinguish symptoms from root cause
+      - Identify related issues or edge cases
+
+      **STEP 4: Document Findings**
+      - Create `$VIBE_DIR/specs/$BRANCH_NAME/reproduction.md` with detailed reproduction steps
+      - Include error logs, screenshots, or other evidence
+      - Document the gap between expected and actual behavior
+
+      **Output**: Clear, reliable reproduction case to verify the fix later.
+
+    transitions:
+      - trigger: 'bug_reproduced'
+        to: 'specify'
+        transition_reason: 'Bug reproduced successfully, ready to specify correct behavior'
+
+      - trigger: 'bug_not_reproducible'
+        to: 'reproduce'
+        instructions: >
+          Gather more details about the environment, conditions, or steps that might be missing from the current information.
+          Contact the reporter for additional information if needed.
+        transition_reason: 'Bug could not be reproduced, need more information'
+
+  specify:
+    description: 'Create specification of correct behavior'
+    default_instructions: |
+      **Create a clear specification of the correct behavior** to guide the fix and prevent regressions.
+
+      **STEP 1: Define Correct Behavior**
+      - Describe what should happen in the scenario that currently fails
+      - Specify expected outcomes for users
+      - Clarify system behavior in edge cases
+      - Document business rules that should be enforced
+
+      **STEP 2: Handle Ambiguities**
+      - Make informed decisions about unclear requirements
+      - Use `[NEEDS CLARIFICATION: question]` only for critical ambiguities (max 3)
+      - Prioritize: correctness > user experience > technical details
+
+      **STEP 3: Ensure Quality Standards**
+      - Focus on user impact and business value
+      - Avoid implementation details
+      - Ensure all requirements are testable
+      - Make success criteria measurable
+
+      **STEP 4: Document Specification**
+      - Create `$VIBE_DIR/specs/$BRANCH_NAME/bug-spec.md` using the template provided below
+    additional_instructions: |
+      **Bug Specification Template:**
+
+      Use this template to create your `bug-spec.md` file:
+
+      ```markdown
+      # Bug Fix Specification: [BUG TITLE]
+
+      **Created**: [DATE]
+      **Bug Report**: [Reference to original bug report]
+
+      ## Current Problem
+
+      **Description**: [Clear description of the bug and its impact]
+
+      **Symptoms**: [What users experience when the bug occurs]
+
+      **Impact**: [Business impact, user frustration, data issues, etc.]
+
+      ## Expected Behavior
+
+      **Correct Functionality**: [Detailed specification of how it should work]
+
+      **User Experience**: [How users should be able to interact with the fixed system]
+
+      **Business Rules**: [Rules that should be enforced]
+
+      ## User Scenarios
+
+      ### Scenario 1 - [Primary Fix Scenario]
+
+      **Given** [initial state]
+      **When** [action that currently fails]
+      **Then** [expected correct outcome]
+
+      ### Scenario 2 - [Edge Case Scenario]
+
+      **Given** [edge case state]
+      **When** [edge case action]
+      **Then** [expected correct outcome]
+
+      [Add more scenarios as needed]
+
+      ## Functional Requirements
+
+      - **FR-001**: System MUST [correct behavior requirement]
+      - **FR-002**: System MUST [error handling requirement]
+      - **FR-003**: System MUST [data integrity requirement]
+      - **FR-004**: System MUST [user feedback requirement]
+
+      ## Success Criteria
+
+      ### Fix Validation
+
+      - **SC-001**: Original reproduction case no longer occurs
+      - **SC-002**: All user scenarios work as specified
+      - **SC-003**: [Performance/reliability metric if applicable]
+      - **SC-004**: No regressions in related functionality
+
+      ### User Impact
+
+      - **SC-005**: [Measurable improvement in user experience]
+      - **SC-006**: [Reduction in error rates or support tickets]
+
+      ## Edge Cases
+
+      - What happens when [boundary condition]?
+      - How does system handle [error scenario]?
+      - What about [related functionality]?
+
+      ## Assumptions
+
+      - [Document any assumptions about correct behavior]
+      - [Include decisions made about ambiguous requirements]
+
+      ## Dependencies
+
+      - [Related systems that must continue working]
+      - [Integration points that must be preserved]
+      ```
+
+      Fill in all sections with specific details about the correct behavior that should replace the current buggy behavior.
+
+    transitions:
+      - trigger: 'specification_complete'
+        to: 'test'
+        transition_reason: 'Bug specification completed, ready to create tests'
+
+      - trigger: 'needs_clarification'
+        to: 'specify'
+        instructions: >
+          Present structured questions to stakeholders about unresolved clarifications in the bug specification.
+          Wait for their responses, then update the specification accordingly.
+        transition_reason: 'Bug specification needs clarification before proceeding'
+
+  test:
+    description: 'Create comprehensive tests that capture the bug and expected behavior'
+    default_instructions: |
+      **Create comprehensive tests** that capture both the current bug and the expected correct behavior to guide the fix and prevent regressions.
+
+      **STEP 1: Create Failing Tests for Current Bug**
+      - Write tests that demonstrate the current buggy behavior
+      - These tests should fail initially (Red phase of TDD)
+      - Cover the main reproduction case and related scenarios
+      - Include edge cases and boundary conditions
+
+      **STEP 2: Create Tests for Expected Behavior**
+      - Write tests that specify the correct behavior from `$VIBE_DIR/specs/$BRANCH_NAME/bug-spec.md`
+      - These tests should pass once the bug is fixed
+      - Cover all functional requirements from the specification
+      - Include user scenarios and success criteria
+
+      **STEP 3: Create Regression Tests**
+      - Write tests for related functionality that should not be affected
+      - Ensure the fix doesn't break existing features
+      - Test integration points and dependencies
+
+      **STEP 4: Organize Test Suite**
+      - Group tests by functionality and user scenarios
+      - Use clear, descriptive test names
+      - Include both unit and integration tests as appropriate
+      - Document test setup and data requirements
+
+      **Output**: Comprehensive test suite in appropriate test files to guide the fix implementation.
+
+    transitions:
+      - trigger: 'tests_created'
+        to: 'plan'
+        transition_reason: 'Tests created for bug and expected behavior, ready to plan the fix'
+
+  plan:
+    description: 'Plan the fix approach with constitutional compliance'
+    default_instructions: |
+      **Plan the fix approach** to ensure the solution aligns with system architecture and quality principles.
+
+      **STEP 1: Load Context**
+      - Read bug specification from `$VIBE_DIR/specs/$BRANCH_NAME/bug-spec.md`
+      - Review reproduction case from `$VIBE_DIR/specs/$BRANCH_NAME/reproduction.md`
+      - Understand the test requirements
+      - Analyze existing codebase and architecture
+
+      **STEP 2: Perform Root Cause Analysis**
+      - Identify the underlying cause of the bug
+      - Understand why the current implementation fails
+      - Map the problem to specific code areas or logic flaws
+      - Consider systemic issues vs. isolated bugs
+
+      **STEP 3: Design Fix Strategy**
+      - Design minimal, targeted fix that addresses root cause
+      - Ensure fix aligns with existing architectural patterns
+      - Consider impact on related functionality
+      - Plan for backward compatibility if needed
+
+      **STEP 4: Verify Constitutional/Quality Compliance**
+      - Ensure fix follows system design principles
+      - Verify approach maintains code quality standards
+      - Check that fix doesn't introduce technical debt
+      - Validate solution is maintainable and testable
+
+      **STEP 5: Create Implementation Plan**
+      - Break down fix into specific, actionable tasks
+      - Identify files and components that need changes
+      - Plan testing and validation approach
+      - Consider rollout and deployment strategy
+
+      **Output**: Create `$VIBE_DIR/specs/$BRANCH_NAME/fix-plan.md` with detailed approach for implementing the bug fix.
+
+    transitions:
+      - trigger: 'plan_complete'
+        to: 'fix'
+        transition_reason: 'Fix plan completed, ready to implement the solution'
+
+      - trigger: 'architectural_conflict'
+        to: 'plan'
+        instructions: >
+          Revise the approach to address conflicts with system architecture or quality principles.
+          Ensure proper integration and maintainability of the planned fix.
+        transition_reason: 'Fix plan conflicts with architecture, needs revision'
+
+  fix:
+    description: 'Implement the minimal fix to make tests pass'
+    default_instructions: |
+      **Implement the bug fix** following the plan and making the tests pass with minimal, targeted changes.
+
+      **STEP 1: Execute Fix Strategy**
+      - Follow the fix strategy from `$VIBE_DIR/specs/$BRANCH_NAME/fix-plan.md`
+      - Make targeted changes to address the root cause
+      - Avoid over-engineering or unnecessary modifications
+      - Keep changes minimal and focused
+
+      **STEP 2: Apply Test-Driven Implementation**
+      - Run the failing tests to confirm they capture the bug
+      - Implement changes to make the tests pass (Green phase)
+      - Ensure all new tests pass while maintaining existing functionality
+
+      **STEP 3: Maintain Quality Standards**
+      - Follow existing code patterns and conventions
+      - Maintain or improve code readability
+      - Add appropriate error handling
+      - Include necessary logging or monitoring
+
+      **STEP 4: Validate Implementation**
+      - Verify the original reproduction case no longer occurs
+      - Run full test suite to check for regressions
+      - Test edge cases and boundary conditions
+      - Validate fix meets success criteria from specification
+
+      **STEP 5: Track Progress**
+      - Document any deviations from the original plan
+      - Note any additional issues discovered during implementation
+      - Update tests if new edge cases are found
+
+    transitions:
+      - trigger: 'fix_implemented'
+        to: 'verify'
+        transition_reason: 'Bug fix implemented and tests passing, ready for verification'
+
+      - trigger: 'fix_blocked'
+        to: 'plan'
+        instructions: >
+          Return to planning to revise the approach or break down the problem further.
+          Fix implementation is blocked by technical issues or complexity that need to be resolved.
+        transition_reason: 'Fix implementation blocked, need to revise plan'
+
+      - trigger: 'tests_failing'
+        to: 'test'
+        instructions: >
+          Review and update the test suite to better capture the requirements.
+          Tests are failing in unexpected ways, indicating the test design may need revision.
+        transition_reason: 'Tests failing unexpectedly, need to revise test approach'
+
+  verify:
+    description: 'Verify the fix works and does not introduce regressions'
+    default_instructions: |
+      **Verify the bug fix** works correctly and doesn't introduce any regressions or new issues.
+
+      **STEP 1: Verify Bug Resolution**
+      - Confirm the original reproduction case no longer occurs
+      - Verify all scenarios from `$VIBE_DIR/specs/$BRANCH_NAME/bug-spec.md` work correctly
+      - Test the fix in the original environment where the bug was reported
+      - Validate that success criteria are met
+
+      **STEP 2: Perform Regression Testing**
+      - Run full test suite to ensure no existing functionality is broken
+      - Test related features and integration points
+      - Verify performance hasn't degraded
+      - Check that the fix doesn't introduce new edge case failures
+
+      **STEP 3: Validate User Acceptance**
+      - Test from user perspective using real scenarios
+      - Verify the fix addresses the original user problem
+      - Ensure user experience is improved, not just technically correct
+      - Consider having original bug reporter validate the fix
+
+      **STEP 4: Update Documentation**
+      - Update relevant documentation if behavior has changed
+      - Document the fix approach for future reference
+      - Prepare release notes or change log entries
+      - Consider if this fix reveals systemic issues to address
+
+      **Final Validation Checklist**:
+      - All tests pass (both new and existing)
+      - Original bug reproduction case fails (bug is fixed)
+      - No regressions detected
+      - User scenarios work as specified
+
+    transitions:
+      - trigger: 'regression_detected'
+        to: 'fix'
+        instructions: >
+          Return to implementation to address the problems.
+          The fix has introduced new issues or broken existing functionality.
+        transition_reason: 'Regression detected, need to revise fix implementation'
+
+      - trigger: 'fix_insufficient'
+        to: 'specify'
+        instructions: >
+          Return to specification to better define the requirements.
+          The fix doesn't fully address the original problem or reveals incomplete specification.
+        transition_reason: 'Fix insufficient, need to revise specification'
+
+# Global transitions available from any state
+global_transitions:
+  - trigger: 'abandon_bugfix'
+    to: 'reproduce'
+    instructions: >
+      If you want to restart, you'll begin again with reproducing and understanding the bug.
+    transition_reason: 'Bug fix abandoned, restart from beginning'