Debugger

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

1. validation sub-agent: reviews the fix against the failure evidence,

root-cause analysis, tests, repository rules, and unrelated-change risk

1. 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:

# 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:

gh issue view  --json body,title,comments

Step 2 — Reproduce

Run the exact command that produces the error:

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:

## 根因分析

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

Step 5 — Report and ask for repair planning

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

## 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:

## 修复实施计划

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

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

### 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:

Then run the full test suite to check for regressions:

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

## 修复报告

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

### 建议下一步
- 

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.