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

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 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 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 for schema details.

Security-Related Problems

Issues exploitable by untrusted actors—open ports, insecure defaults, privilege escalation vectors—are enumerated in 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

# 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

// 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:

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	Diagnostic command specification, JSON schema, exit codes, stable issue codes
docs/SPEC.md	Architecture including MCP concurrency and delegation behavior
docs/SESSION_REFERENCE_ARCHITECTURE.md	Real-world issue examples and surfacing patterns
REASONIX.md	Core conventions including TODO/HACK markers for issue tracking
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: 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 and surfaced through the same diagnostic pipeline, but with additional context for threat modeling and response coordination.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}