A disciplined, multi-phase diagnosis loop designed for tracing hard bugs and performance regressions through structured reproduction and feedback loops.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install mp-diagnose
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install mp-diagnose using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is diagnose?
The diagnose skill provides a rigorous framework for troubleshooting complex technical anomalies, shifting debugging from guesswork to a structured engineering discipline. By prioritizing the creation of an automated, deterministic feedback loop, it ensures that developers and AI agents can isolate root causes efficiently rather than staring blindly at code.
This workflow navigates through feedback creation, reproduction confirmation, multi-hypothesis ranking, precision instrumentation, regression testing, and post-mortem cleanups. It is optimized to raise the reproduction rate of non-deterministic bugs, establishing an execution path where software errors are predictably captured, analyzed, and permanently resolved.
diagnose Use Cases
- Debugging Hard-to-Reproduce Bugs: Systematically increasing the reproduction rate of flaky or non-deterministic software glitches.
- Performance Regression Isolation: Measuring, bisecting, and diagnosing sudden speed drops or resource bottlenecks using precise profiling baselines.
- Root Cause Analysis (RCA): Formulating and validating multiple falsifiable hypotheses to discover why a system failed under specific conditions.
- Regression Test Verification: Locking down bugs by establishing correct test seams and verifying fixes before merging code changes.
How diagnose Works
- Build a Feedback Loop: Construct a fast, deterministic pass/fail signal (such as a failing test, curl script, or headless browser loop) to capture the bug instantly.
- Reproduce: Run the loop to confirm that the exact failure mode matches the user's description and record its unique symptoms.
- Hypothesise: Generate 3–5 ranked, falsifiable predictions regarding the root cause and present them to the user for early validation.
- Instrument: Target specific boundaries by inserting unique tagged logs (e.g.,
[DEBUG-a4f2]) or utilizing interactive debuggers to test the active hypotheses. - Fix & Regression Test: Establish a correct testing seam, turn the minimized reproduction script into a failing test, apply the permanent fix, and ensure the test passes.
- Cleanup & Post-Mortem: Strip all temporary debug code, delete throwaway harnesses, document the correct hypothesis, and evaluate architectural improvements.
diagnose Setup
To initiate the diagnostic routine within Openclaw Skills, invoke the tool inside your repository execution environment.
Ensure that relevant project domain glossaries and Architectural Decision Records (ADRs) are readily available in your current working directory to assist the agent in understanding contextual boundaries.
# Trigger the debugging and diagnostic agent flow
openclaw run diagnose --target="bug-description-or-issue-id"
# Grep and clean up temporary tagged instrumentation when complete
grep -rn "[DEBUG-" ./
diagnose Data Schema & Taxonomy
The diagnose skill organizes its troubleshooting lifecycle through the following artifacts and structures:
| Phase Component | Artifact / Strategy Type | Description |
|---|---|---|
| Feedback Seams | Test Scripts / Mocks | Unit, integration, e2e, Playwright/Puppeteer scripts, or throwaway harnesses used to expose the error path. |
| Hypothesis Format | Falsifiable String | Formatted explicitly as: "If |
| Trace Elements | Unique Tagged Logs | Temporary logging structures injected across codebase branches utilizing a unified grep-able prefix like [DEBUG-...]. |
| Baseline Capture | Timing Harness / Profiler Maps | High-resolution timestamps (performance.now()), query execution plans, or profiler states to track performance metrics. |
diagnose Advanced Features
- Non-Deterministic Flake Raising: Loops triggers up to 100x, adds concurrent system stress, injects strategic sleep statements, and narrows timing windows to raise a 1% flake rate into a debuggable 50%+ threshold.
- Bisection Harness Automation: Integrates cleanly with automated execution paths like
git bisect runby determining states across distinct codebase versions or historical datasets. - Human-in-the-Loop (HITL) Fallbacks: Drops back to interactive user execution using templates like
scripts/hitl-loop.template.shwhen an environment requires physical user interface interactions. - Cross-Skill Architecture Handoff: Feeds architectural system flaws directly into the
/improve-codebase-architectureskill when poor test isolation or tight coupling prevents proper seam injection.
SKILL.md
Loading
Related Openclaw Skills
Prototype Skill
A dedicated AI agent skill for building quick, throwaway prototypes to validate architectural logic or UI designs before committing to production code.
TDD
A systematic, test-driven development workflow designed to guide AI agents through precise, vertical red-green-refactor loops.
Grill-Me
An aggressive, investigative AI-driven interviewing framework designed to stress-test your system architectures, technical designs, and plans until true alignment is achieved.
Database Schema Designer
An expert database modeling skill that architecturally transforms business requirements into production-ready schemas, ER diagrams, indexing strategies, and optimized DDL definitions.
Code Review and Quality Agent Skill
A multi-dimensional code quality gate and security audit skill that validates correctness, architecture, performance, and AI agent integrity before merge or deployment.
AI Video Factory
An automated short-video generation skill that transforms a single topic prompt into a complete, high-quality video ready for multi-platform distribution.
Featured*
