| name | debugging-protocol |
| description | Structured debugging: hypothesis generation, validation, root cause analysis. For complex bugs, flaky tests, intermittent failures. |
Debugging Protocol
Rigorous framework: beyond ad-hoc troubleshooting to structured hypothesis → validation.
Workflow
1. Initialize
Copy template assets/debugging-session-template.md → docs/debugging/{issue}-{YYYY-MM-DD}-{HHmm}.md
2. Define Problem
- Symptom: observable behavior vs expected
- Scope: which components involved
3. Hypotheses
List distinct, testable hypotheses. Avoid vague guesses. Differentiate layers (frontend vs backend). Example: "race condition in UI state" vs "DB schema misconfiguration."
4. Validation Tasks
Per hypothesis:
- Objective: prove/disprove what
- Steps: precise, reproducible
- Code pattern: exact command/query/script
- Success criteria: what output confirms hypothesis
5. Execute & Document
Per task: status (✅ VALIDATED / ❌ FAILED / ⚠️ INCONCLUSIVE), findings (evidence), conclusion.
6. Root Cause
Synthesize: primary root cause, confidence level, proposed fixes.
Best Practices
- Be specific ("grep 'Error 500' in
/var/log/nginx/access.log" not "check logs")
- Isolate variables: one change at a time
- Validate assumptions first (config, versions)
- Preserve evidence (trace IDs, timestamps, repro scripts)
Language Modules
Load from languages/ for language-specific tools, hypothesis categories, validation strategies:
| Module | Runtime |
|---|
| Rust | cargo, rustc, tokio |
| Frontend | Vue 3, React, browser, Vite |
Compliance
- Error Handling @.gemini/rules/error-handling-principles.md
- Logging — load
logging-and-observability-principles skill
- Testing Strategy @.gemini/rules/testing-strategy.md (regression test for fix)
