#+TITLE: Skill: Diagnostics (org-skill-diagnostics.org) #+AUTHOR: Agent #+FILETAGS: :skill:diagnostic:health: #+STARTUP: content * Overview The *Diagnostics Skill* provides the OpenCortex Agent with the capability to perform self-examinations and environment validation. By moving this logic from the harness to a skill, we enable the Agent's **Reflection Loop** to autonomously run health checks when a tool fails, transforming the Agent into a self-healing system. * Phase A: Demand (Thinking) ** The Self-Healing Invariant In a standard Lisp Machine, the system should be able to reason about its own environment. The `:run-diagnostics` capability ensures the Agent can verify its own dependency chain and XDG directory structure. ** XDG Compliance The skill strictly validates the POSIX standard paths resolved during bootstrap, ensuring no silent configuration drift occurs. * Phase B: Protocol (Success Criteria) ** Test Suite Context #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/diagnostics-tests.lisp")" ) (defpackage :opencortex-diagnostics-tests (:use :cl :fiveam :opencortex) (:export #:diagnostics-suite)) #+end_src #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/diagnostics-tests.lisp")" ) (in-package :opencortex-diagnostics-tests) #+end_src #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/diagnostics-tests.lisp")" ) (def-suite diagnostics-suite :description "Verification of the Diagnostics skill #+end_src #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/diagnostics-tests.lisp")" ) (in-suite diagnostics-suite) #+end_src ** Dependency Tests #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/tests/diagnostics-tests.lisp")" ) (test test-dependency-check-fail "Verify that missing binaries are correctly identified as failures." (let ((opencortex::*doctor-required-binaries* '("non-existent-binary-123)) (is (null (opencortex:doctor-check-dependencies))))) #+end_src * Phase C: Implementation (Build) ** Package Context #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" ) (in-package :opencortex) #+end_src ** Skill Metadata #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" ) (defparameter *skill-diagnostics* '(:name "diagnostics" :description "Performs system health checks and environment validation." :capabilities (:run-diagnostics) :type :deterministic) "Skill metadata for the Diagnostics component. #+end_src ** Global Configuration #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" ) (defvar *doctor-required-binaries* '("sbcl" "emacs" "git" "socat" "nc "List of external binaries required for full system operation. #+end_src ** Dependency Verification #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" ) (defun doctor-check-dependencies () "Verifies that required external binaries are available in the PATH via a shell probe." (let ((all-ok t)) (harness-log "DOCTOR: Checking system dependencies... (dolist (dep *doctor-required-binaries*) (let ((path (ignore-errors (uiop:run-program (list "which" dep) :output :string :ignore-error-status t)))) (if (and path (> (length path) 0)) (harness-log " [OK] Found ~a" dep) (progn (harness-log " [FAIL] Missing binary: ~a" dep) (setf all-ok nil))))) all-ok)) #+end_src ** Environment & XDG Validation #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" ) (defun doctor-check-env () "Validates XDG directories and environment configuration against the POSIX standard." (harness-log "DOCTOR: Checking XDG environment... (let ((all-ok t) (config-dir (getenv "OC_CONFIG_DIR) (data-dir (getenv "OC_DATA_DIR) (state-dir (getenv "OC_STATE_DIR) (memex-dir (getenv "MEMEX_DIR)) (flet ((check-dir (name path critical) (if (and path (> (length path) 0)) (if (uiop:directory-exists-p path) (harness-log " [OK] ~a: ~a" name path) (progn (harness-log " [FAIL] ~a directory missing: ~a" name path) (when critical (setf all-ok nil)))) (progn (harness-log " [FAIL] ~a variable not set." name) (when critical (setf all-ok nil)))))) (check-dir "Config (OC_CONFIG_DIR)" config-dir t) (check-dir "Data (OC_DATA_DIR)" data-dir t) (check-dir "State (OC_STATE_DIR)" state-dir t) (check-dir "Memex (MEMEX_DIR)" memex-dir t)) all-ok)) #+end_src ** LLM Connectivity #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" ) (defun doctor-check-llm () "Tests connectivity to primary LLM providers. Non-critical fallback allowed." (harness-log "DOCTOR: Checking LLM connectivity... (let ((openrouter-key (getenv "OPENROUTER_API_KEY)) (if (and openrouter-key (> (length openrouter-key) 0)) (progn (harness-log " [OK] OpenRouter API Key detected. t) (progn (harness-log " [WARN] No OpenRouter API Key. Falling back to local inference only. t)))) #+end_src ** Orchestration #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" ) (defun doctor-run-all () "Executes the full diagnostic suite and returns T if system is healthy." (harness-log "================================================== (harness-log " OPENCORTEX DOCTOR: Commencing Health Check (harness-log "================================================== (let ((dep-ok (doctor-check-dependencies)) (env-ok (doctor-check-env)) (llm-ok (doctor-check-llm))) (harness-log "================================================== (if (and dep-ok env-ok) (progn (harness-log " ✓ SYSTEM HEALTHY: Ready for ignition. t) (progn (harness-log " ✗ SYSTEM UNHEALTHY: Fix the errors above. nil)))) #+end_src ** CLI Entry Point #+begin_src lisp :tangle (concat (identity (getenv "INSTALL_DIR")) "/skills/org-skill-diagnostics.lisp")" ) (defun doctor-main () "Entry point for the 'doctor' CLI command." (if (doctor-run-all) (uiop:quit 0) (uiop:quit 1))) #+end_src