# Debug

Debug issues in the MCP Gateway Registry using first-principles thinking.

- Repository: https://github.com/agentic-community/mcp-gateway-registry (1032 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add agentic-community/mcp-gateway-registry --skill debug -g -a claude-code -y`
Codex: `npx skills add agentic-community/mcp-gateway-registry --skill debug -g -a codex -y`
Cursor: `npx skills add agentic-community/mcp-gateway-registry --skill debug -g -a cursor -y`
Gemini CLI: `npx skills add agentic-community/mcp-gateway-registry --skill debug -g -a gemini-cli -y`

## Description

Debug issues in the MCP Gateway Registry using first-principles thinking. Invoke when something is broken, timing out, returning errors, or behaving unexpectedly. Forces structured root-cause analysis before any code change is proposed.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Debug Skill

Use this skill when debugging any issue in the MCP Gateway Registry: timeouts, 5xx errors, UI failures, broken flows, unexpected behavior. Invoke this skill proactively whenever normal debugging is failing or going in circles, or use it from the start for any non-trivial issue. We are testing whether this approach should be the default for all debugging.

## Expert Personas

Before starting, announce that you are consulting the following expert panel. Each persona challenges assumptions and contributes their domain expertise:

- **SRE/Infrastructure Engineer** - Thinks about: single-worker bottlenecks, event loop blocking, connection pooling, DNS resolution, proxy timeouts, container resource limits, startup ordering.
- **Frontend/Browser Security Engineer** - Thinks about: same-origin vs cross-origin, preflight behavior, cookie scope, session validity after restarts, browser caching of error responses, service worker interception.
- **Backend/Python Engineer** - Thinks about: asyncio event loop blocking, synchronous HTTP calls on async workers, Pydantic model_dump dropping extra fields, DB write ordering, exception swallowing in try/except.
- **Senior Staff Engineer (Skeptic)** - Questions EVERY theory before implementation. Asks: "If that were true, why does X work?" and "Was this working before our change?" Forces the team to prove hypotheses before writing code.

State which persona is "speaking" when presenting a theory or counter-argument. The Skeptic must challenge every theory before any code change is proposed.

## First Principles Debugging

### Step 1: Reproduce and observe (do NOT theorize yet)

- What exact error does the user see? (HTTP status, error message, timing)
- What was the user doing? (which page, which action, which persona)
- Does the same operation work via curl from the command line?
- If curl works but browser doesn't: the difference is timing or session, NOT the backend logic.

The rest: https://github.com/agentic-community/mcp-gateway-registry/blob/HEAD/.claude/skills/debug/SKILL.md