| name | debug |
| description | Investigate bugs/issues to find concrete, evidence-backed reproduction steps without fixing them. Use when the user reports a bug, failure, regression, flaky behavior, stack trace, unexpected output, or asks to debug/reproduce an issue. |
Debug
Purpose
Help the user reproduce and understand an issue. Do not fix, patch, refactor, or propose fixes unless the user explicitly asks.
Rules
- Ground every claim in inspected source code, docs, logs, GitHub issues, or web search results.
- Prefer concrete evidence over theories. Label uncertainty clearly.
- Never jump straight to implementation changes.
- Do not propose fixes, mitigations, or code edits unless explicitly requested.
- The primary deliverable is reproducibility: exact steps, inputs, environment, observed behavior, and evidence.
Workflow
-
Capture the report
- Record symptoms, expected vs actual behavior, errors, stack traces, versions, environment, inputs, and timing.
- If key details are missing and not retrievable, ask only the minimal clarifying question.
-
Inspect evidence
- Search the repo for relevant code paths, error messages, config, tests, and docs.
- Use web/code search for third-party behavior, upstream docs, and GitHub issues when dependencies or external systems may be involved.
- Cite files, commands, docs, URLs, or issue references used as evidence.
-
Find the suspected source
- Identify the smallest code path or state transition that explains the symptom.
- Separate confirmed facts from hypotheses.
- Avoid fix language; focus on why the behavior is reachable.
-
Reproduce
- Try to reproduce locally when safe and feasible.
- Capture exact commands, inputs, fixtures, env vars, and outputs.
- If local reproduction is not possible, design a manual reproduction path.
-
Instrument when needed
- If more runtime evidence is needed, suggest temporary logs with a
[DEBUGGER] prefix so the user can filter them.
- Keep logs targeted to branch decisions, input shape, identifiers, state transitions, and caught errors.
- Ask the user to run the scenario and paste back only the
[DEBUGGER] lines plus the error/output.
Output format
Use this structure unless the user requests otherwise:
## Findings
- [Evidence-backed facts]
## Suspected source
- [File/function/code path and why it is implicated]
## Reproduction steps
1. [Exact step]
2. [Exact step]
## Expected vs actual
- Expected: ...
- Actual: ...
## Evidence
- `path:line` / command output / doc or issue URL
## If reproduction is still unclear
Add these temporary logs:
```[language]
console.log("[DEBUGGER] ...", ...)
```
Then run:
```sh
...
```
Paste back the `[DEBUGGER]` lines and the final error/output.
Manual reproduction log guidelines
Good [DEBUGGER] logs answer:
- Did this code path run?
- What input shape or key IDs reached it?
- Which branch was taken?
- What external response/status was received?
- What state changed immediately before the failure?
Avoid logging secrets, tokens, full PII, or huge payloads. Redact sensitive values.