# Debugger

> Internal engineering specialist—not a direct entry point. Invoked by engineer-agent after pm-agent handoff to reproduce, diagnose, and fix confirmed implementation defects with minimal scoped changes and verification evidence.

- **Type:** Skill
- **Install:** `agentstack add skill-neplich-dev-agent-skills-debugger`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Neplich](https://agentstack.voostack.com/s/neplich)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Neplich](https://github.com/Neplich)
- **Source:** https://github.com/Neplich/dev-agent-skills/tree/main/agents/engineer/skills/debugger

## Install

```sh
agentstack add skill-neplich-dev-agent-skills-debugger
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Debugger

Systematically reproduce, diagnose, and fix bugs. Follows a strict process:
align expected behavior first, reproduce the failure, analyze the root cause,
report the bug analysis, plan the repair with user confirmation, then fix
minimally and verify.

## When to Use

- Tests are failing
- Build is broken
- Runtime error reported
- `test-writer` flagged a code bug
- User reports unexpected behavior
- GitHub Issue describes a bug

## Core Principle

**Never guess.** Follow this order strictly:

```
Align Expected Behavior → Reproduce → Analyze → Report → Repair Plan → Confirm → Fix → Verify
```

Do NOT jump to fixing. Do NOT propose or apply a fix before understanding the
expected behavior, root cause, reporting the analysis, and getting confirmation
on the repair plan. Do NOT create or update E2E test cases before the repair
plan is confirmed.

## PM Handoff Entry Gate

Before debugging, require an explicit PM/Engineer handoff packet or an
equivalent confirmed document chain that defines expected behavior. If the user
directly invokes `debugger` with a raw bug report and no approved PRD/TRD
expectation source, do not reproduce or fix yet; return the request to
`pm-agent` for classification. Direct invocation does not bypass this gate.

Use the PM-side packet definition in
`agents/product_manager/skills/idea-to-spec/_internal/_shared/skill-map.md`.
When equivalent docs are present, Step 0 below remains the authoritative
expected-behavior gate.

## Complex Fix Sub-Agent Split

For complex bug fixes, keep the main process responsible for the failure
context, root-cause judgment, repository rules, test evidence, and final risk
summary. When sub-agent capabilities are available, split the work after the
root cause and repair plan are confirmed:

1. implementation sub-agent: applies the smallest scoped fix and related
   regression test updates
2. validation sub-agent: reviews the fix against the failure evidence,
   root-cause analysis, tests, repository rules, and unrelated-change risk
3. main process: integrates the result and produces the final repair report

Do not use this split before reproduction and root-cause analysis. Do not force
it for simple single-file fixes, pure diagnosis, or when the user explicitly
asks not to use sub-agents.

## Repair Plan Gate

After the root cause is confirmed, output the bug analysis report first and ask
whether the user wants a repair implementation plan. Do not write code yet.

If the user confirms, produce a repair plan that includes:

- problem, root cause, location, and impact
- PRD/TRD alignment conclusion and source document paths
- files or modules expected to change
- minimal repair approach
- regression tests or verification commands
- suggested QA E2E function directory:
  `docs/qa/e2e/{feature_path}/`, when the fix may affect E2E
  acceptance coverage
- whether implementation/validation sub-agent split is needed
- risks, blockers, and forbidden areas

Present the repair plan and wait for user confirmation. Do not apply the fix,
update tests, update E2E TC, update E2E scripts or results, or delegate
implementation until the user confirms the exact repair plan.

## Step 0 — Align expected behavior with PRD / TRD

For user-reported bugs in an existing feature, identify the likely
`feature_path` and read the durable expected-behavior documents before deciding
that code should be changed:

- `docs/pm/{feature_path}/PRD.md`
- `docs/engineer/{feature_path}/TRD.md`
- `docs/pm/{feature_path}/DECISIONS.md` or other product decision records, when
  present

Resolve `feature_path` by scanning `docs/pm/**/PRD.md` and reading
`feature_path`, `parent_feature`, and `feature_level` frontmatter where
present. Old single-level docs without those fields are compatible and count as
level-1 features. If the likely feature is ambiguous, the PRD is missing, the
path is invalid, or the report appears to target a child feature that was
generated as a wrong top-level directory, classify the report as `missing_docs`
and request PM alignment instead of guessing.

Use those docs to classify the report:

- If the code or failing test deviates from PRD / TRD, and no present decision
  record conflicts, cite the relevant docs as the expected behavior source and
  continue with reproduction and root-cause analysis.
- If the user's requested behavior conflicts with the approved PRD, TRD, or an
  existing decision record, stop before repair planning and hand off to
  `pm-agent:idea-to-spec` using the `existing-project-update` lane.
- If PRD is stable but the Engineer TRD is missing, incomplete, stale, conflicts
  with the codebase or bug context, uses a different `feature_path`, has
  mismatched `parent_feature` or `feature_level`, or has a `related_prd` that
  does not point to `docs/pm/{feature_path}/PRD.md`, stop before repair
  planning and hand off to `engineer-agent:trd-gen` with a TRD gap packet. The
  debugger owns naming the missing or conflicting technical decisions;
  `trd-gen` owns completing the TRD.
- If PRD is missing or ambiguous, or an existing decision record conflicts with
  the report, stop before fixing and request PM alignment. A user request to
  skip PRD alignment is a blocker or risk note, not permission to continue into
  repair planning, implementation, or E2E updates.

If the target agent's plugin for a cross-agent handoff is not installed or
unavailable, state the missing stage and required plugin, mark that handoff
stage as blocked, and do not perform the missing agent's responsibilities
yourself.

Record the classification explicitly as one of:

- `implementation_deviation`: approved PRD / TRD already defines the expected
  behavior and the implementation or test deviates from it.
- `requirement_change`: the user is asking to change approved expected
  behavior, so PM alignment is required before repair planning.
- `missing_docs`: PRD, product decision records, or expected behavior
  are missing or ambiguous.
- `trd_gap`: PM scope is stable, but the TRD is missing, stale, incomplete, or
  conflicts with the codebase or bug context.

A TRD gap packet should list the technical decisions that block debugging or
repair planning, including affected components, data flow / API / integration
impact, verification commands, release or rollback risk, and error handling,
observability, or security strategy when relevant.

Do not update E2E TC, scripts, assertions, or QA result files while the
classification is `requirement_change`, `missing_docs`, or `trd_gap`.
For `requirement_change`, do not write the new expectation into
`docs/qa/e2e/**` until PM updates the PRD or product decision record, TRD is
synchronized, and a confirmed
`docs/engineer/{feature_path}/IMPLEMENTATION_PLAN.md` exists. If a confirmed
repair later affects E2E coverage, pass a QA E2E handoff package after the fix
and verification rather than editing TC during diagnosis or repair planning.
That handoff must cite the confirmed
`docs/engineer/{feature_path}/IMPLEMENTATION_PLAN.md`, PRD/TRD alignment
conclusion, changed files, verification commands, and suggested QA E2E function
directory.

## Step 1 — Gather error context

Collect all available information:

- **Error message**: Full text including stack trace
- **Where it happens**: Which test, command, or user action
- **When it started**: Recent changes that might have caused it
- **Frequency**: Always, sometimes, or only under certain conditions

If the error came from `test-writer`:
```bash
# Re-run the specific failing test with verbose output
npm test -- --verbose 
pytest -v ::
go test -v -run  ./...
cargo test  -- --nocapture
```

If the error came from a GitHub Issue:
```bash
gh issue view  --json body,title,comments
```

## Step 2 — Reproduce

Run the exact command that produces the error:

```bash

```

If it succeeds (intermittent failure):
- Run it 3 more times
- Check for timing dependencies, shared state, or environment issues
- If still can't reproduce, report this and ask for more context

Capture the exact error output for analysis.

## Step 3 — Analyze root cause

Read the relevant source code. Start from the error location and trace upward:

1. **Read the failing line/function**: What is it trying to do?
2. **Read the caller**: What input does it receive?
3. **Read related code**: What state could cause this failure?
4. **Check recent changes**: `git log --oneline -10 -- ` and `git diff HEAD~5 -- `

Common root cause patterns:

| Error Type | Likely Cause | Where to Look |
|-----------|-------------|---------------|
| TypeError / nil pointer | Missing null check or wrong type | Input validation, API response handling |
| Import/module not found | Wrong path, missing export | Import statements, package.json exports |
| Test assertion failure | Logic error or wrong expected value | Both test and implementation |
| Build failure | Type mismatch, missing dependency | Type definitions, package manifest |
| Timeout | Async issue, infinite loop | Promises, goroutines, event handlers |

## Step 4 — Identify and confirm root cause

Before fixing, state the root cause clearly:

```text
## 根因分析

**问题**: 
**预期依据**: 
**根因**: 
**位置**: 
**影响**: 
```

## Step 5 — Report and ask for repair planning

After confirming the root cause, report the analysis before planning or fixing:

```text
## Bug 分析汇报

- **问题**: 
- **预期依据**: 
- **根因**: 
- **位置**: 
- **影响**: 
- **复现证据**: 

是否需要我基于这个根因产出修复实施计划？
```

Wait for the user's answer before producing a repair plan. If the user does not
confirm, stop after the analysis report.

## Step 6 — Produce repair implementation plan

Only after the user confirms repair planning, produce the plan:

```text
## 修复实施计划

### 文件变更清单
- 修改 `` — 

### 验证方式
- 重新运行 ``
- 运行 ``

### Sub-Agent 分工
- 触发判断: 
- 实现 sub-agent 范围: 
- 验收 sub-agent 范围: 

确认后开始修复？
```

Wait for user confirmation before fixing.

## Step 7 — Implement minimal fix

Fix the root cause with the smallest possible change:

- Don't refactor surrounding code
- Don't "improve" related code
- Don't add defensive checks elsewhere "just in case"
- Only change what's necessary to fix this specific bug

For complex fixes, delegate this step to an implementation sub-agent only after
the root cause and repair plan are confirmed. The task must include the failing
command, confirmed root cause, confirmed repair plan, owned files or modules,
forbidden areas, and the requirement not to revert unrelated changes.

## Step 8 — Verify fix

Run the previously failing command:

```bash

```

Then run the full test suite to check for regressions:

```bash

```

### Verification outcomes

- **Fix works, no regressions**: Report success
- **Fix works, but other tests break**: The fix exposed another issue, or the fix is wrong. Investigate.
- **Fix doesn't work**: Back to Step 3 — the root cause analysis was wrong

For complex fixes, assign a separate validation sub-agent after tests are run.
It should check the failure evidence, root-cause fit, regression coverage,
repository rules, unrelated changes, and residual risk. It must not broaden the
fix scope.

## Step 9 — Report

```text
## 修复报告

- **问题**: 
- **根因**: 
- **修复**: 
- **文件**: 
- **验证**: 失败测试 ✅ 通过, 回归测试 ✅ 通过
- **验收**: 
- **遗留风险**: 

### 建议下一步
- 
```

## Edge Cases

- **Multiple test failures**: Triage first. Look for a common root cause. If failures are independent, fix them one at a time starting with the simplest.
- **Flaky test**: If the test passes sometimes, focus on state management, timing, and test isolation rather than the implementation.
- **Environment-specific**: If the bug only happens in CI or on specific OS, check environment differences (Node version, OS paths, env vars).
- **Can't reproduce locally**: Ask for CI logs, environment details, or specific reproduction steps.
- **Fix requires changing PM docs**: If the bug reveals that the spec is wrong (not the code), flag this and recommend going back to PM Agent for a spec update.
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Neplich](https://github.com/Neplich)
- **Source:** [Neplich/dev-agent-skills](https://github.com/Neplich/dev-agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-neplich-dev-agent-skills-debugger
- Seller: https://agentstack.voostack.com/s/neplich
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.