Bug Investigation
Investigate and fix reported bugs. Use this skill when a bug has been reported, including root cause analysis, reproduction, and implementing fixes.
Best use case
Bug Investigation is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Investigate and fix reported bugs. Use this skill when a bug has been reported, including root cause analysis, reproduction, and implementing fixes.
Teams using Bug Investigation should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/bug-investigation/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How Bug Investigation Compares
| Feature / Agent | Bug Investigation | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Investigate and fix reported bugs. Use this skill when a bug has been reported, including root cause analysis, reproduction, and implementing fixes.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Skill: Bug Investigation ## Metadata | Field | Value | |-------|-------| | **Skill ID** | SKL-0020 | | **Version** | 1.0 | | **Owner** | fixer | | **Inputs** | Bug description, STATE.md, source files, tests/logs | | **Outputs** | Bug fix, STATE.md updated | | **Triggers** | `BUG_REPORTED` | --- ## Purpose Systematically isolate and fix bugs. Hypothesis first, evidence second, fix third. Never guess — find the root cause, not just the symptom. --- ## Procedure 1. **Reproduce the bug** before touching any code. - Can it be reproduced consistently? What are the exact steps? - If not reproducible: log as intermittent and request more info. 2. **Form a hypothesis** about the root cause: - Check STATE.md for recent changes that may have introduced it - State explicitly: "I believe the bug is caused by X because Y." 3. **Gather evidence** to confirm or reject: - Read relevant code carefully - Trace execution path from input to failure - Check: off-by-one errors, null handling, async timing, data shape assumptions 4. **Confirm root cause before fixing.** If the fix isn't obvious, the root cause hasn't been found. 5. **Apply the minimal fix:** - Fix only what is broken — do not refactor surrounding code - If larger change needed: note it and add a refactor task instead 6. **Verify the fix:** - Does it resolve the bug? Does it break anything else? - If tests exist: do they pass? 7. **Document in STATE.md Completed Tasks Log:** - Root cause: [what caused it] - Fix applied: [what changed and why] 8. **Update STATE.md.** --- ## Constraints - Never refactors while fixing a bug — separate tasks - Never applies a fix without confirming root cause - Never silently swallows errors --- ## Primary Agent fixer --- ## Definition of Done - [ ] Bug reproduced before fixing - [ ] Root cause confirmed (not just symptom treated) - [ ] Minimal fix applied - [ ] Fix verified against original bug report - [ ] Finding documented in STATE.md - [ ] STATE.md updated ## Output Contract | Field | Value | |-------|-------| | **Artifacts** | Bug fix applied to source files | | **State Update** | `.claude/project/STATE.md` — mark task complete, log root cause and fix | | **Handoff Event** | `TASK_COMPLETED` (bug fixed) |
Related Skills
Supply Chain Audit
Audit the dependency supply chain for security risks beyond what `npm audit` or `pip audit` catches. Analyzes dependency health, maintainer trust signals, typosquatting risk, and transitive dependency exposure.
SEO Audit
Audit web pages for search engine optimization: meta tags, heading hierarchy, structured data, image optimization, mobile-friendliness, and content quality. Complements SKL-0013 (Growth & Distribution) by validating what was built.
Pitch Deck
Create a structured pitch deck outline for investors, stakeholders, or partners. Covers problem, solution, market, traction, team, and ask. Natural output after PRD + Problem Stress Test validation.
Launch Checklist
Pre-launch validation covering everything deployment (SKL-0021) doesn't: analytics, error tracking, social meta, legal pages, email setup, DNS, SSL, and go-live readiness. Produces a launch readiness report with pass/fail checklist. Use this skill before going live on any project.
Insecure Defaults Detection
Detect insecure default configurations, hardcoded credentials, fail-open security patterns, and dangerous default values in application code and configuration files. Complements SKL-0015 (Security Audit) by focusing on configuration-level vulnerabilities that dependency scanners miss.
Differential Security Review
Security-focused review of code changes using git diff analysis. Identifies security implications of recent modifications — new attack surfaces, removed protections, changed auth logic, and risky refactors. Complements SKL-0016 (Code Review) with a security lens on diffs.
Copywriting
Write conversion-focused copy using proven frameworks (AIDA, PAS, BAB). Produces headlines, CTAs, landing page copy, email sequences, and micro-copy. Ensures copy matches brand voice and target audience.
Competitor Analysis
Structured competitor research: features, pricing, positioning, gaps, and differentiation strategy. Feeds into PRD Writing (SKL-0004) and Problem Stress Test (SKL-0027) with better market context.
UX Design
Design user experiences including wireframes, flows, and interaction patterns. Use this skill when UX design work is requested, including onboarding flows and interface layouts.
User Acceptance Testing
Structured QA testing with four modes: diff-aware (auto-scoped to branch changes), full (systematic exploration), quick (30-second smoke test), and regression (compare against baseline). Produces health score, structured reports, and actionable bug lists. Use this skill when UAT is requested or a feature is ready for acceptance testing.
Token Audit
Audit the current project for token waste patterns. Produces a Token Health Report with scored findings and actionable fixes. Use this skill when token usage feels high, sessions are hitting limits, or before optimizing costs.
Test Writing
Write automated tests for existing or new functionality. Use this skill when tests are requested, including unit tests, integration tests, and end-to-end tests.