@qball-inc/the-bulwark 1.0.0

package/skills/issue-debugging/references/debug-report-schema.md

@@ -0,0 +1,227 @@
+# Debug Report Schema
+
+Full YAML schema for debug reports generated by the issue-debugging methodology.
+
+## Location
+
+```
+logs/debug-reports/{issue-id}-{timestamp}.yaml
+```
+
+## Complete Schema
+
+```yaml
+debug_report:
+  # ============================================
+  # METADATA
+  # ============================================
+  metadata:
+    issue_id: "{identifier}"           # Required: Unique issue identifier
+    timestamp: "{ISO-8601}"            # Required: When analysis completed
+    analyzer: "bulwark-issue-analyzer" # Required: Agent that produced this
+    complexity: low | medium | high    # Required: Determined during analysis
+
+  # ============================================
+  # ANALYSIS
+  # ============================================
+  analysis:
+    symptom: "{user-visible problem}"
+    # Example: "Login button returns 500 error"
+
+    root_cause: "{underlying reason - NOT just symptom}"
+    # Example: "Null profile object accessed when user has no profile data"
+    # BAD: "API returns 500" (that's the symptom)
+
+    fix_approach: "{recommended approach}"
+    # Example: "Add null check before accessing profile.name"
+
+    five_whys:  # Optional but recommended
+      - "{first why}"
+      - "{second why}"
+      - "{third why}"
+      - "{fourth why}"
+      - "{fifth why - root cause}"
+
+  # ============================================
+  # IMPACT ANALYSIS
+  # ============================================
+  impact_analysis:
+    affected_files:
+      - path: "{file path}"
+        changes: "{what needs to change}"
+      # Example:
+      # - path: "src/auth/login.ts"
+      #   changes: "Add null check at line 42"
+
+    upstream_dependencies:
+      - caller: "{what calls this code}"
+        file: "{file path}"
+        impact: "{how it's affected}"
+      # Example:
+      # - caller: "POST /api/login"
+      #   file: "src/api/auth-routes.ts"
+      #   impact: "Will receive null instead of crashing"
+
+    downstream_effects:
+      - consumer: "{what this code affects}"
+        file: "{file path}"
+        impact: "{potential impact}"
+      # Example:
+      # - consumer: "User dashboard"
+      #   file: "src/pages/dashboard.tsx"
+      #   impact: "Must handle empty profile gracefully"
+
+    risk_scope: isolated | medium | broad
+    # isolated: Self-contained, no affected areas
+    # medium: 1-5 affected areas
+    # broad: >5 affected areas, cross-cutting
+
+  # ============================================
+  # VALIDATION PLAN
+  # ============================================
+  validation_plan:
+    tests_to_execute:
+      - path: "{test file}"
+        test_name: "{specific test or describe block}"  # Optional
+        reason: "{why this test matters}"
+        priority: 1  # 1=P1 must, 2=P2 should, 3=P3 nice-to-have
+      # Example:
+      # - path: "tests/auth/login.test.ts"
+      #   test_name: "handles null profile"
+      #   reason: "Direct test of the fix"
+      #   priority: 1
+
+    functionalities_to_validate:
+      - functionality: "{user-level verification}"
+        how: "{validation method}"
+        automatable: true | false
+      # Example:
+      # - functionality: "User can log in successfully"
+      #   how: "E2E test or manual login"
+      #   automatable: true
+
+    test_commands:
+      p1: "{command to run P1 tests}"
+      p2: "{command to run P1+P2 tests}"
+      p3: "{command to run all tests}"
+      # Example:
+      # p1: "just test -- tests/auth/login.test.ts"
+      # p2: "just test -- tests/auth/"
+      # p3: "just test"
+
+  # ============================================
+  # CONFIDENCE CRITERIA
+  # ============================================
+  confidence_criteria:
+    high:
+      - "All P1 tests pass"
+      - "All P2 tests pass"
+      - "No regression in existing tests"
+      - "At least one functionality validated"
+    medium:
+      - "All P1 tests pass"
+      - "Some P2-P3 tests skipped or not applicable"
+      - "No critical regressions"
+    low:
+      - "Tests cannot reliably validate the fix"
+      - "Broad risk scope with untested paths"
+      - "Manual testing required"
+
+    escalation_required: true | false
+    escalation_reason: "{why manual testing needed}"  # If escalation_required
+
+  # ============================================
+  # DEBUG JOURNEY (Required for medium/high complexity)
+  # ============================================
+  debug_journey:
+    started_at: "{ISO-8601}"
+    completed_at: "{ISO-8601}"
+    duration_minutes: 0
+
+    hypotheses_tested:
+      - id: 1
+        hypothesis: "{what was suspected}"
+        tested_at: "{ISO-8601}"
+        method: "{how it was tested}"
+        result: confirmed | rejected
+        evidence: "{what proved/disproved it}"
+      # Example:
+      # - id: 1
+      #   hypothesis: "Database connection timeout"
+      #   tested_at: "2026-01-16T10:30:00Z"
+      #   method: "Checked DB logs and connection pool"
+      #   result: rejected
+      #   evidence: "DB logs show successful queries"
+
+    investigation_path:
+      - "{step 1 of investigation}"
+      - "{step 2 of investigation}"
+      # Breadcrumb trail of investigation steps
+
+    dead_ends:  # Optional: Document what didn't work
+      - approach: "{what was tried}"
+        why_abandoned: "{why it didn't work}"
+```
+
+## Minimal Valid Report (Low Complexity)
+
+For low complexity issues, only required fields:
+
+```yaml
+debug_report:
+  metadata:
+    issue_id: "fix-typo-readme"
+    timestamp: "2026-01-16T10:00:00Z"
+    analyzer: "bulwark-issue-analyzer"
+    complexity: low
+
+  analysis:
+    symptom: "Typo in README installation section"
+    root_cause: "Misspelled 'npm' as 'nmp'"
+    fix_approach: "Correct spelling"
+
+  impact_analysis:
+    affected_files:
+      - path: "README.md"
+        changes: "Fix typo"
+    upstream_dependencies: []
+    downstream_effects: []
+    risk_scope: isolated
+
+  validation_plan:
+    tests_to_execute: []
+    functionalities_to_validate:
+      - functionality: "README displays correctly"
+        how: "Visual inspection"
+        automatable: false
+    test_commands:
+      p1: "# No tests needed"
+
+  confidence_criteria:
+    high: ["Visual inspection confirms fix"]
+    escalation_required: false
+```
+
+## Field Requirements by Complexity
+
+| Field | Low | Medium | High |
+|-------|-----|--------|------|
+| metadata.* | Required | Required | Required |
+| analysis.symptom | Required | Required | Required |
+| analysis.root_cause | Required | Required | Required |
+| analysis.fix_approach | Required | Required | Required |
+| analysis.five_whys | Optional | Recommended | Required |
+| impact_analysis.* | Required | Required | Required |
+| validation_plan.* | Required | Required | Required |
+| confidence_criteria.* | Required | Required | Required |
+| debug_journey.* | Optional | **Required** | **Required** |
+
+## Validation Rules
+
+1. `issue_id` must be unique within the project
+2. `timestamp` must be valid ISO-8601
+3. `complexity` must be one of: `low`, `medium`, `high`
+4. `risk_scope` must be one of: `isolated`, `medium`, `broad`
+5. `priority` in tests must be 1, 2, or 3
+6. `debug_journey` required when complexity is medium or high
+7. `escalation_reason` required when `escalation_required` is true