xD4O/diagnostic-reasoning
skills/diagnostic-reasoning/SKILL.md
MANDATORY debugging protocol. You MUST invoke this skill when debugging complex issues, investigating failures, diagnosing intermittent problems, or performing root cause analysis. Do NOT start changing code before collecting observations. Do NOT guess at causes — generate 5 competing hypotheses and design a discriminating test. Invoke this BEFORE touching any code when something is broken.
$ install --global
skillsauthnpx skillsauth add xD4O/praxis diagnostic-reasoningInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 23, 2026, 6:25 PM222.4s1 file scanned
SKILL.md
- name:
- diagnostic-reasoning
- description:
- >
Diagnostic Reasoning Protocol
EXTREMELY_IMPORTANT: This is a MANDATORY protocol, not a suggestion. Follow every step. Do not skip steps. Do not combine steps. Do not summarize. Work through each gate in order.
Something is broken. Do NOT start changing code. Follow this protocol.
PHASE 1 — Observe precisely
Before forming any hypothesis, collect facts. Answer each:
- What exactly happened? (exact error, exact behavior, exact output)
- When did it start? (timestamp, deploy, config change, load change)
- How often? (every time, intermittent, under specific conditions)
- What changed recently? (deploys, config, dependencies, traffic patterns)
- What's the blast radius? (all users, some users, one endpoint, one region)
Do NOT proceed until you can state the problem in one precise sentence that another engineer could verify independently.
PHASE 2 — Generate competing hypotheses
Produce exactly 5 hypotheses. Not 1. Not 3. Five.
For each hypothesis, state:
- What it would explain
- What it would NOT explain (if anything in the observations contradicts it)
- Prior probability estimate (likely / possible / unlikely)
Order by: (explanatory power) × (prior probability), highest first.
Mandatory check: Is your #1 hypothesis the simplest explanation? Simple causes first: config error, permissions, missing dependency, wrong environment, typo. Check these before investigating race conditions, memory corruption, or kernel bugs.
PHASE 3 — Design a discriminating test
Do NOT test hypotheses one by one. Design a single observation that distinguishes between your top 3 hypotheses simultaneously.
Template: "If I observe [X], then hypothesis A is supported. If I observe [Y], then hypothesis B is supported. If I observe [Z], then hypothesis C is supported."
This is Strong Inference. One test, maximum information.
If no single test distinguishes all three, design the test that eliminates the most hypotheses regardless of outcome (maximum information gain).
PHASE 4 — Execute and update
Run the test. Observe the result.
- Which hypotheses are eliminated?
- Which are supported?
- Does the result suggest a NEW hypothesis not in your original list?
Update your hypothesis ranking. If the top hypothesis is now >80% likely, proceed to verification. If not, return to Phase 3 with the surviving hypotheses.
PHASE 5 — Root cause drilling
You found WHAT is broken. Now find WHY.
Ask "Why?" five times minimum:
- Why did [the immediate failure] happen?
- Why did [the cause from #1] happen?
- Why did [the cause from #2] happen?
- Why did [the cause from #3] happen?
- Why did [the cause from #4] happen?
Stop when you reach a systemic cause (process, tooling, policy) rather than an individual cause (person made a mistake). Fix the systemic cause.
PHASE 6 — Verify the fix
After applying the fix:
- Does the original symptom disappear?
- Does the discriminating test from Phase 3 now show healthy behavior?
- Are there related symptoms that should also be checked?
- What prevents this from recurring? (monitoring, test, guard, policy)
Red flags that this skill catches:
- "I think it might be..." — Generate 5 hypotheses, not 1 guess.
- Changing code before collecting observations — Observe first. Always.
- Testing hypotheses sequentially — Use Strong Inference to test simultaneously.
- "Fixed!" after patching the symptom — Did you drill to root cause?
- "Can't reproduce" — That's an observation, not a conclusion. What conditions differ? </HARD-GATE>
Superpowers handoff
After root cause is identified and fix is designed:
If Superpowers is installed → invoke Skill(superpowers:systematic-debugging) or
Skill(superpowers:test-driven-development) to implement the fix. Pass your ranked
hypotheses, discriminating test results, and root cause analysis. The fix should be
implemented via TDD: write a test that reproduces the root cause, verify it fails,
then fix. Do NOT write the fix inside this skill. PRAXIS diagnosed. Superpowers fixes.
If Superpowers is NOT installed → implement the fix yourself, following TDD principles where possible.
Related Skills
xD4O/using-praxis
development
VerifiedTrustedCommunity
MANDATORY — HIGHEST PRIORITY SKILL. You MUST invoke this skill (praxis) BEFORE invoking superpowers:brainstorming or ANY other skill when the task is non-trivial. This skill classifies the problem, selects reasoning frameworks, and runs threat analysis BEFORE brainstorming begins. Do NOT invoke superpowers:brainstorming first. Do NOT respond directly. Do NOT ask clarifying questions on your own. Invoke praxis FIRST, complete its gates, THEN hand off to superpowers:brainstorming. Non-trivial means: system design, feature planning, architecture decisions, debugging, security-sensitive code, trade-off evaluation, code review, or refactoring. Trivial means: fix a typo, rename a variable, answer a factual question, run a command.
9SKILL.mdUpdated Apr 23, 2026
xD4O/strategic-reasoning
development
VerifiedTrustedCommunity
MANDATORY strategic analysis. You MUST invoke this skill for business decisions, product strategy, competitive analysis, roadmap prioritization, or any decision about WHAT to build rather than HOW to build it. Do NOT skip SWOT analysis. Do NOT present strategy without measurable OKRs. Invoke when the problem is about direction, positioning, or priorities rather than implementation.
9SKILL.mdUpdated Apr 23, 2026
xD4O/security-reasoning
development
VerifiedTrustedCommunity
MANDATORY threat analysis. You MUST invoke this skill before writing or approving ANY code involving authentication, authorization, cryptography, input handling, payment processing, PII, secrets management, API endpoints, or trust boundaries. Do NOT write security-sensitive code without running STRIDE analysis first. Do NOT say you will add security later. Auth is a design decision, not a feature to bolt on.
9SKILL.mdUpdated Apr 23, 2026
xD4O/problem-classification
development
VerifiedTrustedCommunity
MANDATORY first step. You MUST invoke this skill before brainstorming, designing, or planning any non-trivial work. Do NOT start asking clarifying questions on your own — this skill's gates ARE the clarifying questions. Invoke when the user asks to build, design, plan, create, architect, or implement anything substantial. Do NOT skip this because the task seems straightforward. Straightforward-seeming tasks with wrong framing produce the most expensive failures.
9SKILL.mdUpdated Apr 23, 2026