# ═══════════════════════════════════════════════════════════
# SKILL META - Task-Based: Bug Fix
# ═══════════════════════════════════════════════════════════

# ─────────────────────────────────────────────────────────────
# IDENTITY
# ─────────────────────────────────────────────────────────────
skill_name: x-ipe-task-based-bug-fix
skill_type: x-ipe-task-based
version: "1.3.0"
status: candidate
created: 2026-02-24
updated: 2026-03-02

# ─────────────────────────────────────────────────────────────
# PURPOSE
# ─────────────────────────────────────────────────────────────
summary: |
  Systematically diagnose, fix, and verify bug resolutions with early conflict pre-check,
  fix scope covering code and documentation gaps, and optional doc updates before testing.

triggers:
  - "fix bug"
  - "something is broken"
  - "not working"

not_for:
  - "x-ipe-task-based-code-refactor: When restructuring code without fixing a bug"
  - "x-ipe-task-based-change-request: When modifying behavior intentionally"

# ─────────────────────────────────────────────────────────────
# CHANGE DESCRIPTION (v1.2.0 → v1.3.0)
# ─────────────────────────────────────────────────────────────
change_description: |
  Generalize `logic_conflict_reaction` into `human_approval` parameter.
  - Renamed input: logic_conflict_reaction → human_approval (set via --human-approval)
  - Same values: "notify" (default) and "approval_required"
  - Now controls ALL human approval gates across steps, not just conflict analysis:
    - Step 3 (Conflict Analysis): when conflicts are found
    - Step 6 (Design Fix): when fix changes key components or interfaces
  - Any step needing a human decision checks human_approval to decide
    whether to notify-and-proceed or stop-for-confirmation.

# ─────────────────────────────────────────────────────────────
# WORKFLOW POSITION
# ─────────────────────────────────────────────────────────────
workflow:
  category: standalone
  phase: null
  next_task_based_skill: null
  human_review: true

# ─────────────────────────────────────────────────────────────
# INTERFACE
# ─────────────────────────────────────────────────────────────
inputs:
  required:
    - name: auto_proceed
      type: boolean
      default: false
      description: Whether to auto-proceed to next task

    - name: bug_description
      type: string
      description: Description of the bug

    - name: expected_behavior
      type: string
      description: What should happen

    - name: actual_behavior
      type: string
      description: What actually happens

  optional:
    - name: human_approval
      type: string
      default: "notify"
      description: "How to handle logic conflicts: 'notify' (log in summary, proceed) or 'approval_required' (stop for human approval). Set via --human-approval"
      validation: "must be 'notify' or 'approval_required'"

    - name: reproduction_steps
      type: string
      default: null
      description: Steps to reproduce the bug

    - name: environment_info
      type: string
      default: null
      description: Environment details if relevant

    - name: program_type
      type: string
      default: null
      description: "frontend | backend | fullstack | cli | library | skills | mcp"

    - name: tech_stack
      type: array
      default: []
      description: e.g. ["Python/Flask", "JavaScript/Vanilla"]

outputs:
  state:
    - name: category
      value: standalone
    - name: status
      value: completed | blocked
    - name: next_task_based_skill
      value: null
    - name: require_human_review
      value: yes

  artifacts:
    - name: fixed_source_file
      type: file
      path: "{path to fixed source file}"
      description: The source file with the bug fix applied

    - name: test_file
      type: file
      path: "{path to test file}"
      description: Test file with bug-reproducing test case

    - name: updated_docs
      type: file
      path: "{path to updated spec/design docs}"
      description: Updated feature spec or technical design docs (if applicable)

  data:
    - name: bug_severity
      type: string
      description: "Critical | High | Medium | Low"
    - name: root_cause
      type: string
      description: Brief description of root cause
    - name: fix_scope
      type: array
      description: "Classified list of fix items: [{type: 'code|feature-spec|technical-design', description: '...'}]"
    - name: conflicts_found
      type: array
      description: List of conflicts identified during analysis (empty if none)
    - name: docs_updated
      type: array
      description: List of doc files updated (empty if none)

# ─────────────────────────────────────────────────────────────
# ACCEPTANCE CRITERIA (MoSCoW)
# ─────────────────────────────────────────────────────────────
acceptance_criteria:
  must:
    - id: AC-S01
      category: structure
      criterion: SKILL.md exists with valid frontmatter
      test: file_exists + yaml_parse
      expected: name and description fields present

    - id: AC-S02
      category: structure
      criterion: SKILL.md body < 500 lines
      test: line_count
      expected: < 500

    - id: AC-C01
      category: content
      criterion: Execution Flow table has 10 steps
      test: table_parse
      expected: 10 rows in Execution Flow table

    - id: AC-C02
      category: content
      criterion: Step 3 is named "Conflict Analysis" (moved before Diagnose)
      test: content_check
      expected: step_3 contains "Conflict Analysis"

    - id: AC-C03
      category: content
      criterion: human_approval input parameter exists with two options
      test: content_check
      expected: Input Parameters contains human_approval with "notify" and "approval_required"

    - id: AC-C04
      category: content
      criterion: Conflict Analysis behavior branches on human_approval
      test: content_check
      expected: Step 3 has IF human_approval == "notify" and "approval_required" branches

    - id: AC-C05
      category: content
      criterion: Step 5 is named "Define Fix Scope"
      test: content_check
      expected: step_5 contains "Define Fix Scope"

    - id: AC-C06
      category: content
      criterion: Fix scope includes code AND documentation gaps
      test: content_check
      expected: Step 5 mentions "code", "feature-spec", and "technical-design" scope types

    - id: AC-C07
      category: content
      criterion: Step 7 is named "Fix Related Docs" and is optional
      test: content_check
      expected: step_7 contains "Fix Related Docs" with SKIP condition

    - id: AC-C08
      category: content
      criterion: Fix Related Docs handles feature spec and technical design separately
      test: content_check
      expected: Step 7 mentions specification.md for functional and technical-design.md for non-functional

    - id: AC-C09
      category: content
      criterion: Diagnose step (Step 4) assesses documentation gaps
      test: content_check
      expected: Step 4 mentions "missing functional requirement" and "missing non-functional requirement"

    - id: AC-C10
      category: content
      criterion: DoD includes fix scope and doc update checkpoints
      test: content_check
      expected: DoD has checkpoints for "Fix scope defined" and "Related docs updated if in scope"

    - id: AC-C11
      category: content
      criterion: Input Initialization subsection with input_init XML block
      test: section_parse
      expected: "### Input Initialization with <input_init> XML block"

    - id: AC-B01
      category: behavior
      criterion: "notify" mode records conflicts in summary and proceeds
      test: execution
      expected: When human_approval == "notify", conflicts logged but flow continues

    - id: AC-B02
      category: behavior
      criterion: "approval_required" mode stops for human approval
      test: execution
      expected: When human_approval == "approval_required" and conflicts exist, flow pauses

    - id: AC-B04
      category: behavior
      criterion: Design Fix (Step 6) also uses human_approval for key component changes
      test: content_check
      expected: Step 6 has human_approval branching when fix changes key interfaces

    - id: AC-B03
      category: behavior
      criterion: Fix scope with no doc gaps skips Step 7
      test: execution
      expected: When fix scope only contains "code" items, Step 7 is skipped

  should:
    - id: AC-S03
      category: structure
      criterion: Full-Scope Fix pattern documented in Patterns section
      test: content_check
      expected: Pattern for full-scope fix (code + docs) exists

    - id: AC-C12
      category: content
      criterion: Anti-pattern for code-only fix when docs need updating
      test: table_parse
      expected: Anti-pattern entry about "Code-only fix for doc gap"

    - id: AC-C13
      category: content
      criterion: Output Result includes fix_scope and docs_updated fields
      test: content_check
      expected: task_completion_output has fix_scope and docs_updated dynamic attributes

  could:
    - id: AC-C14
      category: content
      criterion: --human-approval CLI flag documented
      test: content_check
      expected: Reference to --human-approval flag in input or init

  wont:
    - id: AC-W01
      criterion: Automated conflict detection tooling
      reason: Agent uses code analysis, not specialized tools

# ─────────────────────────────────────────────────────────────
# TESTING
# ─────────────────────────────────────────────────────────────
test_scenarios:
  happy_path:
    - name: Bug fix with no conflicts (notify mode)
      given: Simple off-by-one bug in isolated function, human_approval = "notify"
      when: Conflict Detector analyzes expected behavior against design
      then: No conflicts found, proceeds to Diagnose

    - name: Bug fix with code-only scope
      given: Root cause is pure implementation error, no doc gaps
      when: Define Fix Scope analyzes root cause
      then: Fix scope = [code], Step 7 (Fix Related Docs) is skipped

    - name: Bug fix with doc gaps
      given: Root cause reveals missing validation requirement in spec
      when: Define Fix Scope analyzes root cause
      then: Fix scope = [code, feature-spec], Step 7 updates specification.md

  edge_cases:
    - name: Bug fix with conflicts in approval_required mode
      given: Expected behavior contradicts documented design, human_approval = "approval_required"
      when: Conflicts detected and presented to user
      then: Flow pauses until human approves, then proceeds to Diagnose

    - name: Fix scope with both feature-spec and technical-design items
      given: Root cause reveals missing functional AND non-functional requirements
      when: Define Fix Scope classifies items
      then: Step 7 updates both specification.md and technical-design.md

  error_cases:
    - name: User rejects conflict in approval_required mode
      given: Conflicts found, user says "the existing design is correct"
      when: User rejects suggested resolution
      then: Bug report re-evaluated, understanding updated, conflict analysis re-run

  blocking:
    - name: Cannot skip conflict analysis in approval_required mode
      given: Conflicts detected, human_approval = "approval_required"
      when: Attempt to proceed to Diagnose without approval
      then: BLOCKED — must get human approval first

    - name: Cannot skip doc updates when in fix scope
      given: Fix scope includes "feature-spec" items
      when: Attempt to proceed to Write Test without updating docs
      then: BLOCKED — must complete Fix Related Docs first

# ─────────────────────────────────────────────────────────────
# EVALUATION
# ─────────────────────────────────────────────────────────────
evaluation:
  self_check:
    - "Step 3 is Conflict Analysis (before Diagnose)"
    - "human_approval parameter controls conflict handling behavior"
    - "Step 5 Define Fix Scope covers code + docs"
    - "Step 7 Fix Related Docs is conditional on fix scope"
    - "Diagnose step assesses doc gaps"
    - "DoD includes fix scope and doc update checkpoints"

  judge_agent:
    - criterion: "Conflict Analysis with human_approval is clear and actionable"
      rubric: |
        5: Excellent - clear branching logic, both modes well-defined
        4: Good - minor clarity improvements needed
        3: Acceptable - some gaps in mode handling
        2: Poor - significant logic gaps
        1: Fail - modes unclear or missing key paths
    - criterion: "Fix scope and doc update flow is coherent"
      rubric: |
        5: Excellent - scope classification clear, doc update step well-integrated
        4: Good - minor improvements needed
        3: Acceptable - some gaps
        2: Poor - significant gaps
        1: Fail - scope or doc flow unclear
