agentleFS
alex-voloshin-devalex-voloshin-dev/ai-skills/.agents/skills/bugfix/SKILL.md

bugfix

Skill2 starsChanged 6 months agoMITView on GitHub

End-to-end bugfix workflow — analyze environment (local Docker or cloud production), collect evidence, prepare bug report, plan fix, apply appropriate engineer role, implement and verify the fix.

35 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use feature, refactor and 6 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • bradtraversySkill

    feature

    Manage current feature workflow - start, review, explain or complete

    Also in 7 projects that use this

  • GitHubSkill

    refactor

    Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements.

    Also in 6 projects that use this

  • SentrySkill

    spec

    Produce a verified spec — problem, desired outcome, and acceptance criteria — before building. Use when given a GitHub/Linear issue link, when starting from a fuzzy in-conversation idea, or asked to "figure out what to do" / "scope this" / "what should I build" — whenever the *what* isn't yet pinned down. Grills the ambiguities, checks the premise against the code, and produces acceptance criteria you sign off on — then hands to design-first.

    Also in 4 projects that use this

  • SentrySkill

    commit

    Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history. Follows conventional commits with Sentry-specific issue references.

    Also in 8 projects that use this

  • MicrosoftSkill

    pr-review

    Verify the technical accuracy of a vscode-docs pull request against the VS Code source code in microsoft/vscode. Use when reviewing a docs PR for factual correctness: setting names, command IDs, default values, API shapes, keybindings, versioned availability, and described behavior.

    Also in 3 projects that use this

  • Hugging FaceSkill

    implement

    Make tests pass. Invoke after /write-tests produces failing tests.

    Also in 3 projects that use this

  • +1 more from getsentry

The file

Show its rules and text

We split this skill into the rules it gives an agent

28 rules. 0 are common, 24 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 32 edited versions we read keep these.

  • 24

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If the user provides partial information, extract what you can and fill gaps during analysis.

    line 31
  2. Distinctive:

    Run the follow-up skill. It will:

    line 43
  3. Distinctive:

    Timeline: When did it start? What changed?

    line 84
  4. Distinctive:

    Use the applied role's debugging methodology to trace the bug:

    line 90
  5. Distinctive:

    Read error stack traces to identify the failing code path

    line 91
  6. Distinctive:

    Search codebase for related functions, error handlers, and data flows

    line 92
  7. Distinctive:

    Check recent changes (git log -n 20 --oneline) for potential regressions

    line 93
  8. Distinctive:

    Wait for user confirmation before proceeding to fix.

    line 138
  9. Distinctive:

    Create an ordered fix plan following the applied role's guidelines:

    line 142
  10. Distinctive:

    Wait for user approval before implementing.

    line 171
  11. Distinctive:

    Verify the code compiles/parses without errors

    line 180
  12. Distinctive:

    Run the full test suite to catch regressions

    line 185
  13. Distinctive:

    Follow existing code patterns and conventions

    line 191
  14. Distinctive:

    No new warnings or linter errors — and fix pre-existing ones in the affected files if trivial

    line 192
  15. Distinctive:

    Do not defer fixes to "follow-up" tasks — complete the fix in this changeset

    line 193
  16. Distinctive:

    Do not increase tech debt — if you touch it, leave it better than you found it

    line 194
  17. Distinctive:

    If the fix is more complex than expected — stop and discuss with the user

    line 195
  18. Very specific:

    If you need more information about the environment, run specialized follow-up skills (analyze-local skill or analyze-prod skill) to collect …

    line 196
  19. Distinctive:

    Before declaring the bug fixed, perform a thorough self-review.

    line 200
  20. Distinctive:

    If the self-review reveals any remaining issues — fix them before proceeding.

    line 211
  21. Distinctive:

    Verify the bug is resolved in the appropriate environment:

    line 215
  22. Distinctive:

    Run the reproduction steps — confirm the bug no longer occurs

    line 218
  23. Distinctive:

    Run the full test suite — all tests pass (new + existing)

    line 219
  24. Very specific:

    If Docker-based: rebuild and verify with analyze-local skill (optional)

    line 220
  25. Very specific:

    If you need more data, run specialized follow-up skills for analyze-local skill to collect environment state

    line 221
  26. Distinctive:

    Verify the fix locally first

    line 224
  27. Very specific:

    After deploy: re-run relevant checks from analyze-prod skill to confirm resolution

    line 226
  28. Distinctive:

    If any check fails — fix and re-verify.

    line 239

“Common” is measured: kept by at least 6 in 10 of the 32 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Bugfix

End-to-end workflow for investigating, diagnosing, and fixing bugs. Orchestrates environment analysis (analyze-local skill or analyze-prod skill), evidence collection, bug report preparation, fix planning, and implementation by the appropriate engineering role.

1. Receive Bug Report

Gather the bug description from the user:

  • What is the expected behavior?
  • What is the actual behavior? (error message, wrong output, crash, performance issue)
  • Steps to reproduce (if known)
  • Environment: local (Docker) or production (cloud K8s)?
  • When did it start? (after deploy, config change, or unknown)
  • Severity: P1 (outage), P2 (degraded), P3 (minor), P4 (cosmetic)

If the user provides partial information, extract what you can and fill gaps during analysis. For P1/P2 — skip detailed intake and proceed immediately to Step 2.

2. Analyze Environment

Based on the environment, delegate to the appropriate analysis follow-up skill:

Environmentfollow-up skillWhen to use
Local Docker / Docker Composeanalyze-local skillBug observed in local dev environment
Cloud production (GKE/AKS/EKS, managed DB)analyze-prod skillBug observed in production or staging
Code-only (no infra)Skip to Step 3Bug is in application logic, no environment analysis needed

Run the follow-up skill. It will:

  • Apply the appropriate diagnostic role (sre-engineer role or devops-engineer role)
  • Collect environment snapshot (container/pod status, logs, metrics, networking)
  • Identify infrastructure-level issues
  • Present diagnosis

If the follow-up skill resolves the issue (e.g., container restart, config fix) — skip to Step 8.

If the root cause is in application code — continue to Step 3 with the collected evidence.

3. Detect Stack and Apply Engineer Role

Determine the affected service's tech stack and apply the appropriate engineering role:

  1. Read project's AGENTS.md — tech stack declaration
  2. Scan project files — package.json, pom.xml, requirements.txt, go.mod, etc.
  3. Check evidence from Step 2 — which service's logs show the error? What language is the stack trace in?

Role assignment:

Stack SignalRole
Next.js, React, TypeScript, .tsx filesfrontend-engineer role
Spring Boot, Java, .java filesjava-engineer role
FastAPI, Python, .py filespython-engineer role
Terraform, Dockerfile, Helm, CI/CDdevops-engineer role
ML model, training pipeline, inferenceml-engineer role
Multiple stacks affectedApply all relevant roles
Unknown / generalsoftware-engineer role

Announce the applied role(s) to the user.

4. Collect Evidence

Gather all evidence into a structured collection. Combine data from Step 2 (environment analysis) with code-level investigation:

<evidence_checklist>

  • Error output: Full error message, stack trace, exit code
  • Logs: Relevant log entries (timestamped) from the affected service
  • Reproduction: Can you reproduce locally? Consistent or intermittent?
  • Scope: Which endpoints / features / components are affected?
  • Timeline: When did it start? What changed? (recent commits, deploys, config)
  • Data: Specific inputs that trigger the bug (request payload, user ID, dataset)
  • Metrics (if from prod): Error rate, latency change, affected user count
  • Related code: Files, functions, lines most likely involved </evidence_checklist>

Use the applied role's debugging methodology to trace the bug:

  • Read error stack traces to identify the failing code path
  • Search codebase for related functions, error handlers, and data flows
  • Check recent changes (git log -n 20 --oneline) for potential regressions
  • Identify the minimal reproduction case

5. Prepare Bug Report

Compile findings into a structured bug report. Present to the user for review:

## Bug Report

### Summary
[One sentence: what is broken]

### Severity: [P1 | P2 | P3 | P4]

### Environment
- **Type**: [local | production]
- **Service**: [name]
- **Stack**: [detected] | **Role**: [applied]

### Expected Behavior
[What should happen]

### Actual Behavior
[What actually happens — include error messages]

### Steps to Reproduce
1. [step]
2. [step]
3. [observed error]

### Evidence
- **Stack trace**: [snippet or reference]
- **Logs**: [relevant entries]
- **Metrics**: [if applicable]
- **Affected code**: [file:line references]

### Root Cause Analysis
[Technical explanation of why the bug occurs]

### Affected Components
- [file/module 1] — [how it's affected]
- [file/module 2] — [how it's affected]

Wait for user confirmation before proceeding to fix.

6. Plan the Fix

Create an ordered fix plan following the applied role's guidelines:

  1. Root cause fix — address the actual cause, not symptoms
  2. Complete fix — fix everything described in the bug report. Do not leave cosmetic issues, lint warnings, or minor problems unfixed. Do not create follow-up tickets for things you can fix now
  3. Regression test — test that would have caught this bug
  4. Related fixes — any adjacent issues discovered during investigation. Fix them in the same changeset — do not increase tech debt

Present the plan:

## Fix Plan

### Root Cause
[What caused the bug — one sentence]

### Changes
1. [file] — [what to change and why]
2. [file] — [what to change and why]
...

### Tests
1. [test file] — [test that reproduces and verifies the fix]
2. [test file] — [regression test for edge cases]

### Risk Assessment
- **Blast radius**: [which features could be affected by this change]
- **Rollback**: [how to revert if the fix causes issues]

Wait for user approval before implementing.

7. Implement the Fix

Execute the approved plan step by step.

For each change:

  1. State what you are about to do (file, change summary)
  2. Implement the fix following the applied role's code quality standards
  3. Verify the code compiles/parses without errors

Then write tests:

  1. Regression test: Reproduces the original bug — must fail without fix, pass with fix
  2. Edge case tests: Cover related scenarios discovered during investigation
  3. Run the full test suite to catch regressions

Rules:

  • Fix the root cause, not the symptom
  • Fix EVERYTHING reported in the bug — do not leave non-blocking or cosmetic issues unfixed
  • Fix all lint errors, style violations, and warnings introduced or exposed by the change
  • Follow existing code patterns and conventions
  • No new warnings or linter errors — and fix pre-existing ones in the affected files if trivial
  • Do not defer fixes to "follow-up" tasks — complete the fix in this changeset
  • Do not increase tech debt — if you touch it, leave it better than you found it
  • If the fix is more complex than expected — stop and discuss with the user
  • If you need more information about the environment, run specialized follow-up skills (analyze-local skill or analyze-prod skill) to collect it

8. Self-Review the Fix

Before declaring the bug fixed, perform a thorough self-review. Do NOT skip this step.

Code review checklist:

  • Re-read every changed file diff — verify correctness and completeness
  • Every item from the bug report or user description is addressed — nothing left unfixed
  • No cosmetic issues, lint warnings, or style violations remain in changed files
  • No TODO, FIXME, or "will fix later" comments introduced
  • No tech debt created — the code is clean and production-ready
  • Run linter on all changed files — zero warnings
  • Run formatter on all changed files — zero diffs

If the self-review reveals any remaining issues — fix them before proceeding. Do not declare the bug fixed with known remaining problems.

9. Verify the Fix

Verify the bug is resolved in the appropriate environment:

For local bugs:

  • Run the reproduction steps — confirm the bug no longer occurs
  • Run the full test suite — all tests pass (new + existing)
  • If Docker-based: rebuild and verify with analyze-local skill (optional)
  • If you need more data, run specialized follow-up skills for analyze-local skill to collect environment state

For production bugs:

  • Verify the fix locally first
  • Deploy through normal CI/CD pipeline (do NOT hotfix production directly)
  • After deploy: re-run relevant checks from analyze-prod skill to confirm resolution
  • Monitor error rates and SLIs for regression

Verification checklist:

  • Original bug no longer reproduces
  • ALL items from the bug report are fixed — not just the primary symptom
  • Regression test passes
  • Full test suite passes (no new failures)
  • Linter passes with zero warnings on changed files
  • No unrelated files modified
  • Code follows project conventions and role guidelines
  • No deferred work — everything is done in this changeset

If any check fails — fix and re-verify. Do NOT declare the bug fixed until every checkbox passes.

10. Summary

Present the completed bugfix:

  • Bug: one-sentence summary
  • Severity: P1–P4
  • Environment: local / production
  • Role(s) applied: which roles were used
  • Root cause: technical explanation
  • Fix: what was changed (files, brief description)
  • Tests added: count and description
  • Self-review: passed — all items verified
  • Verification: how it was confirmed fixed
  • Remaining issues: NONE (if any remain, go back and fix them before reporting)
  • Prevention: recommendations to avoid similar bugs (e.g., add validation, improve error handling, add monitoring)

Integration

  • follow-up skills: analyze-local skill, analyze-prod skill (environment diagnostics — launch as specialized skills when more data is needed)
  • Follow-up: run-tests skill (verify fix), pre-commit skill (quality gate), create-pr skill (submit fix)
  • Skills: code-review skill (review fix), test-strategy skill (test strategy), worktree-isolation skill (branch isolation)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.