# What Kind of Issues Does DeepSeek-Reasonix Address? A Complete Diagnostic Categories Guide

> Explore the eight diagnostic categories DeepSeek-Reasonix addresses: skill, command, hook, plugin, MCP, runtime, configuration, and security issues. Get a complete guide to its capabilities.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: deep-dive
- Published: 2026-08-14

---

**DeepSeek-Reasonix addresses eight major categories of issues through its capability-diagnostics subsystem: skill problems, command problems, hook problems, plugin problems, MCP (Multi-Channel Protocol) problems, runtime/host problems, configuration problems, and security-related problems.**

DeepSeek-Reasonix is an open-source AI engine that ships with a built-in *capability-diagnostics* subsystem designed to catch misconfigurations before they cause failures in production. When users ask "what kind of issues does DeepSeek-Reasonix address," they're typically looking to integrate the engine's diagnostic capabilities into their CI pipelines or troubleshooting workflows. This guide breaks down every issue category the engine detects, how the detection mechanism works, and how to automate issue remediation.

## Issue Categories Detected by DeepSeek-Reasonix

The diagnostic engine in [`docs/CAPABILITY_DIAGNOSTICS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/CAPABILITY_DIAGNOSTICS.md) defines eight distinct issue categories. Each category maps to specific subsystems and produces machine-readable issue codes for programmatic handling.

### Skill Problems

Skills are the core execution units in Reasonix. The diagnostics subsystem flags:

- `skill.shadowed` — duplicate skill names where one definition overrides another
- `skill.missing_description` — skills lacking required metadata
- `skill.disabled` — skills explicitly turned off in configuration

These issues are detected during static scanning of the `.reasonix/skills/` directory, where the engine validates TOML definitions against the skill schema.

### Command Problems

Commands define how users interact with skills. Issues include:

- `command.shadowed` — duplicate command names across skill boundaries
- `command.read_failed` — filesystem or permission errors when loading command files

The engine walks `.reasonix/commands/` and validates each file's structure, checking for malformed JSON or missing required fields.

### Hook Problems

Hooks attach behavior to command execution. Detected issues:

- `hook.invalid_matcher` — pattern syntax errors in hook activation rules
- `hook.missing_command` — hooks referencing non-existent commands
- `hook.malformed_settings` — invalid configuration in hook definitions

### Plugin Problems

Plugins extend engine functionality. The diagnostics catch:

- `plugin.missing_root` — plugin directories without expected entry points
- `plugin.invalid_manifest` — malformed [`plugin.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/plugin.toml) or missing required keys
- `plugin.compatibility` — version mismatches between plugin and engine core

### MCP (Multi-Channel Protocol) Problems

MCP servers enable external tool integration. This is the most complex category with seven distinct issue codes:

- `mcp.invalid_transport` — unsupported or malformed transport specifications (stdio, HTTP, WebSocket)
- `mcp.command_not_found` — referenced executable missing from PATH
- `mcp.missing_command` — MCP server definition lacking launch command
- `mcp.missing_url` — HTTP-based servers without required endpoint
- `mcp.start_failed` — server process exits during startup
- `mcp.no_tools` — server starts but advertises zero available tools
- `mcp.runtime_unavailable` — tool calls fail at runtime despite successful startup

These issues require **live probing** with the `--live` flag to fully validate.

### Runtime/Host Problems

When MCP servers fail to start or tool calls error out, the engine surfaces these through:

- Exit code 1 in `reasonix doctor capabilities` for hard failures
- Exit code 2 for partial degradation with recoverable issues

### Configuration Problems

Invalid TOML entries, unsupported values, and missing required fields are caught during initial config load. See the **Configuration** section in [`docs/SPEC.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/SPEC.md) for schema details.

### Security-Related Problems

Issues exploitable by untrusted actors—open ports, insecure defaults, privilege escalation vectors—are enumerated in [`SECURITY.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/SECURITY.md) and filtered through the diagnostics output with elevated severity.

## How DeepSeek-Reasonix Detects Issues

The detection pipeline runs in four deterministic stages:

**1. Static Scanning**

The engine recursively walks workspace directories (`.reasonix/skills`, `.reasonix/commands`, `.reasonix/hooks`, `.reasonix/plugins`) and parses each file against JSON schemas and TOML validators. Duplicate names and missing required keys are flagged without executing any code.

**2. MCP Probing**

With `--live`, Reasonix isolates each MCP server in a separate process, monitors startup, and validates tool availability. This catches runtime-only issues like `mcp.runtime_unavailable` that static analysis cannot detect.

**3. Aggregation**

Results merge into a single `issues[]` array with deterministic ordering—sorted by severity, then subsystem, then code—ensuring reproducible CI outputs.

**4. Reporting**

The `reasonix doctor capabilities` command produces human-readable tables or JSON output via `--json`.

## Using DeepSeek-Reasonix Diagnostics in Practice

### CLI Commands

```bash

# Human-readable diagnostic output

reasonix doctor capabilities

# Machine-readable JSON for automation

reasonix doctor capabilities --json > issues.json

# CI pipeline integration: fail on any error-severity issue

if reasonix doctor capabilities --json | jq '.summary.errors > 0' | grep -q true; then
    echo "Critical issues detected"
    exit 1
fi

```

### Parsing Diagnostics Programmatically

```go
// Example: Load and filter error-severity issues in Go
package main

import (
    "encoding/json"
    "fmt"
    "os"
)

type Issue struct {
    Severity    string `json:"severity"`
    Code        string `json:"code"`
    Subsystem   string `json:"subsystem"`
    Message     string `json:"message"`
    Remediation string `json:"remediation,omitempty"`
}

type Diagnostics struct {
    Summary struct {
        Errors   int `json:"errors"`
        Warnings int `json:"warnings"`
        Info     int `json:"info"`
    } `json:"summary"`
    Issues []Issue `json:"issues"`
}

func main() {
    data, err := os.ReadFile("issues.json")
    if err != nil {
        panic(err)
    }

    var d Diagnostics
    if err := json.Unmarshal(data, &d); err != nil {
        panic(err)
    }

    for _, issue := range d.Issues {
        if issue.Severity == "error" {
            fmt.Printf("ERROR [%s] %s: %s\n", issue.Subsystem, issue.Code, issue.Message)
            if issue.Remediation != "" {
                fmt.Printf("  → %s\n", issue.Remediation)
            }
        }
    }
}

```

## Issue Schema and Stable Codes

Every issue emitted by DeepSeek-Reasonix follows a structured JSON schema defined in [`docs/CAPABILITY_DIAGNOSTICS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/CAPABILITY_DIAGNOSTICS.md):

| Field | Type | Description |
|-------|------|-------------|
| `severity` | string | `error`, `warning`, or `info` |
| `code` | string | Stable identifier (e.g., `mcp.start_failed`) |
| `subsystem` | string | Origin category (skill, command, hook, plugin, mcp, runtime, config, security) |
| `message` | string | Human-readable description |
| `remediation` | string | Optional fix suggestion |

The complete list of stable issue codes is maintained at `docs/CAPABILITY_DIAGNOSTICS.md#stable-codes`. Codes are guaranteed not to change between minor versions, enabling reliable CI rule definitions.

## Key Source Files for Issue Detection

| File | Purpose |
|------|---------|
| [`docs/CAPABILITY_DIAGNOSTICS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/CAPABILITY_DIAGNOSTICS.md) | Diagnostic command specification, JSON schema, exit codes, stable issue codes |
| [`docs/SPEC.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/SPEC.md) | Architecture including MCP concurrency and delegation behavior |
| [`docs/SESSION_REFERENCE_ARCHITECTURE.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/SESSION_REFERENCE_ARCHITECTURE.md) | Real-world issue examples and surfacing patterns |
| [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md) | Core conventions including TODO/HACK markers for issue tracking |
| [`SECURITY.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/SECURITY.md) | Security issue enumeration and response procedures |

## Summary

- **DeepSeek-Reasonix addresses eight issue categories**: skills, commands, hooks, plugins, MCP, runtime/host, configuration, and security.
- **Detection combines static scanning and live probing**: use `--live` to validate MCP server startup and tool availability.
- **All issues emit structured JSON** with stable codes, enabling CI integration via `reasonix doctor capabilities --json`.
- **Exit codes signal severity**: 1 for errors, 2 for warnings in live mode, 0 for clean diagnostics.
- **Source authority lives in [`docs/CAPABILITY_DIAGNOSTICS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/CAPABILITY_DIAGNOSTICS.md)**: the definitive reference for issue schemas and stable codes.

## Frequently Asked Questions

### How do I fail my CI pipeline only on specific issue codes?

Filter the JSON output using `jq`. The stable codes in `docs/CAPABILITY_DIAGNOSTICS.md#stable-codes` let you define allowlists or blocklists. For example, block only `mcp.runtime_unavailable` while permitting `mcp.no_tools` during development.

### Can DeepSeek-Reasonix detect issues without starting MCP servers?

Yes. Static scanning requires no live services and catches schema violations, duplicates, and missing fields. Add `--live` only when you need to validate actual server startup and tool execution.

### What is the performance impact of running diagnostics on a large workspace?

Static scanning completes in milliseconds for typical workspaces. Live probing adds latency proportional to MCP server count and startup time—each server starts in isolation, so parallelism depends on available cores and resource limits enforced by the host.

### Where are security issues documented separately from general diagnostics?

Security-sensitive issues are enumerated in [`SECURITY.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/SECURITY.md) and surfaced through the same diagnostic pipeline, but with additional context for threat modeling and response coordination.