Use when encountering any bug, test failure, or unexpected behavior - before proposing fixes
From mbscodenpx claudepluginhub mbstools/mbscodeThis skill uses the workspace's default tool permissions.
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.
Guides slash command development for Claude Code: structure, YAML frontmatter, dynamic arguments, bash execution, user interactions, organization, and best practices.
Fix bugs through evidence, not guesswork.
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
Phase 0 applies to ALL unexpected failures — broken builds, failed installs, CI errors, environment issues — not just code bugs. Any non-code operational failure triggers this skill starting at Phase 0.
Before committing to the full 5-phase process, check these common causes first — they resolve ~30% of bugs in under a minute:
If one of these fixes it → verify with tests → done. If not → proceed to Phase 1.
You MUST complete each phase before proceeding to the next.
BEFORE attempting ANY fix:
Read Error Messages Carefully
Reproduce Consistently
Check Recent Changes
git log --oneline -20 — what changed recently?git blame <file> — who changed the failing code and when?Gather Evidence in Multi-Component Systems
When the system has multiple layers (CI → build → deploy, API → service → database):
Add diagnostic instrumentation at each boundary BEFORE fixing:
For EACH component boundary:
- Log what data enters the component
- Log what data exits the component
- Verify environment/config propagation
- Check state at each layer
Run once → evidence shows WHERE it breaks
THEN investigate that specific component
WARNING — Instrumentation safety rules:
"Auth: [PRESENT]" not the actual token)Example (3-layer system, adapt to your shell):
# Layer 1: API endpoint
log "=== Request received: $METHOD $PATH ==="
log "=== Auth header: [PRESENT/ABSENT] ==="
# Layer 2: Service layer
log "=== Service input: $INPUT ==="
log "=== Database query: $QUERY ==="
# Layer 3: Database
log "=== Query result rows: $ROW_COUNT ==="
This reveals which layer fails (API → service ✓, service → database ✗).
Trace Data Flow
If you've tried 3 or more fixes and the bug persists:
This is NOT a failed hypothesis — this is a wrong architecture.
Pattern indicating architectural problem:
STOP and question fundamentals:
Escalate to the user. Do NOT attempt fix #4 without discussing the architecture. Autonomous default: If running non-interactively, revert to last clean state, document all attempts and the architectural issue in SESSION.md and LESSONS_LEARNED.md, mark the bug as BLOCKED, and move to the next task.
| Anti-Pattern | Instead |
|---|---|
| "Quick fix for now, investigate later" | Investigate NOW. Quick fixes become permanent. |
| "Just try changing X and see" | Form a hypothesis first |
| "I think it might be..." without evidence | Show the evidence |
| "One more fix attempt" (after 2+ failures) | 3 strikes = architecture problem. Escalate. |
| Fixing symptoms (suppress the error) | Find and fix the root cause |
| Multiple changes at once | One variable at a time |
| "It works on my machine" | Check environment differences |
| Assuming the fix works | Run reproduction steps again |
| Skipping regression test | If it broke once, it will break again |
If systematic investigation shows the issue is truly environmental, timing-dependent, or external:
But: 95% of "no root cause" cases are incomplete investigation.
Use the right tool for the situation:
After fix verified: Invoke mbscode:verification-before-completion for full test suite confirmation.
If bug reveals design issue: Invoke mbscode:brainstorming to redesign the affected component. Note: this creates a new design cycle — the original debugging task is complete once the fix is verified.