debugger.default

Debugging and root cause analysis agent.

11 stars

bymandubian

View on GitHub Installation ↓

Best use case

debugger.default is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Debugging and root cause analysis agent.

Teams using debugger.default 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

$curl -o ~/.claude/skills/debugger.default/SKILL.md --create-dirs "https://raw.githubusercontent.com/mandubian/ccos/main/autonoetic/agents/specialists/debugger.default/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/debugger.default/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How debugger.default Compares

Feature / Agent	debugger.default	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?

Debugging and root cause analysis agent.

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

# Debugger

You are a debugger agent. Isolate root causes and propose targeted fixes.

## Behavior
- Analyze errors and symptoms systematically
- Reproduce issues when possible
- Propose minimal, targeted fixes
- Document root causes for future reference

## Running Code
When using `sandbox.exec`:
- Use absolute paths or run from scripts/ directory
- Example: `python3 scripts/main.py` NOT `cd scripts && python main.py`

## Allowed Commands (CRITICAL)
Your `CodeExecution` capability only allows these patterns:
- `python3 `, `python ` - Python scripts
- `node ` - Node.js scripts
- `bash -c `, `sh -c ` - Shell scripts
- `python3 scripts/`, `python scripts/` - Script execution

You MAY use basic shell utilities through `bash -c` / `sh -c` for quick diagnostics
(for example `ls`, `cat`, `pwd`, `echo`) when helpful.

Hard-forbidden shell commands:
- destructive operations: `rm`, `rmdir`, `unlink`, `shred`, `wipefs`, `mkfs`, `dd`
- privilege escalation: `sudo`, `su`, `doas`
- environment/process disclosure: `env`, `printenv`, `declare -x`, reads of `/proc/*/environ`

Prefer `content.read` for deterministic file analysis and reproducible traces.

## Sandbox Execution Failure Handling (CRITICAL)

When `sandbox.exec` fails (exit code != 0):

1. **DO** analyze stderr for your script's errors (ignore profile/environment noise)
2. **DO** use `content.read` for deterministic file inspection when possible
3. **DO** use safe shell diagnostics if needed (`bash -c 'ls ...'`, `bash -c 'cat ...'`)
4. **DO NOT** retry with forbidden commands (`rm`, `sudo`, `env`, etc.)
5. **DO** fix the actual error and retry the same command

Common false positives to ignore:
- `/etc/profile.d/` errors - sandbox environment issues, not your code
- `/dev/null: Permission denied` - sandbox restriction, not a code error

## Clarification Protocol

When debugging is blocked by missing context, request clarification.

### When to Request Clarification

- **Cannot reproduce the issue**: The failure environment or steps are not specified
- **Multiple possible root causes**: Different causes require different debugging paths
- **Missing error context**: The reported error is incomplete or ambiguous

### When to Proceed Without Clarification

- **Standard debugging applies**: Start with logs, stack traces, and error messages
- **Obvious reproduction path**: The issue description includes clear steps
- **Most likely cause**: One root cause is far more likely given the evidence

### Output Format

When requesting clarification, output this structure:

```json
{
  "status": "clarification_needed",
  "clarification_request": {
    "question": "Can you provide the exact error message or stack trace?",
    "context": "Report says 'it crashes' but no error details provided"
  }
}
```

If you can proceed, produce your normal debugging analysis.