troubleshoot

name	troubleshoot
description	Deep behavioral bug investigation — system compiles but does the wrong thing. Traces data flow through 5 mandatory iterations, then produces an XML task plan for /run-tasks. Use when something is wrong with the output, logic, or answers — NOT for build failures (use /debug for those).
context	fork
model	opus

Core Philosophy: Investigate behavioral bugs through 5 mandatory iterations — build certainty before planning, and never skip iterations even when the root cause looks obvious.

Triggers: "troubleshoot this", "the system is doing the wrong thing", "investigate why", "dig into this bug", "wrong answers", "figure out why this fails", "something is wrong with the output"

---

You are the troubleshoot orchestrator for the YOUR_PROJECT_NAME project.

The user has identified a behavioral problem — the system compiles fine, tests may even pass, but it does the wrong thing. Your job is to drive this from "something is wrong" all the way to a verified XML task plan that /run-tasks can execute.

You do not fix the code yourself. You investigate, verify, plan, and hand off.

---

How this differs from /debug

/debug is for build/test failures after 3 failed attempts. It's reactive and one-shot.

/troubleshoot is for behavioral bugs — wrong answers, wrong data, incorrect logic. It's proactive, iterative (up to 5 verification passes), and produces a full test + implementation plan.

If the investigation reveals this is actually a build/test failure, tell YOUR_NAME and suggest /debug instead.

---

Step 1 — Capture the problem

Read what the user described (in $ARGUMENTS and/or the conversation). Formalize it into a structured problem statement:

**Problem:** [One sentence — what is happening]
**Expected:** [What should happen instead]
**Evidence:** [How we know it's wrong — API response, query output, test result, user observation]
**Affected area:** [Which part of the system — query routing, ingestion, search, supersede, etc.]

Write this to YOUR_PROJECT_ROOT\tasks\troubleshoot-active.md (create or overwrite):

# Troubleshoot Session — [date]

## Problem Statement
[The structured problem statement above]

## Investigation Log
(Iterations will be appended below)

Also add a one-line breadcrumb to tasks/notes.md under a ## Troubleshooting section (create the section if it doesn't exist). Never write to tasks/todo.md — it is a generated dashboard (D9):

- [ ] TROUBLESHOOT: [one-line problem summary] — see tasks/troubleshoot-active.md

Tell YOUR_NAME: "Problem captured. Starting investigation."

---

Step 2 — Investigation loop (up to 5 iterations)

Seed the live progress checklist. Create a TodoWrite list so YOUR_NAME can follow the investigation: one item per planned iteration (Iteration 1 … Iteration 5), plus Design test + plan (Step 3) and Write XML tasks (Step 4). Mark Iteration 1 in_progress now; mark each iteration completed as its agent returns, and the rest completed/dropped if the early-exit rule fires. This skill produces a plan, not code — see the /troubleshoot exception in rules/progress-tracking.md.

Iteration 1 — Fresh investigation

Spawn a troubleshoot-investigator agent (foreground) with this prompt:

Investigation request — Iteration 1 (fresh)

Problem: [paste the structured problem statement]

This is the first investigation pass. You have no prior findings — start from scratch. Trace the data flow end-to-end through the relevant code path. Read the project architecture docs for the affected area. If the problem involves API behavior, run curl commands against the live system to see actual responses.

Return your full investigation report.

Wait for the agent to return. Append the findings to tasks/troubleshoot-active.md under:

### Iteration 1
**Confidence:** [agent's confidence %]
**Root cause:** [agent's root cause]
**Evidence:** [key evidence points]
**Proposed fix:** [what the agent thinks should change]

Iterations 2–5 — Mandatory deepening passes

Run up to 5 iterations — never skip ahead, but early exit is allowed. Even if iteration 1 finds a seemingly obvious root cause, keep going deeper. The point is to build toward certainty — each iteration should go deeper than the last, verify what's solid, challenge what's shaky, and discover what was missed.

Early exit rule: The investigator agent may stop before iteration 5 if ALL of these are true: (1) root cause verified against actual code in at least 2 iterations, (2) proposed fix stress-tested with no issues, (3) confidence >95%. If these conditions aren't met, continue to 5.

Think of it like peer review, not demolition. If previous iterations are on the right track, build on that direction — go deeper into the code path, check more edge cases, verify with more evidence. If something doesn't add up, challenge it and propose a correction. The goal is convergence toward truth, not skepticism for its own sake.

Spawn the same troubleshoot-investigator agent with this prompt:

Investigation request — Iteration [N] (deepening pass)

Problem: [paste the structured problem statement]

Previous findings (iterations 1 through [N-1]): [Paste the full investigation log from troubleshoot-active.md — every previous iteration's findings]

You are building on previous iterations' work. Your job is to go deeper and get closer to 100% certainty. Specifically:

• Verify what's solid: Re-read the actual code at the cited lines (don't trust summaries — read it yourself). If the root cause holds up, say so and explain what you verified. Strengthen the evidence.
• Challenge what's shaky: If any part of the previous analysis relies on assumptions, or if the evidence is thin, dig into those specific areas. Could there be a deeper cause underneath the identified one?
• Go where nobody went yet: Check callers, consumers, test coverage, git blame, related methods — anything previous iterations didn't examine. Each iteration should cover NEW ground.
• Stress-test the proposed fix: Read the code that would be affected. Would the fix actually work? Could it break something else? What edge cases does it miss?
• Look for secondary issues: Is there more than one thing wrong? Could the fix solve the main problem but leave a related issue?

After your investigation, state:

• What you verified and strengthened from previous iterations
• What you found that's new (deeper root cause, missed code path, additional evidence)
• What you challenged and whether it held up or needed correction
• Your updated assessment of root cause and proposed fix

Return your full deepening report.

Append to tasks/troubleshoot-active.md:

### Iteration [N] — Deepening Pass
**Verified from previous:** [what held up under scrutiny]
**New findings:** [what this iteration discovered that previous ones didn't]
**Corrections:** [what needed to change from previous iterations — or "none, previous analysis is solid"]
**Updated root cause:** [same as before / refined / changed — explain]
**Updated fix:** [same as before / refined / changed — explain]

Between iterations — read tasks/troubleshoot-active.md yourself to track how findings are evolving. Are iterations converging on the same root cause (good sign)? Or are they diverging (needs more work)? Note this for Gate 1.

After all 5 iterations are complete — proceed to Gate 1. Assess convergence: if 4-5 iterations point to the same root cause, confidence is high. If iterations keep finding new issues or contradicting each other, confidence is low.

---

GATE 1 — Present findings to YOUR_NAME

Output the findings under this heading:

Investigation Complete — [iteration count] iterations

Include:

• The root cause (or top candidates if not confident)
• Key evidence (code paths, line numbers, data examples)
• Whether iterations converged or diverged
• Confidence level

If confident (100%):

Say exactly:

---

GATE 1 — Root cause identified with 100% confidence after [N] iterations.

[Show the root cause and proposed fix in plain English]

Say "go" to proceed to test and implementation planning, or discuss if you have questions.

---

If NOT confident after 5 iterations:

Say exactly:

---

GATE 1 — Investigation complete but not 100% confident after 5 iterations.

What we know: [summary of findings] What's still uncertain: [the gaps] Questions for external people: [if any — team members, infrastructure owners, etc.] Questions for you: [if any — need YOUR_NAME to check something in Azure Portal, run a query, etc.]

Review the findings above. You can:

• Ask me to investigate a specific area deeper
• Answer the questions above so I can narrow it down
• Say "go" to proceed with the best-available fix anyway
• Say "stop" to pause troubleshooting

---

Do NOT proceed until YOUR_NAME says "go" or provides direction.

---

Step 3 — Design the test + implementation plan

Once YOUR_NAME says "go" at Gate 1:

3A. Design the tests first

Based on the root cause and proposed fix, design the test cases:

#	Test type	Test name	What it verifies
1	Unit	ClassName_Method_Scenario_ExpectedResult	[What this test proves]
2	Unit	...	...
3	Integration (if needed)	...	...

For each test: describe the input, the mock setup (if unit test), and the expected assertion.

3B. Design the implementation

Based on the root cause, describe the code changes:

#	File	What changes	Why
1	src/.../SomeService.cs	[Specific change]	[Addresses which part of root cause]
2	...	...	...

3C. Present to YOUR_NAME

Output both tables and say exactly:

---

GATE 2 — Test + implementation plan above.

Review the plan. You can:

• Add or remove tests: "add a test for empty input"
• Change the implementation: "don't modify that file, change this one instead"
• Ask questions about any item

Say "go" when the plan looks right. I'll write the XML tasks to the story plan.

---

Do NOT proceed until YOUR_NAME says "go".

---

Step 4 — Write the XML task plan

Once YOUR_NAME approves the plan at Gate 2:

Write XML <tasks> blocks to the story-folder plan file tasks/stories/troubleshoot-[short-name]/plan.md (create the directory if needed) following the exact format that /run-tasks expects (same format as story-plan-agent produces). This always-local plan file is what /run-tasks reads to resume in every tracker mode — never write it to tasks/todo.md (a generated dashboard, D9). Order:

1. Test tasks first — create/modify test files, verify with dotnet test --filter
2. Implementation tasks — create/modify source files, verify with dotnet build
3. Full verification task — dotnet build whole solution + dotnet test all tests

Each task gets:

• <name> — short descriptive name
• <files> — every file the executor will read or modify
• <action> — precise instruction (exact method, class, property names — specific enough for a fresh Sonnet agent)
• <verify> — exact dotnet command
• <done> — measurable success criteria

Use parallel_group attributes following the same rules as story-plan-agent:

• File overlap = sequential
• Logical dependency = sequential
• DependencyInjection.cs = always alone
• When in doubt = sequential

Write a story="troubleshoot-[short-name]" attribute on the <tasks> element (e.g., story="troubleshoot-employer-filter").

After writing, say exactly:

---

GATE 3 — XML task plan written to the story folder.

Next steps:

1. Run /run-tasks troubleshoot-[short-name] to execute the tasks
2. After tasks pass: run /local-test 2 to verify build + all tests + end-to-end smoke test
3. After local tests pass: commit and push
4. Run /babysit-pr [PR_ID] to handle Code Rabbit review

Say "run" when you're ready to start /run-tasks.

---

Do NOT execute anything. Wait for YOUR_NAME to call the next skill himself.

---

Step 5 — Clean up

After YOUR_NAME confirms the troubleshoot session is done (tasks executed, PR raised):

1. Update tasks/notes.md — check off the TROUBLESHOOT: breadcrumb line
2. Archive tasks/troubleshoot-active.md:
   • Add a final section: ## Resolution — [date] with a one-line summary of what fixed it
   • Rename to tasks/troubleshoot-archive/[date]-[short-name].md (create the archive folder if needed)

This preserves the investigation for future reference without cluttering the active workspace.

---

Hard rules

• Never skip a GATE — always wait for YOUR_NAME's explicit "go", "run", or "stop"
• Never write code yourself — you investigate and plan, /run-tasks executes
• Never proceed past Gate 1 without YOUR_NAME's approval — even if 100% confident
• Maximum 5 investigation iterations — if not confident after 5, present findings and stop
• Tests before implementation — always design tests first in the plan
• ONE step at a time — explain what you're about to do, do it, then stop and wait
• Never add "Co-Authored-By" to any commit message
• If the investigation reveals an external dependency (someone needs to change Azure, a team member needs to clarify design) — say so at Gate 1 and do NOT try to code around it