wiring doctor
wiring doctor
Diagnoses and prescribes wiring in Claude Code systems. Reads the real wiring state, maps it against 6 invariants (structural, economic, reachability, propagation, boundary, semantic), scores fragility of each wire, and prescribes surgical corrections with explicit decision-tree reasoning and forward simulation.
Wiring Doctor
Diagnose and fix invisible wiring problems in Claude Code systems.
The Problem
You wrote a rule. Claude ignored it. You added a hook. It never fired. You configured a sub-agent to know the context — but it keeps asking questions you already answered.
The instructions are there. The files exist. And yet the behavior is wrong.
Welcome to broken wiring. Claude Code systems are circulatory systems — five mechanisms (CLAUDE.md, rules, hooks, skills, agents) each carrying different cargo through different channels. When behavior breaks, it's rarely a Claude problem. It's a wiring problem: the wrong instruction in the wrong mechanism, a hook event spelled wrong, a boundary collision between two rules that are individually correct but collectively contradictory.
The problem isn't visible from outside. You can't see the wiring. You can only see the symptoms.
Wiring Doctor reads the invisible layer between intention and behavior — and tells you exactly what's wrong, in which file, and how to fix it.
What Wiring Doctor Does
Wiring Doctor reads your system's actual wiring state, maps it against 5 invariants of correct wiring, and delivers surgical prescriptions — not vague suggestions.
4 phases, 5 invariants, zero guessing:
| Phase | What happens |
|---|---|
| Phase 0 — Intenção | "Where does it hurt?" — maps symptom to suspect mechanism |
| Phase 1 — Raio-X | Reads real files, builds the actual wiring graph |
| Phase 2 — Diagnóstico | Tests 5 invariants against real state — violations named exactly |
| Phase 3 — Prescrição | Decision-tree reasoning + simulation check for every fix |
Is This For Me?
✅ You have a Claude Code project with CLAUDE.md, rules, hooks, or agents ✅ You've experienced unexpected Claude behavior you can't explain ✅ You've built a system that's grown complex enough to have invisible interactions ✅ You want to audit before shipping a product or system
❌ You're debugging code bugs (use /aegis for security issues) ❌ You're building a project from scratch with no existing wiring ❌ You want generic best practices (Wiring Doctor diagnoses YOUR system specifically)
Quick Start
/wiring-doctor
Wiring Doctor will ask one question first: "Where does it hurt?"
Then it reads your system, tests the invariants, and delivers a prioritized list of surgical fixes with explicit reasoning for each.
The 5 Invariants
Wiring Doctor tests every system against these 5 invariants:
| Invariant | What it checks |
|---|---|
| A1 — Especificidade | Is every behavior in the correct mechanism? |
| A2 — Custo Declarado | Is ambient budget declared and justified? |
| A3 — Alcançabilidade | Does every wire have a verifiable activation path? |
| A4 — Propagação Explícita | In multi-agent systems, is context passed explicitly? |
| A5 — Bordas | Do mechanism boundaries have hidden conflicts? |
How It Works
Claude Code wiring is a circulatory system. CLAUDE.md is the arteries — always flowing, high cost, global. Rules are veins — conditional, path-scoped. Hooks are neural reflexes — deterministic, event-triggered, zero ambient cost. Skills are voluntary muscles — on-demand, invoked. Agents are specialist organs — isolated context, spawned.
Every mechanism has a non-overlapping responsibility domain. When behavior breaks, it's because a wire is in the wrong channel, or the channel is misconfigured, or two channels are claiming the same territory.
Wiring Doctor doesn't guess. It tests your system against 5 invariants (A1–A5) that define correct wiring — then cites which invariant is violated, in which file, and why the prescription is the correct fix (not a preference). Every prescription runs a simulation check: does the fix create a new violation?
The 4-phase protocol mirrors clinical medicine:
- Phase 0 (Intenção): "Where does it hurt?" — declare the symptom before reading any file
- Phase 1 (Raio-X): Read the real wiring state — not assumed state
- Phase 2 (Diagnóstico): Test 5 invariants against real state
- Phase 3 (Prescrição): Decision-tree reasoning + simulation check for every fix
The authority comes from the invariants. "This could be better" is an opinion. "This violates A3 because the event name 'PreTooluse' is not in the valid event registry" is a diagnosis.
Requirements
- Claude Code ≥ 1.0.0
- Any Claude Code project with at least one of: CLAUDE.md, rules/, hooks, skills, agents
Compatibility
Works on any Claude Code project. No dependencies. No external API calls. Reads only local files in your project.
Language
Source: Portuguese (pt-BR) · Adapts to your language at runtime
License
Proprietary — © l0z4n0
Built with MyClaude Studio Engine
<!-- PT-BR --> <details> <summary>Português</summary>
O Problema
Você escreveu uma regra. O Claude ignorou. Configurou um hook. Ele nunca disparou. Criou um sub-agente com contexto — mas ele continua perguntando o que você já respondeu.
As instruções estão lá. Os arquivos existem. Mesmo assim, o comportamento está errado.
Bem-vindo ao wiring quebrado. Sistemas Claude Code são sistemas circulatórios — cinco mecanismos (CLAUDE.md, rules, hooks, skills, agents) carregando cargas diferentes por canais diferentes. Quando o comportamento quebra, raramente é problema do Claude. É problema de wiring: instrução certa no mecanismo errado, evento de hook com erro de maiúscula, colisão de bordas entre duas regras individualmente corretas mas coletivamente contraditórias.
O problema é invisível por fora. Você não consegue ver o wiring. Só consegue ver os sintomas.
O Wiring Doctor lê a camada invisível entre intenção e comportamento — e diz exatamente o que está errado, em qual arquivo, e como corrigir.
O Que o Wiring Doctor Faz
O Wiring Doctor lê o estado real do seu sistema, mapeia contra 5 invariantes de wiring correto, e entrega prescrições cirúrgicas — não sugestões vagas.
4 fases, 5 invariantes, zero achismo:
| Fase | O que acontece |
|---|---|
| Fase 0 — Intenção | "Onde dói?" — mapeia sintoma para mecanismo suspeito |
| Fase 1 — Raio-X | Lê arquivos reais, constrói o grafo de wiring atual |
| Fase 2 — Diagnóstico | Testa 5 invariantes contra o estado real |
| Fase 3 — Prescrição | Raciocínio por árvore de decisão + simulação para cada correção |
El Problema
Escribiste una regla. Claude la ignoró. Configuraste un hook. Nunca se ejecutó. Creaste un sub-agente con contexto — pero sigue preguntando lo que ya respondiste.
Las instrucciones están ahí. Los archivos existen. Y sin embargo, el comportamiento es incorrecto.
Bienvenido al wiring roto. Los sistemas Claude Code son sistemas circulatorios — cinco mecanismos (CLAUDE.md, rules, hooks, skills, agents) transportando distintas cargas por distintos canales. Cuando el comportamiento falla, rara vez es un problema de Claude. Es un problema de wiring: la instrucción correcta en el mecanismo equivocado, un evento de hook mal escrito, una colisión de límites entre dos reglas individualmente correctas pero colectivamente contradictorias.
El problema es invisible desde fuera. No puedes ver el wiring. Solo puedes ver los síntomas.
Wiring Doctor lee la capa invisible entre intención y comportamiento — y te dice exactamente qué está mal, en qué archivo, y cómo corregirlo.
Qué Hace Wiring Doctor
Wiring Doctor lee el estado real de tu sistema, lo mapea contra 5 invariantes de wiring correcto, y entrega prescripciones quirúrgicas — no sugerencias vagas.
4 fases, 5 invariantes, cero suposiciones:
| Fase | Qué ocurre |
|---|---|
| Fase 0 — Intención | "¿Dónde duele?" — mapea el síntoma al mecanismo sospechoso |
| Fase 1 — Radiografía | Lee archivos reales, construye el grafo de wiring actual |
| Fase 2 — Diagnóstico | Prueba 5 invariantes contra el estado real |
| Fase 3 — Prescripción | Razonamiento por árbol de decisión + simulación para cada corrección |
<sub>Built with MyClaude Studio Engine</sub>
Reviews (0)
Loading reviews...
