workflows/workflows/bugfix at main · ambient-code/workflows

Bug Fix Workflow for Ambient Code Platform

A systematic workflow for analyzing, fixing, and verifying software bugs. Guides developers through the complete bug resolution lifecycle from reproduction to release.

Overview

This workflow provides a structured approach to fixing software bugs:

Systematic Process: Structured methodology from reproduction to PR submission
Root Cause Focus: Emphasizes understanding why bugs occur, not just what happens
Comprehensive Testing: Ensures fixes work and prevents regression
Complete Documentation: Creates all artifacts needed for release and future reference
Agent Collaboration: Leverages ACP platform agents for complex scenarios

Directory Structure

bugfix/
├── .ambient/
│   └── ambient.json          # Workflow configuration
├── .claude/
│   └── skills/               # All workflow logic lives here
│       ├── controller/SKILL.md   # Phase transitions and recommendations
│       ├── assess/SKILL.md
│       ├── reproduce/SKILL.md
│       ├── diagnose/SKILL.md
│       ├── fix/SKILL.md
│       ├── test/SKILL.md
│       ├── review/SKILL.md
│       ├── document/SKILL.md
│       ├── pr/SKILL.md
│       └── speedrun/SKILL.md    # Runs all remaining phases in sequence
├── CLAUDE.md                 # Behavioral guidelines
└── README.md                 # This file

How Skills Work

Each phase is implemented as a skill in .claude/skills/{name}/SKILL.md. When you run /assess, /fix, etc., the corresponding skill is invoked directly. Each phase skill checks whether it was dispatched by the controller or speedrun; if invoked standalone, it reads the controller first to ensure proper workflow context.

The controller skill manages phase transitions and recommends next steps. The speedrun skill bypasses the controller and runs all remaining phases in sequence without stopping.

Workflow Phases

The Bug Fix Workflow follows this approach:

Phase 1: Assess (`/assess`)

Purpose: Understand the bug report and propose a plan before taking action.

Read the bug report, issue URL, or symptom description
Clone the repository if not already available (read-only, no code executed)
Summarize understanding of the bug, its location, and severity
Identify what information is available and what is missing
Propose a reproduction plan
Let the user correct misunderstandings before work begins

Output: artifacts/bugfix/reports/assessment.md

When to use: Start here to build a shared understanding before investing effort. This is the default first phase when you provide a bug report.

Phase 2: Reproduce (`/reproduce`)

Purpose: Systematically reproduce the bug and document observable behavior.

Parse bug reports and extract key information
Set up environment matching bug conditions
Attempt reproduction with variations to understand boundaries
Document minimal reproduction steps
Create reproduction report with severity assessment

Output: artifacts/bugfix/reports/reproduction.md

When to use: Start here if you have a bug report, issue URL, or symptom description.

Phase 3: Diagnose (`/diagnose`)

Purpose: Perform root cause analysis and assess impact.

Review reproduction report and understand failure conditions
Analyze code paths and trace execution flow
Examine git history and recent changes
Form and test hypotheses about root cause
Assess impact across the codebase
Recommend fix approach

Output: artifacts/bugfix/analysis/root-cause.md

When to use: After successful reproduction, or skip here if you know the symptoms.

Phase 4: Fix (`/fix`)

Purpose: Implement the bug fix following best practices.

Review fix strategy from diagnosis phase
Create feature branch (bugfix/issue-{number}-{description})
Implement minimal code changes to fix the bug
Address similar patterns identified in analysis
Run linters and formatters
Document implementation choices

Output: Modified code files + artifacts/bugfix/fixes/implementation-notes.md

When to use: After diagnosis phase, or jump here if you already know the root cause.

Phase 5: Test (`/test`)

Purpose: Verify the fix and create regression tests.

Create regression test that fails without fix, passes with fix
Write comprehensive unit tests for modified code
Run integration tests in realistic scenarios
Execute full test suite to catch side effects
Perform manual verification of original reproduction steps
Check for performance or security impacts

Output: New test files + artifacts/bugfix/tests/verification.md

When to use: After implementing the fix.

Phase 6: Review (`/review`) — Optional

Purpose: Critically evaluate the fix and its tests before proceeding.

Re-read all evidence (reproduction report, root cause analysis, code changes, test results)
Critique the fix: Does it address the root cause or just suppress the symptom?
Critique the tests: Do they prove the bug is fixed, or do mocks hide real problems?
Classify into a verdict and recommend next steps

Verdicts:

Fix is inadequate → Recommend going back to /fix with specific guidance
Fix is adequate, tests are incomplete → Provide instructions for what additional testing is needed (including manual steps for the user)
Fix and tests are solid → Recommend proceeding to /document and /pr

Output: artifacts/bugfix/review/verdict.md

When to use: After /test, especially for complex or high-risk fixes.

Phase 7: Document (`/document`)

Purpose: Create complete documentation for the fix.

Update issue/ticket with root cause and fix summary
Create release notes entry
Write CHANGELOG addition
Update code comments with issue references
Draft PR description

Output: artifacts/bugfix/docs/ containing issue updates, release notes, changelog entries, and PR description.

When to use: After testing is complete.

Phase 8: PR (`/pr`)

Purpose: Create a pull request to submit the bug fix.

Run pre-flight checks (authentication, remotes, git config)
Ensure a fork exists and is configured as a remote
Create a branch, stage changes, and commit with conventional format
Push to fork and create a draft PR targeting upstream
Handle common failures (no push access, no fork permission) with clear fallbacks

Output: A draft pull request URL (or manual creation instructions if automation fails).

When to use: After all prior phases are complete, or whenever you're ready to submit.

Getting Started

Quick Start

Create an AgenticSession in the Ambient Code Platform
Select "Bug Fix Workflow" from the workflows dropdown
Provide context: Bug report URL, issue number, or symptom description
Start with /assess to analyze the bug report and build a plan
Follow the phases sequentially or jump to any phase based on your context

Example Usage

Scenario 1: You have a bug report

User: "Fix bug https://github.com/org/repo/issues/425 - session status updates failing"

Workflow: Starts with /reproduce to confirm the bug
→ /diagnose to find root cause
→ /fix to implement solution
→ /test to verify fix
→ /document to create release notes
→ /pr to submit the fix

Scenario 2: You know the symptoms

User: "Sessions are failing to update status in the operator"

Workflow: Jumps to /diagnose for root cause analysis
→ /fix to implement
→ /test to verify
→ /document
→ /pr

Scenario 3: You already know the fix

User: "Missing retry logic in UpdateStatus call at operator/handlers/sessions.go:334"

Workflow: Jumps to /fix to implement
→ /test to verify
→ /document
→ /pr

Prerequisites

Access to the codebase where the bug exists
Ability to run and test code locally or in an appropriate environment
Git access for creating branches and reviewing history

Agent Orchestration

This workflow is orchestrated by Amber, who serves as your single point of contact. Rather than manually selecting agents, Amber automatically coordinates the right specialists from the ACP platform based on the complexity and nature of the task.

Specialists Amber may engage:

Stella (Staff Engineer) — Complex debugging, root cause analysis, architectural issues
Neil (Test Engineer) — Comprehensive test strategies, integration testing, automation
Taylor (Team Member) — Straightforward implementations, documentation
secure-software-braintrust — Security vulnerability assessment
sre-reliability-engineer — Performance and reliability issues
frontend-performance-debugger — Frontend-specific performance bugs
And any other platform agents as the situation warrants

You interact with Amber. Amber assesses each phase and brings in the right expertise automatically.

Artifacts Generated

All workflow artifacts are organized in the artifacts/bugfix/ directory:

artifacts/bugfix/
├── reports/                  # Bug reproduction reports
│   └── reproduction.md
├── analysis/                 # Root cause analysis
│   └── root-cause.md
├── fixes/                    # Implementation notes
│   └── implementation-notes.md
├── tests/                    # Test results and verification
│   └── verification.md
├── docs/                     # Documentation and release notes
│   ├── issue-update.md
│   ├── release-notes.md
│   ├── changelog-entry.md
│   └── pr-description.md
└── logs/                     # Execution logs
    └── *.log

Best Practices

Reproduction

Take time to reproduce reliably — flaky reproduction leads to incomplete diagnosis
Document even failed attempts — inability to reproduce is valuable information
Create minimal reproduction steps that others can follow

Diagnosis

Understand the why, not just the what
Document your reasoning process for future developers
Use file:line notation when referencing code (e.g., handlers.go:245)
Consider similar patterns elsewhere in the codebase

Implementation

Keep fixes minimal — only change what's necessary
Don't combine refactoring with bug fixes
Reference issue numbers in code comments
Consider backward compatibility

Testing

Regression tests are mandatory — every fix must include a test
Test the test — verify it fails without the fix
Run the full test suite, not just new tests
Manual verification matters

Documentation

Be clear and specific for future developers
Link issues, PRs, and commits for easy navigation
Consider your audience (technical vs. user-facing)
Don't skip this step — documentation is as important as code

Behavioral Guidelines

The CLAUDE.md file defines engineering discipline, safety, and quality standards for bug fix sessions. Key points:

Confidence levels: Every action is tagged High/Medium/Low confidence
Safety guardrails: No direct commits to main, no force-push, no secret logging
Escalation criteria: When to stop and request human guidance
Project respect: The workflow adapts to the target project's conventions

See CLAUDE.md for full details.

Customization

You can customize this workflow by:

Adding project-specific linting commands in the Fix skill
Customizing test commands in the Test skill for your stack
Extending phases with additional steps for your workflow
Modifying artifact paths to match your project structure

Environment-Specific Adjustments

Microservices: Add service dependency analysis to Diagnose
Frontend: Include browser testing in Test
Backend: Add database migration checks to Fix
Infrastructure: Include deployment validation in Test

Troubleshooting

"I can't reproduce the bug"

Document what you tried and what was different
Check environment differences (versions, config, data)
Ask the reporter for more details
Consider it may be fixed or non-reproducible

"Multiple potential root causes"

Document all hypotheses in /diagnose
Test each systematically
May need multiple fixes if multiple issues

"Tests are failing after fix"

Check if tests were wrong or your fix broke something
Review test assumptions
Consider if behavior change was intentional

"Fix is too complex"

Amber will engage Stella for complex scenarios
Consider breaking into smaller fixes
May indicate an underlying architectural issue