playbooks

home / skills / first-fluke / fullstack-starter / debug-agent

debug-agent skill

/.agent/skills/debug-agent

This skill diagnoses and fixes bugs by reproducing issues, identifying root causes, applying minimal changes, and generating regression tests.

npx playbooks add skill first-fluke/fullstack-starter --skill debug-agent

Review the files below or copy the command above to add this skill to your agents.

Files (8)
SKILL.md
1.8 KB
---
name: debug-agent
description: Bug diagnosis and fixing specialist - analyzes errors, identifies root causes, provides fixes, and writes regression tests
---

# Debug Agent - Bug Fixing Specialist

## When to use
- User reports a bug with error messages
- Something is broken and needs fixing
- Performance issues or slowdowns
- Intermittent failures or race conditions
- Regression bugs

## When NOT to use
- Building new features -> use Frontend/Backend/Mobile agents
- General code review -> use QA Agent

## Core Rules
1. Reproduce first, then diagnose - never guess at fixes
2. Identify root cause, not just symptoms
3. Minimal fix: change only what's necessary
4. Every fix gets a regression test
5. Search for similar patterns elsewhere after fixing
6. Document in `.gemini/antigravity/brain/bugs/`

## How to Execute
Follow `resources/execution-protocol.md` step by step.
See `resources/examples.md` for input/output examples.
Before submitting, run `resources/checklist.md`.

## Serena MCP
- `find_symbol("functionName")`: Locate the function
- `find_referencing_symbols("Component")`: Find all usages
- `search_for_pattern("error pattern")`: Find similar issues

## Serena Memory (CLI Mode)
See `../_shared/memory-protocol.md`.

## References
- Execution steps: `resources/execution-protocol.md`
- Code examples: `resources/examples.md`
- Checklist: `resources/checklist.md`
- Error recovery: `resources/error-playbook.md`
- Bug report template: `resources/bug-report-template.md`
- Common patterns: `resources/common-patterns.md`
- Debugging checklist: `resources/debugging-checklist.md`
- Context loading: `../_shared/context-loading.md`
- Reasoning templates: `../_shared/reasoning-templates.md`
- Context budget: `../_shared/context-budget.md`
- Lessons learned: `../_shared/lessons-learned.md`

Overview

This skill is a bug diagnosis and fixing specialist for fullstack monorepos built with Next.js, FastAPI, Flutter, Terraform, and TypeScript. It reproduces reported errors, identifies root causes, applies minimal, safe fixes, and delivers regression tests to prevent recurrence. The agent also searches the codebase for similar patterns and documents each resolution for traceability.

How this skill works

The agent first reproduces the issue using logs, stack traces, and test runs, then traces the failure to a root cause by locating relevant symbols and usages. It creates the smallest possible code change to fix the defect, adds a focused regression test, and searches the repository for related occurrences to reduce future regressions. Each fix is recorded with a concise bug report and checklist verification.

When to use it

  • User reports a reproducible bug with error messages or failing tests
  • Something in production or CI is broken and needs a targeted fix
  • Intermittent failures, race conditions, or concurrency issues
  • Performance regressions or sudden slowdowns
  • A regression bug that reappeared after a recent change

Best practices

  • Always reproduce the issue locally or in an isolated CI environment before changing code
  • Prioritize root-cause analysis over symptom-based patches
  • Make minimal, well-scoped changes and keep commit messages explicit
  • Add a deterministic regression test that captures the failure case
  • Search for and fix similar patterns across the monorepo after patching
  • Document the investigation, decision, and verification steps in the project’s bug records

Example use cases

  • User reports a 500 error from FastAPI endpoint with a stack trace — reproduce, identify null handling bug, patch, add unit and integration tests
  • Intermittent Flutter UI crash on Android — reproduce on emulator, trace race condition, add synchronization and widget tests
  • Next.js server-side rendering mismatch causing hydration errors — locate offending component, apply minimal prop validation fix, add end-to-end test
  • Terraform apply failing due to resource naming collision — reproduce plan, adjust naming logic, add unit tests for naming functions and a CI check
  • Slow database query introduced after migration — reproduce with profiling, optimize query or add index, add performance regression test

FAQ

What if I cannot reproduce the bug locally?

Isolate logs and CI artifacts, create a minimal reproduction case, and use instrumented CI or staging to reproduce before fixing.

How large should the fix be?

Keep fixes as small and focused as possible; if a broader refactor is needed, split into separate PRs and include regression tests for each.

Do all fixes require tests?

Yes. Every fix must include a regression test that fails before the fix and passes after to prevent reintroduction.