convez.ai
SkillDevOps & InfraestruturaIntermediário
webster-yuan

Forensic Bisect — Depuração por Busca Binária

webster-yuan/forensic-bisect

Depuração orientada por fenômeno: observe, bisecte, confirme; código é o último recurso

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill de depuração estruturada que inverte a abordagem tradicional: em vez de ler código primeiro, observa o fenômeno, faz busca binária nas fronteiras do sistema, e só consulta código como último recurso. Implementa checklist de bloqueio e detecção de múltiplas causas raiz com fence logging.

Instalação

$npx convez-ai webster-yuan/forensic-bisect

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Depurar erros de integração entre serviços sem explorar imediatamente o código-fonte
  • Identificar problemas em camadas de rede/infraestrutura antes de assumir bugs aplicacionais
  • Resolver problemas intermitentes com estratégia de fence logging para não-reproduzíveis
  • Otimizar tempo de depuração em sistemas distribuídos com múltiplas possíveis causas raiz

Veredito

Metodologia sólida e pragmática que codifica a prática de engenheiros experientes. Especialmente valiosa para sistemas distribuídos e problemas intermitentes; pode ser overhead em cenários óbvios (erro do compilador, config simples). Requer disciplina do usuário para aplicar o checklist de bloqueio.

README

A tradução para o português deste README ainda está na fila.

forensic-bisect — Phenomenon-Driven Binary-Search Debugging

A Claude Code / Hermes skill that replaces "read error → search code → read files → fix" with "observe phenomenon → bisect system boundaries → drill down → code is last resort."

License: MIT

中文文档


What's New in v0.1.0

FeatureWhat it does
⛔ STOP hard-block4-item checklist before any code-reading tool is allowed
Layer 1.5 multi-root-causeDetects when binary search fails (3 trigger signals → fence logging)
Skip guide5 scenarios where forensic-bisect adds overhead, not value
Frontend/client bisect6 frontend-specific bisect patterns in Layer 1 table
Anti-patterns reorderedBy real frequency — "guessing root cause" now #1
⏱️ Time budgetLayer 0-1 must complete in 3 minutes
Cannot-reproduceSentinel logging strategy for intermittent bugs

The Problem

AI coding agents default to code-first debugging: see an error → search_files → read_file → guess fixes.

This is not how experienced developers debug. They start from the phenomenon, use binary search at system boundaries, and only look at code as a last resort.

The Solution

A structured debugging methodology with hard guardrails:

⛔ STOP: 4-item checklist before touching code
    ↓
Layer 0: Confirm the phenomenon
    ↓
Layer 1: Binary-search at system boundaries (curl/log/ping, NOT code)
    ↓
Layer 1.5: Multi-root-cause detection (fence logging when bisect fails)
    ↓
Layer 2: Drill down within the identified layer
    ↓
Layer 3: Code as last resort

When to Skip forensic-bisect

ScenarioWhy skipDo instead
Compiler tells you file + lineBisect is overheadFix, verify compile
User says "config X is wrong"Trust the userVerify → fix → verify
One-line fix, immediately verifiableFixing is fasterFix → verify; revert if wrong
Known dependency/version issueNot a code bugUpgrade/downgrade

Rule of thumb: if the path from symptom to root cause is ≤ 2 steps, skip forensic-bisect.


Core Anti-Patterns (Ordered by Frequency)

#Anti-PatternCorrect Approach
1"I guess it's probably X" — hypothesizing before Layer 1Guess ≠ diagnosis. curl/log/ping first
2Immediately search_files / read_fileConfirm Layer 0. Write down exact error first
3Changed ≥2 files, still not fixedYou skipped bisect. Stop. Go back to Layer 1
4Changed multiple things at onceChange A → test. Change B → test. Never A+B together
5Skipping diagnostic logs, going straight to codeOne log line to validate your hypothesis first

Real Example: 405 Error (3 min, 0 lines of code)

# Layer 1: MCP server vs auth page
curl MCP auth_login → 200 ✅ → MCP works, problem on admin.wandox.com

# Layer 1: nginx vs application
curl POST admin.wandox.com/api/v1/* → 405
curl POST ai-api.wandox.com/api/v1/* → 422 ✅
→ nginx blocks POST /api/v1/* on admin server

# Conclusion: nginx config. Done.

Real Example: Electron IPC 3-root-cause (multi-root-cause mode)

# Symptom: task status update sometimes doesn't refresh (30% repro rate)

# Layer 1 bisect → contradictory result:
#   Main process emits ✅, renderer sometimes receives ❓

# Enter Layer 1.5 → fence logging at 3 boundaries:
#   [MAIN] emit task-update id=1 ✅ → [BRIDGE] forward ✅ → [COMPONENT] received ✅
#   [MAIN] emit task-update id=2 ✅ → [BRIDGE] forward ❌         (bridge timing)
#   [MAIN] emit task-update id=3 ✅ → [BRIDGE] forward ✅ → [COMPONENT] received ❌ (unmount)
#   [MAIN] emit task-update id=4 ❌                                (pool deadlock)

# → 3 independent root causes found in one log run

Installation

git clone https://github.com/webster-yuan/forensic-bisect.git
cd forensic-bisect
bash install.sh        # macOS / Linux / WSL
# or
.\install.ps1          # Windows PowerShell

Installs to ~/.claude/skills/forensic-bisect/ (Claude Code) or ~/.hermes/skills/forensic-bisect/ (Hermes).

Relationship with systematic-debugging

  • forensic-bisect: find WHERE the problem is (system-level, binary search)
  • systematic-debugging: fix WHAT the problem is (code-level, root cause)

License

MIT

Ver o original no GitHub

Bom para

Relacionados