# Ralph loop (https://github.com/snarktank/ralph) — fresh context per agent session
id: bug-fix
name: Bug Triage & Fix
version: 1
description: |
  Bug fix pipeline. Triager analyzes the report and reproduces the issue.
  Investigator traces root cause. Setup creates the bugfix branch.
  Fixer implements the fix with a regression test. Verifier confirms correctness.
  PR agent creates the pull request.

agents:
  - id: triager
    name: Triager
    role: analysis
    description: Analyzes bug reports, reproduces issues, classifies severity.
    workspace:
      baseDir: agents/triager
      files:
        AGENTS.md: agents/triager/AGENTS.md
        SOUL.md: agents/triager/SOUL.md
        IDENTITY.md: agents/triager/IDENTITY.md

  - id: investigator
    name: Investigator
    role: analysis
    description: Traces bugs to root cause and proposes fix approach.
    workspace:
      baseDir: agents/investigator
      files:
        AGENTS.md: agents/investigator/AGENTS.md
        SOUL.md: agents/investigator/SOUL.md
        IDENTITY.md: agents/investigator/IDENTITY.md

  - id: setup
    name: Setup
    role: coding
    description: Creates bugfix branch and establishes baseline.
    workspace:
      baseDir: agents/setup
      files:
        AGENTS.md: ../../agents/shared/setup/AGENTS.md
        SOUL.md: ../../agents/shared/setup/SOUL.md
        IDENTITY.md: ../../agents/shared/setup/IDENTITY.md

  - id: fixer
    name: Fixer
    role: coding
    description: Implements the fix and writes regression tests.
    workspace:
      baseDir: agents/fixer
      files:
        AGENTS.md: agents/fixer/AGENTS.md
        SOUL.md: agents/fixer/SOUL.md
        IDENTITY.md: agents/fixer/IDENTITY.md

  - id: verifier
    name: Verifier
    role: verification
    description: Verifies the fix and regression test correctness.
    workspace:
      baseDir: agents/verifier
      files:
        AGENTS.md: ../../agents/shared/verifier/AGENTS.md
        SOUL.md: ../../agents/shared/verifier/SOUL.md
        IDENTITY.md: ../../agents/shared/verifier/IDENTITY.md

  - id: pr
    name: PR Creator
    role: pr
    description: Creates a pull request with bug fix details.
    workspace:
      baseDir: agents/pr
      files:
        AGENTS.md: ../../agents/shared/pr/AGENTS.md
        SOUL.md: ../../agents/shared/pr/SOUL.md
        IDENTITY.md: ../../agents/shared/pr/IDENTITY.md

steps:
  - id: triage
    agent: triager
    input: |
      Triage the following bug report. Explore the codebase, reproduce the issue, and classify severity.

      BUG REPORT:
      {{task}}

      Instructions:
      1. Read the bug report carefully
      2. Explore the codebase to find the affected area
      3. Attempt to reproduce: run tests, check for failing cases, read error logs/stack traces
      4. Classify severity (critical/high/medium/low)
      5. Document findings

      Reply with:
      STATUS: done
      REPO: /path/to/repo
      BRANCH: bugfix-branch-name
      SEVERITY: critical|high|medium|low
      AFFECTED_AREA: what files/modules are affected
      REPRODUCTION: how to reproduce the bug
      PROBLEM_STATEMENT: clear description of what's wrong
    expects: "STATUS: done"
    max_retries: 2
    on_fail:
      escalate_to: human

  - id: investigate
    agent: investigator
    input: |
      Investigate the root cause of this bug.

      BUG REPORT:
      {{task}}

      REPO: {{repo}}
      SEVERITY: {{severity}}
      AFFECTED_AREA: {{affected_area}}
      REPRODUCTION: {{reproduction}}
      PROBLEM_STATEMENT: {{problem_statement}}

      Instructions:
      1. Read the code in the affected area
      2. Trace the bug to its root cause
      3. Document exactly what's wrong and why
      4. Propose a fix approach

      Reply with:
      STATUS: done
      ROOT_CAUSE: detailed explanation of the root cause
      FIX_APPROACH: what needs to change and where
    expects: "STATUS: done"
    max_retries: 2
    on_fail:
      escalate_to: human

  - id: setup
    agent: setup
    input: |
      Prepare the environment for the bugfix.

      REPO: {{repo}}
      BRANCH: {{branch}}

      Instructions:
      1. cd into the repo
      2. Create the bugfix branch (git checkout -b {{branch}} from main)
      3. Read package.json, CI config, test config to understand build/test setup
      4. Run the build to establish a baseline
      5. Run the tests to establish a baseline

      Reply with:
      STATUS: done
      BUILD_CMD: <build command>
      TEST_CMD: <test command>
      BASELINE: <baseline status>
    expects: "STATUS: done"
    max_retries: 2
    on_fail:
      escalate_to: human

  - id: fix
    agent: fixer
    input: |
      Implement the bug fix.

      BUG REPORT:
      {{task}}

      REPO: {{repo}}
      BRANCH: {{branch}}
      BUILD_CMD: {{build_cmd}}
      TEST_CMD: {{test_cmd}}
      AFFECTED_AREA: {{affected_area}}
      ROOT_CAUSE: {{root_cause}}
      FIX_APPROACH: {{fix_approach}}
      PROBLEM_STATEMENT: {{problem_statement}}

      VERIFY FEEDBACK (if retrying):
      {{verify_feedback}}

      Instructions:
      1. cd into the repo, checkout the branch
      2. Implement the fix based on the root cause and fix approach
      3. Write a regression test that would have caught this bug
      4. Run {{build_cmd}} to verify the build passes
      5. Run {{test_cmd}} to verify all tests pass
      6. Commit: fix: brief description of the fix

      Reply with:
      STATUS: done
      CHANGES: what was changed
      REGRESSION_TEST: what test was added
    expects: "STATUS: done"
    max_retries: 2
    on_fail:
      escalate_to: human

  - id: verify
    agent: verifier
    input: |
      Verify the bug fix is correct and complete.

      BUG REPORT:
      {{task}}

      REPO: {{repo}}
      BRANCH: {{branch}}
      TEST_CMD: {{test_cmd}}
      CHANGES: {{changes}}
      REGRESSION_TEST: {{regression_test}}
      ROOT_CAUSE: {{root_cause}}
      PROBLEM_STATEMENT: {{problem_statement}}

      Instructions:
      1. Run the full test suite with {{test_cmd}}
      2. Confirm the regression test exists and tests the right thing
      3. Review the fix to confirm it addresses the root cause
      4. Check for unintended side effects
      5. Verify the regression test would fail without the fix (review the diff logic)

      Bug-fix specific checks:
      - The regression test MUST test the specific bug scenario (not just a generic test)
      - The regression test assertions must fail if the fix were reverted
      - The fix should be minimal and targeted — not a refactor disguised as a bugfix
      - Check that the fix addresses the ROOT CAUSE, not just a symptom

      Reply with:
      STATUS: done
      VERIFIED: what was confirmed

      Or if issues found:
      STATUS: retry
      ISSUES:
      - What's wrong or incomplete
    expects: "STATUS: done"
    on_fail:
      retry_step: fix
      max_retries: 3
      on_exhausted:
        escalate_to: human

  - id: pr
    agent: pr
    input: |
      Create a pull request for the bug fix.

      REPO: {{repo}}
      BRANCH: {{branch}}
      PROBLEM_STATEMENT: {{problem_statement}}
      SEVERITY: {{severity}}
      ROOT_CAUSE: {{root_cause}}
      CHANGES: {{changes}}
      REGRESSION_TEST: {{regression_test}}
      VERIFIED: {{verified}}

      PR title format: fix: brief description of what was fixed

      PR body structure:
      ```
      ## Bug Description
      {{problem_statement}}

      **Severity:** {{severity}}

      ## Root Cause
      {{root_cause}}

      ## Fix
      {{changes}}

      ## Regression Test
      {{regression_test}}

      ## Verification
      {{verified}}
      ```

      Use: gh pr create

      Reply with:
      STATUS: done
      PR: URL to the pull request
    expects: "STATUS: done"
    on_fail:
      escalate_to: human