Skip to content
Agentic Coding Toolkit

Bugfix Workflow

Diagnose, fix, and verify a bug using a structured spec-first approach. The key: write a failing test before touching any production code.

Scenario

Section titled “Scenario”

You have a reported bug — a crash, wrong behavior, or visual glitch — and need to fix it reliably. You want to understand the root cause, write a test that catches the bug, fix it, and confirm the fix prevents regression.

Prerequisites

Section titled “Prerequisites”
  • ACT installed and configured in your project (Project Setup)
  • An existing Flutter app where the bug occurs
  • A Claude Code or OpenCode session open in your project directory
  • A description of the bug: what happens, what should happen, and how to reproduce it

Steps

Section titled “Steps”

1. Write a bugfix spec

Section titled “1. Write a bugfix spec”

Use the spec command with a detailed bug description. Include reproduction steps, expected behavior, and actual behavior:

Terminal window
/act:workflow:spec "fix: tapping the 'Save' button on the edit expense screen does nothing when the amount field contains a decimal value like '12.50'. Expected: expense is saved and user returns to the list. Actual: button tap is ignored, no error shown. Happens on both iOS and Android."

ACT will analyze the relevant code paths, ask targeted questions about the bug context, and generate a spec that documents:

  • The root cause hypothesis
  • Affected code paths
  • Validation criteria (how to confirm the fix works)
  • Edge cases to test

See Spec for spec structure details.

2. Create the plan

Section titled “2. Create the plan”

Generate a plan focused on diagnosis, test, and fix:

Terminal window
/act:workflow:plan ai_specs/fix-save-button-spec.md

A good bugfix plan typically has this shape:

  • Phase 1: Write a failing test that reproduces the bug
  • Phase 2: Fix the root cause with minimal changes
  • Phase 3: Add edge case tests and verify no regressions

Review the plan to confirm it starts with a test, not with the fix. The test proves the bug exists and later proves the fix works.

3. Execute the plan

Section titled “3. Execute the plan”

Run the fix:

Terminal window
/act:workflow:work ai_specs/fix-save-button-plan.md

ACT will write the failing test first, then implement the fix, then verify all tests pass. Each step is committed separately so you can see the progression in your git history.

4. Verify manually

Section titled “4. Verify manually”

After ACT finishes, run the app and reproduce the original bug scenario. Confirm:

  • The reported behavior is fixed
  • Related functionality still works
  • The test suite passes with flutter test

5. Push the fix

Section titled “5. Push the fix”
Terminal window
/act:git:push-make-pr

The PR will include the spec context, making it easy for reviewers to understand what was broken and why the fix is correct.

Expected output

Section titled “Expected output”

After completing these steps, you should have:

  • A spec documenting the bug, root cause, and fix criteria
  • At least one test that would have caught the bug
  • A minimal code change that fixes the root cause
  • All existing tests still passing
  • A pull request linking the bug description to the fix

Common pitfalls

Section titled “Common pitfalls”
  • Fixing without a test. If you skip the test, you have no proof the bug is actually fixed and no protection against regression. Always start with a failing test.
  • Vague bug description. “The app crashes sometimes” is not enough. Include reproduction steps, device/OS, and the exact error message or behavior. The better the input, the faster ACT finds the root cause.
  • Fixing symptoms instead of causes. If the spec suggests wrapping code in a try-catch without addressing why the error occurs, push back. Ask ACT to dig deeper into the root cause.
  • Scope creep. A bugfix spec should fix one bug. If you notice other issues during the fix, create separate specs for them.

Next steps

Section titled “Next steps”