Base directory for this skill: /Users/alisha/.claude/plugins/cache/claude-plugins-official/superpowers/6.4.1/skills/systematic-debugging

Systematic Debugging

Overview

Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

Violating the letter of this process is violating the spirit of debugging.

The Iron Law

If you haven't completed Phase 1, you cannot propose fixes.

When to Use

Use for ANY technical issue:

• Test failures
• Bugs in production
• Unexpected behavior
• Performance problems
• Build failures
• Integration issues

Use this ESPECIALLY when:

• Under time pressure (emergencies make guessing tempting)
• "Just one quick fix" seems obvious
• You've already tried multiple fixes
• Previous fix didn't work
• You don't fully understand the issue

Don't skip when:

• Issue seems simple (simple bugs have root causes too)
• You're in a hurry (rushing guarantees rework)
• Manager wants it fixed NOW (systematic is faster than thrashing)

The Four Phases

You MUST complete each phase before proceeding to the next.

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

1. Read Error Messages Carefully

   • Don't skip past errors or warnings
   • They often contain the exact solution
   • Read stack traces completely
   • Note line numbers, file paths, error codes

2. Reproduce Consistently

   • Can you trigger it reliably?
   • What are the exact steps?
   • Does it happen every time?
   • If not reproducible → gather more data, don't guess

3. Check Recent Changes

   • What changed that could cause this?
   • Git diff, recent commits
   • New dependencies, config changes
   • Environmental differences

4. Gather Evidence in Multi-Component Systems

   WHEN system has multiple components (CI → build → signing, API → service → database):

   BEFORE proposing fixes, add diagnostic instrumentation:

   Example (multi-layer system):

   This reveals: Which layer fails (secrets → workflow ✓, workflow → build ✗)

5. Trace Data Flow

   WHEN error is deep in call stack:

   See root-cause-tracing.md in this directory for the complete backward tracing technique.

   Quick version:

   • Where does bad value originate?
   • What called this with bad value?
   • Keep tracing up until you find the source
   • Fix at source, not at symptom

Phase 2: Pattern Analysis

Find the pattern before fixing:

1. Find Working Examples

   • Locate similar working code in same codebase
   • What works that's similar to what's broken?

2. Compare Against References

   • If implementing pattern, read reference implementation COMPLETELY
   • Don't skim - read every line
   • Understand the pattern fully before applying

3. Identify Differences

   • What's different between working and broken?
   • List every difference, however small
   • Don't assume "that can't matter"

4. Understand Dependencies

   • What other components does this need?
   • What settings, config, environment?
   • What assumptions does it make?

Phase 3: Hypothesis and Testing

Scientific method:

1. Form Single Hypothesis

   • State clearly: "I think X is the root cause because Y"
   • Write it down
   • Be specific, not vague

2. Test Minimally

   • Make the SMALLEST possible change to test hypothesis
   • One variable at a time
   • Don't fix multiple things at once

3. Verify Before Continuing

   • Did it work? Yes → Phase 4
   • Didn't work? Form NEW hypothesis
   • DON'T add more fixes on top

4. When You Don't Know

   • Say "I don't understand X"
   • Don't pretend to know
   • Ask for help
   • Research more

Phase 4: Implementation

Fix the root cause, not the symptom:

1. Create Failing Test Case

   • Simplest possible reproduction
   • Automated test if possible
   • One-off test script if no framework
   • MUST have before fixing
   • Use the superpowers:test-driven-development skill for writing proper failing tests

2. Implement Single Fix

   • Address the root cause identified
   • ONE change at a time
   • No "while I'm here" improvements
   • No bundled refactoring

3. Verify Fix

   • Test passes now?
   • No other tests broken?
   • Issue actually resolved?
   • Use the superpowers:verification-before-completion skill before claiming success

4. If Fix Doesn't Work

   • STOP
   • Count: How many fixes have you tried?
   • If < 3: Return to Phase 1, re-analyze with new information
   • If ≥ 3: STOP and question the architecture (step 5 below)
   • DON'T attempt Fix #4 without architectural discussion

5. If 3+ Fixes Failed: Question Architecture

   Pattern indicating architectural problem:

   • Each fix reveals new shared state/coupling/problem in different place
   • Fixes require "massive refactoring" to implement
   • Each fix creates new symptoms elsewhere

   STOP and question fundamentals:

   • Is this pattern fundamentally sound?
   • Are we "sticking with it through sheer inertia"?
   • Should we refactor architecture vs. continue fixing symptoms?

   Discuss with your human partner before attempting more fixes

   This is NOT a failed hypothesis - this is a wrong architecture.

Red Flags - STOP and Follow Process

If you catch yourself thinking:

• "Quick fix for now, investigate later"
• "Just try changing X and see if it works"
• "Add multiple changes, run tests"
• "Skip the test, I'll manually verify"
• "It's probably X, let me fix that"
• "I don't fully understand but this might work"
• "Pattern says X but I'll adapt it differently"
• "Here are the main problems: [lists fixes without investigation]"
• Proposing solutions before tracing data flow
• "One more fix attempt" (when already tried 2+)
• Each fix reveals new problem in different place

ALL of these mean: STOP. Return to Phase 1.

If 3+ fixes failed: Question the architecture (see Phase 4.5)

your human partner's Signals You're Doing It Wrong

Watch for these redirections:

• "Is that not happening?" - You assumed without verifying
• "Will it show us...?" - You should have added evidence gathering
• "Stop guessing" - You're proposing fixes without understanding
• "Ultra-think this" - Question fundamentals, not just symptoms
• "We're stuck?" (frustrated) - Your approach isn't working

When you see these: STOP. Return to Phase 1.

Common Rationalizations

Quick Reference

When Process Reveals "No Root Cause"

If systematic investigation reveals issue is truly environmental, timing-dependent, or external:

1. You've completed the process
2. Document what you investigated
3. Implement appropriate handling (retry, timeout, error message)
4. Add monitoring/logging for future investigation

But: 95% of "no root cause" cases are incomplete investigation.

Supporting Techniques

These techniques are part of systematic debugging and available in this directory:

• root-cause-tracing.md - Trace bugs backward through call stack to find original trigger
• defense-in-depth.md - Add validation at multiple layers after finding root cause
• condition-based-waiting.md - Replace arbitrary timeouts with condition polling

Base directory for this skill: /Users/alisha/.claude/skills/architecture-findings

Architecture findings

What this is for

After an investigation, there are two very different documents you could hand someone:

1. A lookup table — every claim pinned to a file and line so an engineer can jump straight to the code. Precise, but dense and exhausting to read.
2. A map of the territory — who the moving parts are, how they normally fit together, where the break is, and whose job it is to fix. This is the one that actually transfers understanding.

This skill produces the second kind. The reader should come away able to explain the system to someone else, not just able to find the line you're talking about.

The core rule

No code coordinates in the body. No file paths, no line numbers, no function or variable names, no code snippets. Those are the texture of the lookup table, and they're exactly what makes findings hard to read.

What you do name freely: the components, services, and systems by their real names (e.g. "the EU indexer", "entire-core", "the NATS bus"), the concepts ("ref events", "the repo-access token"), and the environment values that matter to the story only when named as a fact, not a citation ("the EU audience host is aws-eu-central-1.entire.io"). The test: would this detail help someone picture the system, or is it just a pointer for someone who wants to open a file? Keep the former, drop the latter.

You still did the rigorous, code-level investigation — this is just how you report it. If the user later asks "where exactly", give them the coordinates then. Don't pre-empt that with a wall of citations.

Structure

Adapt to the investigation, but this arc almost always works:

• Bottom line — 2–4 sentences. What's happening, why, and the one thing that matters most (e.g. "the fix isn't where you'd expect — it's upstream"). Someone who reads only this should get the headline right.
• The players — introduce each component in one line: what it is and what it's responsible for. This is the cast list; everything after refers back to it.
• The normal flow — how it works when it works. This is the reference the reader measures the break against. A simple arrow-chain diagram earns its place here (see below).
• Why it breaks — the failure, told as a story against that normal flow. Show the point where reality diverges from the happy path.
• The structural gap (when there is one) — the deeper "why can't we just fix it here" — the missing capability or wrong assumption underneath the symptom. This is often the most valuable section: it's what stops the reader proposing the naive fix.
• Where the fix belongs — which system owns it and why, what the options are, and explicitly what the wrong fix is if there's a tempting one.
• How other cases differ (when relevant) — the comparison that proves it's structural, not a one-off (other regions, other tenants, the working vs. broken side).

Drop sections that don't apply. A small investigation might be just bottom line + why it breaks + where the fix belongs.

Flow diagrams

Simple ASCII arrow chains are encouraged where a flow clarifies the story — they carry sequence better than a paragraph. Keep them component-level, never code-level. For example:

Then a second chain showing where the broken path diverges is often the clearest way to show a failure. Label them ("normal flow" / "what EU does"). Don't force a diagram where prose is already clear.

Voice

Write for a smart colleague who doesn't live in this code. Explain the why behind each mechanism, not just the what — "the STS refuses because that repo isn't an EU repo; that refusal is the residency guard doing its job" teaches more than "the STS returns an error". Prefer plain language over jargon, and when a term is load-bearing, define it once in passing. Keep it tight — this is a briefing, not an essay.

What to avoid

• File paths, line numbers, symbol names, code blocks (other than the component-level flow diagrams above).
• Turning "the players" into an inventory of every file touched.
• Hedging everything. You investigated; state what you found plainly, and flag genuine open questions as open questions.
• Burying the headline. The bottom line goes first.

Base directory for this skill: /Users/alisha/.claude/skills/rubber-duck

Rubber Duck

The user is looking at something dense — usually a long agent response or a findings dump — and wants to understand it, not act on it. Your whole job is to be the clear, patient explainer and then a sounding board for their questions. Think out loud with them, in plain language.

The one job

Turn the wall of text into something a smart person with no context can follow in under a minute, then answer whatever they ask next — still briefly.

Hard rules (do not break these)

• Do NOT write a plan, and do NOT enter plan mode. No ExitPlanMode, no writing-plans/brainstorming skills, no "here's how we'd fix it" roadmaps.
• Do NOT change code, run builds, or edit files. This is understanding only.
• Do NOT make a todo list. It's a conversation, not a task.
• Stay read-only. Reading a file or scrolling the text to explain it is fine. Anything that does something is not.
• Be concise — this is the point of the skill. You are the antidote to the wall of text, so don't produce another one. Lead with the answer. Short sentences. No preamble, no "great question", no restating the question back.
• Plain language over jargon. No file paths, line numbers, symbol names, or code snippets unless the user asks for them. Names of systems/people are fine; citations are not. (This is the same spirit as the architecture-findings skill — the story, not the lookup table.)

First explanation — the format

Keep it to roughly this, and stop:

1. One-line TL;DR. The single most important thing, first.
2. 3–5 short bullets covering: what's actually going on, why it matters, and (if relevant) what's broken or being decided. One idea per bullet.
3. One line on "so what" — the upshot, or the decision in front of them.

If the source genuinely has more than fits, say "there's more detail under X if you want it" and let them pull it — don't push it.

Use an analogy when it makes a hard idea click. Skip it when it doesn't.

The follow-up loop

After the first explanation, they'll ask things. For each:

• Answer the specific question and nothing more. One concept at a time.
• Stay just as concise — don't let answers creep back into walls of text.
• It's fine to say "not sure / the text doesn't say" rather than guess.
• If a question needs you to look something up to answer honestly, look (read only), then answer plainly.

Keep going as long as they're asking. You're the duck — they're thinking out loud and you're helping them see it.

When they're ready to act

The moment the user shifts from "help me understand" to "okay let's fix/build/ plan this," rubber-duck mode is over. Don't quietly start doing it inside this mode. Say something like: "That's action territory — want me to pick up that work?" and let them start the real task (a plan, a dispatch, an edit) as its own thing. Your job here ends at understanding.

does this pr fix it? https://github.com/entireio/cli/pull/2639

okay lets fix it and is there a way to add a test to catch when cli changes breaks dispatch or search commands?