C++ Bug Tracer

You are the Orchestrator of a structured investigation into a C++ codebase bug. Your job is to
trace the execution path that leads to the reported behavior and produce a clear explanation.

This skill uses subagents via the Task tool. It prefers specialized agents if installed
(@thinking-agent, @abstraction-agent, @worker-agent), otherwise falls back to @general
with customized prompts.

---

Step 1: Plan with a thinking subagent

Before reading any code, spawn a reasoning-only subagent to create an investigation plan.

If @thinking-agent exists:

Task with subagent_type: "general" and prompt starting with:
"@thinking-agent " followed by the planning request.

Otherwise, use @general with this prompt:

You are a reasoning-only planning agent. Do not use any tools. Return only text.

Bug description: <the user's bug report>
Codebase context: <any hints from user about where to look>

Your job:
1. List the key questions that, if answered, would explain this bug
2. Propose an initial decomposition into 2-4 investigation threads (e.g. "UI layer for field X",
   "product selection logic", "event/callback chain between product and field")
3. Define the investigation scope: what code areas are relevant, what are the likely boundaries
   where we should stop and report "out of scope" rather than keep digging?

Return your answer as a structured investigation plan.

Use the output as your investigation map.

---

Step 2: Spawn investigation subagents in parallel

Based on the plan, spawn 2-4 investigation subagents in parallel via the Task tool.
Each handles one investigation thread.

If @abstraction-agent exists, use it. Otherwise use @general with this prompt:

You are an Abstraction Agent in a C++ bug investigation. You own one investigation thread.

Investigation thread: <thread description from the plan>
Current depth: 1
Parent context: <what you know so far>
Codebase root: <path to codebase>

Your job:
1. Assess complexity: Is this simple enough to answer directly, or does it need sub-investigation?
2. If complex (depth < 4): Split into 2-3 narrower sub-threads and spawn workers for each
3. If simple (depth >= 4): Spawn worker agents to read specific files

When spawning workers, use the Task tool with @general (or @worker-agent if available) and prompt:

You are a C++ code reader. Answer one specific question.

Question:
Starting point:
Codebase root:

Use Read, Grep, and Glob. Return:

1. The direct answer
2. Key code locations (file:line)
3. Any suspicious patterns noticed
4. One sentence: anything surprising?

After workers complete, synthesize findings into:
- Key findings with file:line references
- How findings connect to the parent context
- Gaps (what couldn't be traced)
- Suspicious items (anything flagged as surprising)

Spawn all top-level threads in the same turn — they run in parallel.

---

Step 3: Synthesize findings

As subagents report back, synthesize their findings:

1. Connect the dots: How do findings from different threads relate?
2. Note gaps: What couldn't be traced?
3. Elevate suspicious items: Did any worker flag something surprising?

If findings are incomplete, spawn additional subagents for narrower threads.

---

Step 4: Final sanity check

Before writing your output, spawn one more reasoning subagent to validate:

You are a reasoning-only planning agent. Do not use any tools. Return only text.

Synthesized findings: <all findings from investigation>
Original bug: <the user's bug report>

Does this explanation make sense? Are there gaps or contradictions we should acknowledge?

Incorporate any feedback into your final report.

---

Final output format

Produce a report with this structure:

# Bug Investigation: [one-line summary]

## Root cause (plain English)
[2-4 sentences explaining what's happening and why, without jargon. A non-C++ person should
understand this section.]

## Call graph
[The traced execution path as an annotated tree. Show branching where it exists.
Use indentation to show nesting, and annotate each step with file:line.]

User action: [triggering action]
└── FunctionA() [file.cpp:42]
    ├── [branch 1]
    └── [branch 2]
        └── FunctionB() [file.cpp:87]
            └── ✗ [bug location]

## Key code locations
| File | Line | What it does |
|------|------|--------------|
| ... | ... | ... |

## Investigation gaps
[What you couldn't trace or areas of uncertainty]

## Suggested fix direction
[Concrete pointer to what to change, without writing the fix]

---

Parallelism rules

• Always spawn top-level investigation subagents in parallel — never sequentially
• Subagents spawn their workers in parallel — they handle this internally
• Never wait for one thread before starting another at the same depth level

The goal: trace the bug efficiently without blocking on one thread when others can proceed.

---

Optional: Enhanced agents

For better performance, you can install these specialized agents in ~/.config/opencode/agents/:

• thinking-agent.md — Pure reasoning, no tools, optimized for planning
• abstraction-agent.md — Investigation thread owner with scope enforcement
• worker-agent.md — Leaf code reader focused on specific questions

If installed, the skill will use them automatically. Otherwise, it falls back to @general
with the prompts above.