# 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