--- title: "Systematic Debugging: review, role & definition · Undominated.ai" canonical: https://undominated.ai/agents/github-debug-mode/ description: "Reproduces an application bug, tests root-cause hypotheses and verifies a minimal fix against the original failure." --- # Systematic Debugging: review, role & definition · Undominated.ai > Reproduces an application bug, tests root-cause hypotheses and verifies a minimal fix against the original failure. [← Explore all agents](/agents/) TESTING AND REVIEW / github # Systematic Debugging Reproduces an application bug, tests root-cause hypotheses and verifies a minimal fix against the original failure. Use this definition ↓Original source ↗ SOURCE REVIEW Reviewed 2026-09-21 Evidence 4 linked sources Publisher github Licence MIT ↗ Revision ad4c196b933c Read what was—and wasn’t—checked ↓ “Debug your application to find and fix a bug” github · upstream description ↗ Our analysis follows below. 01 / THE REASONING ## Why this made the selection. - Requires reproduction and an expected-versus-actual report before changing code. - Closes the loop by repeating the original reproduction, running relevant tests and recording preventive regression coverage. ### A good fit for - Repairing a reproducible application failure beyond browser-specific investigations. - Keeping a bug fix focused when broad refactoring would hide its cause. ### Weigh up before choosing - The procedure is a general debugging framework, so the caller must provide a concrete symptom and a usable reproduction environment. - It does not define a fixed retry budget or explicit stop condition for an unreproducible failure. - Declared tools include code editing, test execution and a terminal; use an appropriate development environment. 02 / THE REVIEW RECORD ## What we actually inspected. Source review has boundaries. A clear record is more useful than a “safe” badge. ### Material inspected - agents/debug.agent.md (complete original frontmatter and body; strict YAML duplicate-key check) - LICENSE (full applicable licence bytes and redistribution terms) - Current official host configuration documentation; exact source and licence SHA-256 recorded ### Our findings - The definition supplies a sequential investigation or test workflow and a concrete evidence/reporting expectation. - The tool scope includes code changes and execution; this is an implementation-capable role rather than a read-only review restriction. ### Not established by this review - This agent has not been executed or benchmarked. - Host discovery, configured tool availability, model behaviour and task outcomes were not runtime-tested. The review applies to the material and revision named here. A newer upstream release can change its behavior. 03 / PUT IT TO WORK ## Use the role in your project. Upstream setup instructions ↗ - Download the original debug.agent.md with its full licence and attribution; inspect the complete instructions and tool scope before use. - Place the reviewed working copy at .github/agents/debug.agent.md. Select the custom agent in VS Code’s agent picker. - Use the host’s tool configuration to check every declared tool name and any MCP dependency. Confirm a pinned model is available or select a supported one in the working copy; never treat unknown tools as extra permission. - Provide a bounded task, the existing project conventions and a reproducible development/test environment. Keep generated findings separate from checks that actually ran. ### Before you start - GitHub Copilot in VS Code with a model available to the account. - Relevant source, requirements and a project test environment. ### Compatibility GitHub Copilot custom agents in VS Code ### Repository editing and local test execution - The original grants repository edit and execution tools. Commands and test fixtures can change local or connected state. - Review the active tool list and host approval controls before assigning work. ### Cost model The definition is reusable under its stated licence. The host, model and connected services have their own access and billing terms. THE COMPLETE REVIEWED DEFINITION ## Read it before you reuse it. Original source bytes, with attribution. Review the host-specific setup notes above. Copy definition ↗ [Download definition + licence ↗](/resources/agents/github-debug-mode/bundle.zip)[Raw Markdown ↗](/resources/agents/github-debug-mode/definition.md) --- description: 'Debug your application to find and fix a bug' name: 'Debug Mode Instructions' tools: ['edit/editFiles', 'search/codebase', 'search/usages', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'read/problems', 'execute/testFailure', 'web/fetch', 'execute/runTests'] --- # Debug Mode Instructions You are in debug mode. Your primary objective is to systematically identify, analyze, and resolve bugs in the developer's application. Follow this structured debugging process: ## Phase 1: Problem Assessment 1. **Gather Context**: Understand the current issue by: - Reading error messages, stack traces, or failure reports - Examining the codebase structure and recent changes - Identifying the expected vs actual behavior - Reviewing relevant test files and their failures 2. **Reproduce the Bug**: Before making any changes: - Run the application or tests to confirm the issue - Document the exact steps to reproduce the problem - Capture error outputs, logs, or unexpected behaviors - Provide a clear bug report to the developer with: - Steps to reproduce - Expected behavior - Actual behavior - Error messages/stack traces - Environment details ## Phase 2: Investigation 3. **Root Cause Analysis**: - Trace the code execution path leading to the bug - Examine variable states, data flows, and control logic - Check for common issues: null references, off-by-one errors, race conditions, incorrect assumptions - Use search and usages tools to understand how affected components interact - Review git history for recent changes that might have introduced the bug 4. **Hypothesis Formation**: - Form specific hypotheses about what's causing the issue - Prioritize hypotheses based on likelihood and impact - Plan verification steps for each hypothesis ## Phase 3: Resolution 5. **Implement Fix**: - Make targeted, minimal changes to address the root cause - Ensure changes follow existing code patterns and conventions - Add defensive programming practices where appropriate - Consider edge cases and potential side effects 6. **Verification**: - Run tests to verify the fix resolves the issue - Execute the original reproduction steps to confirm resolution - Run broader test suites to ensure no regressions - Test edge cases related to the fix ## Phase 4: Quality Assurance 7. **Code Quality**: - Review the fix for code quality and maintainability - Add or update tests to prevent regression - Update documentation if necessary - Consider if similar bugs might exist elsewhere in the codebase 8. **Final Report**: - Summarize what was fixed and how - Explain the root cause - Document any preventive measures taken - Suggest improvements to prevent similar issues ## Debugging Guidelines - **Be Systematic**: Follow the phases methodically, don't jump to solutions - **Document Everything**: Keep detailed records of findings and attempts - **Think Incrementally**: Make small, testable changes rather than large refactors - **Consider Context**: Understand the broader system impact of changes - **Communicate Clearly**: Provide regular updates on progress and findings - **Stay Focused**: Address the specific bug without unnecessary changes - **Test Thoroughly**: Verify fixes work in various scenarios and environments Remember: Always reproduce and understand the bug before attempting to fix it. A well-understood problem is half solved. The download contains debug.agent.md . Keep its filename when placing it in the agent directory described above. By **github**. Exact upstream source ↗ · [Licence](/resources/agents/github-debug-mode/LICENSE.txt) · [Attribution](/resources/agents/github-debug-mode/ATTRIBUTION.txt) SHA-256 2ac23b322866f85b15918847b7989887df0f167aefdd815f7790214412b6ccdc Read the applicable licence MIT License Copyright GitHub, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 04 / FOLLOW THE EVIDENCE ## The source trail. Our notes are separate from the original resource. Check upstream before adopting a new version. - Complete upstream definition at the reviewed revision ↗ Checked 2026-09-21 https://github.com/github/awesome-copilot/blob/ad4c196b933c5ca7f82a5ba78969ddcd2603ba80/agents/debug.agent.md Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, access - Applicable full upstream licence ↗ Checked 2026-09-21 https://github.com/github/awesome-copilot/blob/ad4c196b933c5ca7f82a5ba78969ddcd2603ba80/LICENSE Supports: license, artifact - Current official custom-agent configuration ↗ Checked 2026-09-21 https://code.visualstudio.com/docs/agent-customization/custom-agents Supports: compatibility, install, access, limitations, review - VS Code tool availability and permissions ↗ Checked 2026-09-21 https://code.visualstudio.com/docs/agents/run/tools Supports: install, access, limitations, review KEEP COMPARING ## Other approaches to consider. Related by category or shared topics. These are alternatives to inspect, not a measured quality order. [### Hypothesis Debugging Investigator ↗ Investigates one assigned bug hypothesis and sends the team lead a cited account of supporting evidence, contradictions and remaining gaps.](/agents/wshobson-team-debugger/)[### FastAPI Reviewer ↗ Reviews FastAPI changes for async blocking, dependency wiring, schema exposure and test setup, with file references and explicit unverified risks.](/agents/ecc-fastapi-reviewer/)[### Playwright Test Explorer ↗ Explores a working interface through Playwright before generating and running TypeScript tests for its observed user flows.](/agents/github-playwright-tester/) [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)