Isolate root causes through structured log analysis, hypothesis testing, and fix validation to prevent symptom-fixing and tunnel vision. Use when any verification step fails, tests break, or debugging a reported bug.
From flownpx claudepluginhub synaptiai/synapti-marketplace --plugin flowThis skill is limited to using the following tools:
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Domain skill for structured investigation of bugs and unexpected behavior.
ALWAYS FIND ROOT CAUSE BEFORE ATTEMPTING FIXES. Symptom fixes are failure.
A fix that doesn't address root cause creates a new bug later. Every. Single. Time.
Collect before theorizing:
# Error logs, stack traces, recent changes
git log --oneline -10
git diff HEAD~3..HEAD --stat
git log, git diff)Look for patterns in the evidence:
Grep to find similar patterns: error messages, function calls, data flowsForm and test hypotheses systematically. Use TaskCreate for each hypothesis:
TaskCreate("Hypothesis 1: {theory}", "Confidence: High\nTest: {specific test}\nEvidence: {what points here}")
TaskCreate("Hypothesis 2: {theory}", "Confidence: Medium\nTest: {specific test}\nEvidence: {what points here}")
TaskCreate("Hypothesis 3: {theory}", "Confidence: Low\nTest: {specific test}\nEvidence: {what points here}")
| # | Hypothesis | Confidence | Test | Result |
|---|---|---|---|---|
| 1 | {theory} | High/Med/Low | {specific test} | {outcome} |
| 2 | {theory} | High/Med/Low | {specific test} | {outcome} |
| 3 | {theory} | High/Med/Low | {specific test} | {outcome} |
For each hypothesis: TaskUpdate(status: "in_progress") before testing, TaskUpdate(status: "completed") after — whether confirmed or disproven. Record the result.
Rules:
Write a test that reproduces the bug BEFORE fixing. If the test doesn't fail, you haven't found the bug.
TaskCreate("Fix validation", "Write reproducing test, implement fix, verify no regressions")
TaskUpdate("Fix validation", status: "in_progress")
TaskUpdate("Fix validation", status: "completed") after all tests pass. Use TaskList to confirm all hypotheses resolved and fix validated.
This skill activates automatically when ANY verification step fails — not just for bug-labeled issues:
Streamlined investigation: read error fully, form 1-2 hypotheses, fix and re-verify. No elaborate investigation needed for clear error messages — just fix and move on.
Read logs and errors BEFORE reading code:
Never start with "let me read the code and understand how it works." Start with "what went wrong and where."
| Trigger | Action |
|---|---|
| 3+ failed fix attempts | Stop fixing forward. The problem is architectural. Return to EXPLORE. |
| Can't explain current behavior | Don't guess. Investigate more. Add logging, add assertions. |
| Tunnel vision (>30 min on one theory) | Step back. List what you KNOW vs what you ASSUME. |
| Fix works but you can't explain WHY | Revert. An unexplained fix is a time bomb. |
| Bias | Symptom | Antidote |
|---|---|---|
| Confirmation bias | Only looking for evidence that confirms your theory | Actively seek DISCONFIRMING evidence |
| Anchoring | First theory dominates even after disproof | Write down ALL hypotheses before testing any |
| Recency bias | Blaming the last change | Check if the bug existed before the last change: git stash && test |
| Complexity bias | Assuming an elaborate cause | Check the simple things first: typos, wrong variable, off-by-one |
| Excuse | Response |
|---|---|
| "I know what's wrong" | Then prove it with evidence. If you're right, it takes 30 seconds. |
| "Quick fix, then proper fix later" | Later never comes. Fix root cause now. |
| "It works on my machine" | Then the bug is in environment differences. Investigate THAT. |
| "Let me just add a try-catch" | That's hiding the bug, not fixing it. Find the root cause. |
| "It's probably a race condition" | Probably? Prove it. Add timing logs, reproduce it reliably. |