[autoresearch] baseline: system prompt quality tests (5/5 passing)

.agents/skills/debugging-protocol/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: debugging-protocol
+description: Comprehensive protocol for validating root causes of software issues. Use when you need to systematically debug a complex bug, flaky test, or unknown system behavior by forming hypotheses and validating them with specific tasks.
+---
+
+# Debugging Protocol
+
+## Overview
+
+This skill provides a rigorous framework for debugging complex software issues. It moves beyond ad-hoc troubleshooting to a structured process of hypothesis generation and validation.
+
+Use this skill to:
+1.  Formalize a debugging session.
+2.  Systematically eliminate potential root causes.
+3.  Document findings for future reference or team communication.
+
+## Protocol Workflow
+
+To run a structured debugging session, follow these steps:
+
+### 1. Initialize the Session
+Create a new debugging document using the provided template. This serves as the "source of truth" for the investigation.
+
+**Template location:** `assets/debugging-session-template.md`
+
+**Save to:** `docs/debugging/{issue-name}-{YYYY-MM-DD}-{HHmm}.md`
+
+1. Create `docs/debugging/` if it doesn't exist
+2. Copy the template and fill in the issue details
+3. This makes the session accessible from other conversations and agents (e.g., when handing off to a `/quick-fix` or `/orchestrator` workflow)
+
+### 2. Define the Problem
+Clearly articulate the **System Context** and **Problem Statement**.
+*   **Symptom**: What is the observable behavior? How does it differ from expected behavior?
+*   **Scope**: Which components are involved?
+
+### 3. Formulate Hypotheses
+List distinct, testable hypotheses.
+*   Avoid vague guesses.
+*   Differentiate between layers (e.g., "Frontend Hypothesis" vs "Backend Hypothesis").
+*   Example: "Race condition in UI state update" vs "Database schema misconfiguration".
+
+### 4. Design Validation Tasks
+For each hypothesis, design a specific validation task.
+*   **Objective**: What are you trying to prove or disprove?
+*   **Steps**: Precise, reproducible actions.
+*   **Code Pattern**: Provide the exact code or command to run (e.g., a specific SQL query, a Python script using the client library, a `curl` command).
+*   **Success Criteria**: Explicitly state what output confirms the hypothesis.
+
+### 5. Execute and Document
+Run the tasks in order. For each task, record:
+*   **Status**: ✅ VALIDATED, ❌ FAILED, or ⚠️ INCONCLUSIVE.
+*   **Findings**: Key observations and raw evidence (logs, screenshots).
+*   **Conclusion**: Does this support or refute the hypothesis?
+
+### 6. Determine Root Cause
+Synthesize the findings into a **Root Cause Analysis**.
+*   Identify the Primary Root Cause.
+*   Assign a Confidence Level.
+*   Propose specific fixes.
+
+## Best Practices
+
+*   **Be Specific**: Don't just say "check the logs." Say "grep for 'Error 500' in `/var/log/nginx/access.log`".
+*   **Isolate Variables**: Change one thing at a time.
+*   **Validate Assumptions**: Verify configuration and versions first (e.g., "Task 1: Validate Current Schema").
+*   **Preserve Evidence**: Keep the specific trace IDs, log timestamps, or reproduction scripts.
+
+## Language-Specific Modules
+
+The `languages/` directory contains **modular, language-specific debugging guides**. When debugging a project, load the relevant language module to augment this protocol with language-specific tools, hypothesis categories, and validation strategies.
+
+**Convention:** Each module is a standalone markdown file at `languages/{language}.md`.
+
+**How to use:**
+1. Identify the primary language of the codebase being debugged
+2. Load the corresponding module from `languages/`
+3. Integrate its toolchain, hypothesis categories, and validation tasks into your debugging session
+
+**Available modules:**
+
+| Module | Languages/Runtimes |
+|---|---|
+| [Rust](languages/rust.md) | Rust (cargo, rustc, tokio) |
+| [Frontend](languages/frontend.md) | Vue 3, React, browser, Vite |
+
+> **Contributing new modules:** To add support for a new language, create `languages/{language}.md` following the structure of existing modules. Each module should include: a toolchain reference table, language-specific hypothesis categories, validation task patterns, and an error-type-to-first-action quick reference.
+
+## Rule Compliance
+When debugging, verify against:
+- Error Handling Principles @error-handling-principles.md (proper error propagation)
+- Logging and Observability Principles @logging-and-observability-principles.md (structured logging for diagnostics)
+- Testing Strategy @testing-strategy.md (regression test for the fix)