Fix Bugs Systematically

Bugs are the most time-consuming interruption on any outsourcing project. A client bug report usually contains a screenshot, a vague description, and a deadline. QA regression sheets have 20 rows and no stack traces. Production incidents need a fix before the client’s morning standup. Sun Agent Kit turns every bug — from a simple typo in a validation message to a race condition in a payment worker — into a structured investigation with a traceable fix.

Overview

Goal: Identify root cause, implement a fix, and verify it without breaking adjacent behavior
Time: 5–20 minutes per bug (vs 1–4 hours manual)
Agents used: debugger, tester, reviewer
Commands: /sk:fix, /sk:fix --quick, /sk:debug, /sk:test

Prerequisites

• Sun Agent Kit installed and the project indexed (run /sk:scout at least once for complex codebases)
• Reproducible bug description — error message, steps to reproduce, or a failing test case
• Test suite in place (strongly recommended before fixing anything in production code)
• Access to logs if it’s a production issue (/sk:debug can read log files directly)

Step-by-Step Workflow

Step 1: Quick Fix for Simple, Clear-Cut Bugs

For bugs with an obvious description — validation error, wrong status code, typo in error message:

/sk:fix --quick "the POST /api/users endpoint returns 500 instead of 422 when the email field is missing from the request body"

What happens: The agent:

1. Locates the route handler and related controller for the affected endpoint
2. Diagnoses the root cause — typically missing validation, wrong status code, or unhandled path
3. Applies the minimal fix and verifies the correct behavior

Step 2: Deep Fix for Complex Bugs

For bugs that require root cause analysis across multiple files or modules:

/sk:fix "users report that after resetting their password, they're immediately logged out when they try to sign in with the new password — this is intermittent, happens about 1 in 5 times"

What happens: The agent:

1. Reads the relevant service files and traces the full password reset flow
2. Identifies the root cause — typically a race condition, missing session invalidation, or token lifecycle issue
3. Implements the fix across all affected files (service, middleware, migration)
4. Writes regression tests to prevent the bug from recurring

Step 3: Debug Production Errors from Logs

/sk:debug "production logs show: UnhandledPromiseRejection: Cannot read properties of undefined (reading 'stripe_customer_id') — this started at 14:32 UTC yesterday, affecting the checkout flow"

What happens: The agent:

1. Searches all call sites for the referenced property or variable
2. Traces the crash path from the HTTP request through to the failing line
3. Identifies the trigger — often a recent migration or deploy that changed a constraint
4. Produces a fix recommendation with the specific code changes needed

Step 4: Fix CI/CD Pipeline Failures

/sk:fix "GitHub Actions build is failing on the test step — error: ECONNREFUSED 127.0.0.1:5432 in the auth integration tests"

What happens: The agent:

1. Reads the CI configuration file and identifies the failing step
2. Diagnoses the root cause — often a timing issue, missing service dependency, or environment mismatch
3. Applies the fix directly to the CI configuration file

Step 5: Fix a UI Bug (Visual + Functional)

/sk:fix "the mobile nav menu doesn't close when a user taps outside of it on iOS Safari — it just stays open"

What happens: The agent:

1. Locates the relevant component and traces event handler logic
2. Diagnoses the root cause — often a browser-specific event handling issue
3. Applies a cross-browser compatible fix with appropriate fallback patterns

Complete Example: QA Reports 5 Bugs from Latest Testing Round

Scenario: QA sends a spreadsheet on Friday afternoon with 5 bugs from regression testing on the client’s project. Sprint review is Monday. The bugs range from trivial to a subtle race condition.

The QA bug list:

1. POST /api/orders returns HTML error page instead of JSON on invalid payload
2. Password reset emails not sent to Gmail addresses (Yahoo works fine)
3. Cart total shows wrong currency symbol for users in the EU locale
4. Order confirmation page crashes on Safari 16 with a JS error
5. Webhook from Stripe fires twice occasionally, causing duplicate order records

Friday afternoon — fix all 5:

# Bug 1: trivial validation/response format issue
/sk:fix --quick "POST /api/orders returns HTML error page instead of JSON 400 when request body is malformed"

# Bug 2: email delivery — needs investigation
/sk:fix "password reset emails not delivered to Gmail addresses — Yahoo works fine. Check SendGrid config, DKIM, and any email filtering happening in the notification service"

# Bug 3: i18n display bug
/sk:fix --quick "cart total shows wrong currency symbol for EU locale users — should be € not $ — check the currency formatting utility and locale detection"

# Bug 4: Safari JS crash
/sk:debug "order confirmation page crashes on Safari 16 with: TypeError: undefined is not an object (evaluating 'e.dataset.orderId'). Find the component and the Safari-incompatible pattern."
# Then apply the fix from the debug report:
/sk:fix --quick "apply the fix recommended in the debug report for the Safari 16 crash on the order confirmation page"

# Bug 5: idempotency — the hard one
/sk:fix "Stripe webhook fires twice causing duplicate order records. Implement idempotency key checking so the same webhook event can never create two orders"

# Run the full test suite after all fixes
/sk:test "run all tests and flag any regressions from today's fixes"

Result: All 5 bugs fixed, tests passing, and a clean commit ready for Monday’s sprint review. The idempotency fix alone (Bug 5) would have taken half a day to research and implement manually.

Time Comparison

Best Practices

1. Use —quick for bugs with clear descriptions ✅

If you can explain the bug in one sentence and know which endpoint or component is affected, --quick skips deep analysis and applies the fix directly. Save the full /sk:fix for bugs that need investigation.

2. Include reproduction steps in the fix prompt ✅

“Cart total is wrong” produces a shallow fix. “Cart total shows $ instead of € when the user’s Accept-Language header is de-DE and they have 3+ items in the cart” lets the agent pinpoint the exact failure.

3. Always run /sk:test after a batch of fixes ✅

Individual fixes are isolated, but fixing 5 bugs sequentially can introduce regressions. A full test run after the batch catches cross-cutting issues before they reach review.

4. Applying fixes without reading the diff first ❌

The agent shows you what changed. Read it. A 4-line fix that edits the wrong function can introduce a worse bug. One minute of review prevents a client escalation.

5. Asking /sk:fix to fix the symptom instead of the cause ❌

“Make the 500 go away” may result in an error being swallowed rather than handled. Describe what the correct behavior should be: “return 422 with a JSON error body when the email field is missing.”

Troubleshooting

Problem: /sk:fix —quick makes a change but the bug still reproduces

Solution: The quick mode takes the shortest path. Switch to full mode: /sk:fix "..." without --quick to run a deeper investigation and a more comprehensive fix.

Problem: /sk:debug can’t find the root cause from a log snippet

Solution: Paste the full stack trace, not just the error message. Stack traces include file names and line numbers that the debug agent uses to trace the execution path.

Problem: The fix introduces a TypeScript error

Solution: Run /sk:fix --quick "fix the TypeScript error introduced in src/services/billing.ts:89 — expected string, got string | null". The agent can resolve its own side effects.

Problem: A bug is in a third-party integration and the source code isn’t in the repo

Solution: Use /sk:ask to understand the integration boundaries, then fix the adapter layer in your code. The agent can’t modify third-party code but can correct how you call it.

Next Steps

• Add a New Feature — after clearing the bug backlog, move to feature work
• Onboard to Existing Codebase — if you inherited a project full of bugs, start with a full orientation
• Implement Authentication — many bug reports trace back to auth edge cases

Key takeaway: A QA sheet with 5 bugs should take a Friday afternoon to clear, not a full sprint — /sk:fix gives you root cause and a tested fix in minutes, not hours.