Reasonix self-diagnostics guide

This skill is inlined. Prefer evidence over guessing.

First action

1. Run a static capability report (no network, no MCP subprocesses):

reasonix doctor capabilities --json

2. Only if the user explicitly allows starting third-party MCP servers (may network and pass configured env/headers), run live probe:

reasonix doctor capabilities --live --timeout 5s --json

3. On desktop, open Settings → Diagnostics for the same report model. The desktop "include current session runtime" toggle only reads the active tab Host (connected/failed/deferred/disabled); it does not start MCP.

Do not invent auto-fixes. Surface stable issue codes, sources, and remediations from the report.

---

Skills

Config sources and priority

Winner per skill name (highest first):

1. project — <workspace>/{.reasonix,.agents,.agent,.claude}/skills/
2. custom — [skills].paths (and plugin package skill roots)
3. global — <Reasonix home>/skills and home convention dirs
4. builtin — shipped skills (including this guide)

Same name: higher scope wins; lower scopes are shadowed. [skills].disabled_skills hides a name from List/Read entirely.

Discovery conventions: .reasonix, .agents, .agent, .claude (see config.ConventionDirs). Layouts: <name>/SKILL.md or flat <name>.md (Claude flat files need skill frontmatter).

Checks

Entry	How
CLI	reasonix doctor capabilities → Skills section
Desktop	Settings → Skills; Settings → Diagnostics
Agent	/skill list, /reasonix-guide, run_skill

Symptom → cause → fix

Symptom	Likely cause	Fix
Skill missing from index	Disabled, shadowed, missing description, wrong root	Check report codes skill.shadowed, skill.missing_description, disabled list, discovery roots
Builtin overridden	Project/global same name	Rename or remove user skill; disable if intentional
Flat Claude file ignored	No skill frontmatter under .claude/skills	Add description: / runAs: frontmatter or use SKILL.md folder
Body never loads	Expected: bodies are on-demand	Invoke via /name or run_skill

Ordered triage

1. reasonix doctor capabilities --json → Skills
2. Confirm name not in disabled_skills
3. Confirm winner Path/Scope; if shadowed, inspect lower-priority roots
4. Missing description: skill may load but index placeholder is weak — add description:
5. Reopen session / Refresh Skills after config changes

---

Commands (slash templates)

Priority

config.CommandDirsForRoot: home convention commands → Reasonix home commands → project convention commands. Later directory overrides earlier on name clash (command.Load).

Name from path: git/commit.md → /git:commit (slashes → :).

Checks

CLI/Desktop Diagnostics → Commands; invoke /name in chat.

Symptom → cause → fix

Symptom	Cause	Fix
Wrong body	Shadowed by later dir	Check command.shadowed winners
Missing command	Wrong dir / extension	Place *.md under a scanned commands/ root
Parse fail	Unreadable file	Fix permissions / encoding (command.read_failed)

---

Hooks

Events (14)

PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, StopFailure, PostLLMCall, SessionStart, SessionEnd, SubagentStart, SubagentStop, Notification, PreCompact.

SubagentStart / SubagentStop:

• Only a foreground task call fires them; read_only_task, parallel_tasks, fleet, skill sub-agents and background tasks do not.
• Both carry callId to pair them. SubagentStart gets the task arguments in toolArgs.
• SubagentStop fires on every end (answer, failure, cancel, refusal); error is set when there was no answer.
• Neither can block: exit 2 only warns.

Blocking (exit 2 can gate the loop): PreToolUse, UserPromptSubmit. Others warn or contribute context only.

Sources

• Project: <workspace>/.reasonix/settings.json — loaded automatically
• Plugin packages: installed enabled packages
• Global: <Reasonix home>/settings.json (always)

Match field is an anchored regex: file does not match read_file; use .*file or *. Timeout is milliseconds (defaults 5s gating / 30s other).

Checks

/hooks, Settings → Hooks, Diagnostics → Hooks.

Symptom → cause → fix

Symptom	Cause	Fix
Project hooks silent	Wrong workspace / restart required	Confirm the project path and restart Reasonix after saving
Matcher never fires	Non-anchored assumption / bad regex	Fix match (hook.invalid_matcher)
Command missing	Empty command / missing context file	Fix settings entry
Malformed JSON	Invalid settings.json	Repair JSON (file yields no hooks, no crash)

---

MCP servers

Merge order

config.LoadForRoot merges:

1. User/project TOML [[plugins]] (higher name wins vs later sources when already defined)
2. Project .mcp.json servers not already in TOML
3. Enabled plugin packages MCP (skipped if name already defined)

Transports: stdio (default), http / streamable-http, sse. auto_start=false skips startup; nil/true = automatic. Tier eager blocks boot handshake; empty/background connects without blocking chat.

Env/header values may contain secrets — diagnostics list keys only.

Checks

Mode	Behavior
Static doctor	Config validity, command path / URL shape, start intent — no subprocess
CLI --live	Isolated Host via boot.PluginSpecsForRoot + plugin.Start; auto-start only; concurrency 4; always Close
Desktop runtime	Read active tab Host only

Symptom → cause → fix

Symptom	Cause	Fix
Not connected	auto_start=false or failed start	Enable / fix command/URL (mcp.command_not_found, mcp.start_failed)
No tools	Connected but empty tools/list	Server config or permissions (mcp.no_tools)
Wrong source	Shadowed by TOML vs .mcp.json vs package	Inspect report Source / package owner
Invalid transport	Bad type	Use stdio/http/sse (mcp.invalid_transport)

---

Plugin packages

Manifests

• Native: reasonix-plugin.json
• Codex: .codex-plugin/plugin.json
• Claude: .claude-plugin/plugin.json (+ limited Claude compatibility paths)

State: <Reasonix home>/plugin-packages.json. Disabled packages do not contribute skills/hooks/MCP.

Unmapped Claude-only features may appear as compatibility warnings — Reasonix does not invent support.

Checks

reasonix plugin doctor <name>, Settings → Plugins, Diagnostics → Plugins.

Symptom → cause → fix

Symptom	Cause	Fix
Package missing	Bad root path	Reinstall / fix root (plugin.missing_root)
Invalid manifest	Parse failure	Fix JSON/manifest (plugin.invalid_manifest)
Skills missing	Disabled package	Enable package

---

Instructions (AGENTS.md / REASONIX.md)

Load order (ascending specificity)

User global docs → ancestor chain → project docs → project-local (*.local.md).

Recognized names: REASONIX.md, AGENTS.md, CLAUDE.md (and *.local.md variants). Multiple files in one directory can load; symlink identity is deduped.

Instructions fold into the system prompt at session boot (cache-stable prefix); Hooks remain runtime event handlers loaded from their configured locations.

Checks

Diagnostics → Instructions; memory Settings; read files on disk.

Symptom → cause → fix

Symptom	Cause	Fix
Guidance ignored	Wrong filename / empty file	Use recognized names under correct dir
Wrong scope won	Local override	Check load order in report

---

Desktop Diagnostics page

• Static report on open; Refresh re-runs static collect
• Copy redacted JSON
• Optional session runtime merge (read-only Host)
• Jump to Settings for MCP / Skills / Plugins / Hooks when issue settings_tab is set
• Never auto-edit config, execute hooks, or auto-reconnect from this page

---

Safety

• Prefer static diagnostics
• Live MCP may run third-party code and network
• Do not print tokens, header values, env values, URL query strings, usernames, or machine-absolute external paths
• Report paths as <workspace>/…, ~/…, or <external>/…