SuperAPI AI Directory

ac-debug

Coding & development

View repository

Updated 10-16 09:27

About this skill

Debug - Main-thread diagnosis + Subagents evidence gathering

Locate the root cause of the problem; when necessary, the Claude main thread coordinates multiple subagents to gather evidence in parallel; final diagnosis, user communication, code fixes, and verification are all handled by the main thread.

How to Use

/ac-debug <问题描述>

Role Division

Role Responsibilities
Claude (Main Thread) Collect the problem, decide whether to enable subagents, integrate evidence, output the diagnosis, wait for confirmation, perform the fix
subagents Retrieve evidence such as call chains, log clues, and configuration/test impact in parallel, without modifying code

Execution Constraints

Working Directory:

  • If the user has added multiple workspaces via /add-dir first use Glob/Grep to determine the workspace relevant to the task
  • If it cannot be determined, use AskUserQuestion to ask the user to select the target workspace
  • Complete diagnosis and fixing within the current session, without relying on external models or additional sessions

Conditions for Using subagents:

  • Applicable: the error path is unclear, multiple modules are involved, there are many logs/stack traces, and multiple directions need to be investigated in parallel
  • Preferred: use read-only subagents for call-chain retrieval, error-point context collection, and configuration/test impact analysis
  • Not applicable: the error point is clear, it is a small single-file problem, or a simple problem that can converge with two or three searches

Important:

  • Do not call any external models, background tasks, or additional Bash orchestration
  • subagents only perform retrieval and evidence gathering, do not modify code, and do not directly give the user a final conclusion
  • For search or analysis content already delegated to subagents, the main thread should not repeat it
  • The final diagnostic conclusion must be output uniformly by the main thread
  • Before fixing, the diagnostic results must first be shown to the user and confirmation awaited

Execution Workflow

Problem Description:$ARGUMENTS

🔍 Phase 0: Prompt enhancement (optional)

[模式:准备]

Analyze the intent, missing information, and implicit assumptions of $ARGUMENTS, and complete them into structured requirements (clear goals, technical constraints, scope boundaries, acceptance criteria); during subsequent diagnosis, prioritize the enhanced requirements.

🔎 Phase 1: Context collection and parallel evidence gathering

[模式:研究]

  1. The main thread first collects the minimal necessary information: error logs, stack traces, reproduction steps, related files
  2. If the problem is relatively simple, continue diagnosis directly
  3. If the problem spans modules or there are many clues, start subagents in parallel as needed, typically split into:
    • Call-chain investigation: locate the error path, entry points, and related callers
    • Evidence collection: organize logs, stack traces, exception branches, and boundary conditions
    • Impact-scope investigation: check configuration, tests, dependent modules, and the related surface of recent changes
  4. After subagents return evidence, locations, and suspicious points, the main thread collects them uniformly

🔬 Phase 2: Main-thread diagnosis

[模式:诊断]

  1. Diagnose based on the evidence collected by the main thread and subagents
  2. Output diagnostic hypotheses (sorted by likelihood), each hypothesis including:
    • Cause
    • Evidence
    • Verification method
    • Fix suggestion
  3. Supplement with a round of targeted retrieval when necessary until the diagnostic scope converges

🔀 Phase 3: Hypothesis Integration

[模式:验证]

  1. Cross-validate code, logs, stack traces, and reproduction steps
  2. Filter Top 1-2 most likely causes
  3. Define the minimal fix path and validation strategy

⛔ Phase 4: User Confirmation (Hard Stop)

[模式:确认]

## 🔍 诊断结果

### 关键证据
- <证据 1>
- <证据 2>

### 综合诊断
**最可能原因**:<具体诊断>
**验证方案**:<如何确认>
**修复方向**:<准备怎么改>

---
**确认后我将执行修复。是否继续?(Y/N)**

⚠️ Must wait for user confirmation before proceeding to Phase 5

🔧 Phase 5: Fix and Validation

[模式:执行]

After user confirmation:

  1. The main thread implements the fix based on the diagnosis
  2. Run tests or validation steps for the minimal relevant scope
  3. If validation fails, fix the regression issue first before delivery

Key Rules

  1. Evidence first – Base decisions on code, logs, stack traces, and reproduction information
  2. Main thread closes the loop – The final diagnosis, fix, and validation are all completed by the main thread of the current session
  3. Subagents only assist with evidence gathering – Use as needed, not enabled by default, and do not modify code
  4. Fix after user confirmation – Confirmation must be obtained before fixing